How to Use the Tizen Native Place API in 4 Steps
PUBLISHED
Since Tizen 2.4
What is the Place API?
The Place API allows you to discover and explore point of interest (POI) information.
The Place API is one of the Maps Services provided by the Tizen Native Location Framework.
To start using the Place API:
- Create an empty Tizen native application.
- Start the Maps Service.
- Prepare a place search filter.
- Run a place request.
Prerequisites
This document assumes that you already have basic knowledge in Tizen development. For basic information, see https://developer.tizen.org/development/getting-started/preface.
The Maps Service API requires a security key issued by the maps provider.
In case of HERE maps, the security key is a concatenation of app_id
and app_code
, generated on https://developer.here.com/plans/api/consumer-mapping according to your consumer plan.
“your-security-key” is “app_id/app_code”
To ensure the Maps Service API execution, set the following privileges:
http://tizen.org/privilege/mapservice
http://tizen.org/privilege/internet
http://tizen.org/privilege/network.get
1 Create an Empty Tizen Native Application
In the IDE, create an empty application using the basic UI application template, and run it on an emulator or a device.
The "Hello Tizen" label appears on the screen at application startup.
2 Start the Maps Service
To start the Maps Service:
- Include the Maps Service API header file in your application:
#include <maps_service.h>
Note This inclusion allows you to use all native Maps Service API functions and features. For more details, see https://developer.tizen.org/development/api-references/, and go to 2.4 API References -> Native Application -> Mobile Native -> Native API Reference -> Location -> Maps Service. - Add a Maps Service handle to the
appdata_s
structure:
typedef struct appdata { Evas_Object *win; Evas_Object *conform; Evas_Object *label; maps_service_h maps; // Maps Service handle } appdata_s;
- Create the Maps Service instance in the
app_create()
function:
static bool app_create(void *data) { appdata_s *ad = data; create_base_gui(ad); // Specify the maps provider name if (maps_service_create("HERE", &ad->maps) != MAPS_ERROR_NONE) return false; // Set the security key issued by the maps provider maps_service_set_provider_key(ad->maps, "your-security-key"); return true; }
- When no longer needed, destroy the Maps Service instance in the
app_terminate()
function:
static void app_terminate(void *data) { // Release all resources appdata_s *ad = data; maps_service_destroy(ad->maps); }
3 Prepare a Place Search Filter
Prepare a search filter to query for places of the "transport" category in the app_create()
function:
maps_place_filter_h filter = NULL; maps_place_category_h category = NULL; maps_coordinates_h coords = NULL; // Create a place search filter maps_place_filter_create(&filter); // Create a transport category maps_place_category_create(&category); maps_place_category_set_id(category, "transport"); // Set the place category to the search filter maps_place_filter_set_category(filter, category); // Create the central coordinates of the search area maps_coordinates_create(41.9, 12.5, &coords);
4 Run a Place Request
To run a place request:
- Add the place request into the
app_create()
function:// Use the Place API int request_id = 0; maps_service_search_place(ad->maps, coords, 500, filter, NULL, search_place_cb, ad, &request_id);
After creating the request, release any temporary data:
maps_coordinates_destroy(coords); maps_place_category_destroy(category); maps_place_filter_destroy(filter);
- Implement the place callback:
static bool search_place_cb(maps_error_e error, int request_id , int index, int total, maps_place_h place, void *user_data) { char *name = NULL; int distance = 0; maps_place_get_name(place, &name); maps_place_get_distance(place, &distance); char place_info[0x80] = {0}; snprintf(place_info, 0x80, "Place \"%s\" is in %d meters", name, distance); appdata_s *ad = user_data; elm_object_text_set(ad->label, place_info); // Release the place handle maps_place_destroy(place); free(name); // If return true, you receive other places, // corresponding to the search parameters // In this example, 1 place is enough return false; }
- Run the application.
At first, the familiar "Hello Tizen" line appears. A moment later, however, it changes to "Place "Stazione Termini" is in 152 meters".
This indicates the transportation place is the Stazione Termini station in Rome.