Location: Using Maps Services and Information such as geocode, place, and route in Tizen Applications

The tutorial demonstrates how you can use Maps API in Tizen Applications.

Two Maps Providers are supported: +

HERE Maps based on HERE REST API
MapQuest based on Open MapQuest API

A user have to get access key of Maps Providers from developer sites

Note that Maps Service must be used under "Term of Use" of Maps Service Providers.

+ +

Warm-up

Become familiar with Location Maps API basics by learning about:

Initializing the Maps Service +
Select Maps Provider, check available capabilities, fulfill the + prerequisites, creates the instance of Maps Service and destroys it + when no longer needed.
Using Geocode and Reverse Geocode Services +
Getting the Geocode of a specified place and Reverse Geocode, + corresponding to the specified geographical coordinates.
Using Place Search Service +
Searching for places near a specified geographical position or inside + specified geographical area.
Using Routing Service +
Querying the route from point A to point B, optionally, passing through + a number of specified way points.
Canceling the Service request

+ +

Follow-up

Once we have learned the basics of the Location Maps API, we can now move on + to other useful tasks, including:

Recognizing Address information +
Parsing the information, obtained from Geocode Service.
Recognizing Place information +
Parsing the information, obtained from Place Search Service.
Recognizing Route information +
Parsing the information, obtained from Routing Service.
Tuning API requests with preferences +
Preparing and sending via API request a set of extra preferences, allowing the + Maps Provider to generate more accurate result.

+ + +

Show All
Hide All

+ +

Initializing the Maps Service

+ Hide +

Using Maps API in maps-aware application requires:

Selecting one of available Maps Providers,
+
Creating the Maps Service, relying on the selected Maps Provider,
+
Setting Maps Provider access key and other preferences,
+
Using Maps Services requests (Geocode, Place Search, Routing),
+
Destroying Maps Service.
+

This Section explains steps 1, 2, 3 and 5. Step 4 is explained in further Sections.

+
+

Below demonstrated how to start using the Maps Service and API.

To use the features of Location Maps API, include the + <maps_service.h> + header file in your application:
+
```
#include <maps_service.h>
```
+

Maps Service instance is relying on a particular Maps Provider. In order to get the list of available + Maps Providers use + maps_service_foreach_provider():

+static bool _maps_service_provider_info_cb(char* maps_provider, void* user_data)
+{
+	/* Handle the Maps Provider name, passed as maps_provider */
+	return bool;
+}
+
+void get_available_providers()
+{
+	void *user_data = NULL;
+	const int error = maps_service_foreach_provider(
+		_maps_service_provider_info_cb, user_data);
+
+	if(error == MAPS_ERROR_NONE) {
+		/* Chose one of providers from the available_providers vector */
+	} else {
+		/* Handle error */
+	}
+}
+

Create an instance of Maps Service using the + maps_service_create() function before you use Maps API.

+maps_service_h maps = NULL;
+int error = maps_service_create("Maps Provider", &maps);
+

Set the security key, appropriate to selected Maps Provider using + maps_service_set_provider_key().
+
```
+error = maps_service_set_provider_key(maps, "XXXYYYZZZ");
+								
```
+

Check which services are supported by selected Maps Provider using + maps_service_provider_is_service_supported().

+bool supported = false;
+
+/* Check if Routing is available */
+error = maps_service_provider_is_service_supported(maps,
+	MAPS_SERVICE_SEARCH_ROUTE, &supported);
+const bool is_routing_supported =
+	(error == MAPS_ERROR_NONE) ? supported : false;
+
+/* Check if Routing via specified waypoints is available */
+error = maps_service_provider_is_service_supported(maps,
+	MAPS_SERVICE_SEARCH_ROUTE_WAYPOINTS, &supported);
+const bool is_routing_waypoints_supported =
+	(error == MAPS_ERROR_NONE) ? supported : false;
+

To check other services availability follow the same approach using keys from + maps_service_e:

MAPS_SERVICE_GEOCODE
MAPS_SERVICE_GEOCODE_INSIDE_AREA
MAPS_SERVICE_GEOCODE_BY_STRUCTURED_ADDRESS
MAPS_SERVICE_REVERSE_GEOCODE
MAPS_SERVICE_SEARCH_PLACE
MAPS_SERVICE_SEARCH_PLACE_BY_AREA
MAPS_SERVICE_SEARCH_PLACE_BY_ADDRESS
MAPS_SERVICE_CANCEL_REQUEST

Optionally, check which data features are available for desired services using + maps_service_provider_is_data_supported().

+/* Check if route path data is supported */
+error = maps_service_provider_is_data_supported(maps, MAPS_ROUTE_PATH,
+						&supported);
+const bool is_route_path_supported =
+	(error == MAPS_ERROR_NONE) ? supported : false;
+if(is_route_path_supported) {
+	/* Allow route path usage */
+}
+
+/* Check if maneuver path data is supported */
+error = maps_service_provider_is_data_supported(maps, MAPS_ROUTE_SEGMENTS_PATH,
+						&supported);
+const bool is_route_segment_path_supported =
+	(error == MAPS_ERROR_NONE) ? supported : false;
+if(is_route_segment_path_supported) {
+	/* Allow segment path usage */
+}
+
+/* Check if maneuver sements data is supported */
+error = maps_service_provider_is_data_supported(maps,
+				MAPS_ROUTE_SEGMENTS_MANEUVERS, &supported);
+const bool is_route_segment_maneuvers_supported =
+	(error == MAPS_ERROR_NONE) ? supported : false;
+if(is_route_segment_maneuvers_supported) {
+	/* Allow segment maneuvers usage */
+}
+

To check other data features availability follow the same approach using keys from + maps_service_data_e:

MAPS_PLACE_ADDRESS
MAPS_PLACE_RATING
MAPS_PLACE_CATEGORIES
MAPS_PLACE_ATTRIBUTES
MAPS_PLACE_CONTACTS
MAPS_PLACE_EDITORIALS
MAPS_PLACE_REVIEWS
MAPS_PLACE_IMAGE
MAPS_PLACE_SUPPLIER
MAPS_PLACE_RELATED

Set general preferences, such as language and distance units using + maps_service_set_preference().

+/* Create an instance of a preference set */
+maps_preference_h preference = NULL;
+int error = maps_preference_create(&preference);
+if(error != MAPS_ERROR_NONE) {
+	/* Handle error */
+}
+
+/* Set the distance units preference */
+error = maps_preference_set_distance_unit(preference, MAPS_DISTANCE_UNIT_M);
+if(error != MAPS_ERROR_NONE) {
+	/* Handle error */
+}
+
+/* Set the language preference */
+error = maps_preference_set_language(preference, "en-US");
+if(error != MAPS_ERROR_NONE) {
+	/* Handle error */
+}
+
+/* Apply the set of preferences for Maps Service */
+error = maps_service_set_preference(maps, preference);
+if(error != MAPS_ERROR_NONE) {
+	/* Handle error */
+}
+
+/* Destroy the instance of the preference set */
+error = maps_preference_destroy(preference);
+if(error != MAPS_ERROR_NONE) {
+	/* Handle error */
+}
+

Optionally you can set the maximum amount of search results and default country code + using maps_preference_set_max_results() + and maps_preference_set_country_code() respectively.

In order to set Maps Provider specific preferences use + maps_preference_set_property() + with key-value pairs, defined in the appropriate Maps Provider documentation.

To get preferences, currently applied in the Maps Provider use following functions:

maps_preference_get_distance_unit()
maps_preference_get_language()
maps_preference_get_max_results()
maps_preference_get_country_code()
maps_preference_get() and + maps_preference_foreach_property()

The former pair of functions retrieve the Maps Provider specific preferences, not defined in the Maps API.

+ +

Using Geocode and Reverse Geocode Services

+ Hide +

To retrieve a geocode of a specified place, or the place information, corresponding to a given + geographical coordinates, use one of approaches, listed in this Section.

Note that each API request may be tuned as it is demonstrated in the section Tuning API requests with preferences.

Note that to perform these operations, your application needs the http://tizen.org/privilege/internet privilege.

+
+

Usage of Geocode API is demonstrated below.

Request the geocode by free formed address using + maps_service_geocode().

+/* Searching for geocode of the
+ * Samsung'c campus "Digital City" in Suwon */
+error = maps_service_geocode(maps,
+	"Suwon, Digital City",
+	preference,
+	__maps_service_geocode_cb,
+	user_data,
+	&request_id);
+
+if(error != MAPS_ERROR_NONE) {
+	/* Handle Error */
+}
+

Request the geocode inside a specified area using + maps_service_geocode_inside_area().

+maps_area_h bounds = NULL;
+/* Use maps_area_create_rectangle() or maps_area_create_circle()
+ * to create a geographical bounds of Geocoding */
+
+/* Searching for geocode of the
+ * Samsung's campus Digital City
+ * within a specified geographical area */
+error = maps_service_geocode_inside_area(maps,
+	"Digital City",
+	bounds,
+	preference,
+	__maps_service_geocode_cb,
+	user_data,
+	&request_id);
+
+if(error != MAPS_ERROR_NONE) {
+	/* Handle Error */
+}
+

Request the geocode for a place, specified as a structured address using + maps_service_geocode_by_structured_address().

+maps_address_h address = NULL;
+/* Use maps_address_create() to create an instance of an address
+ * Than use maps_address_set_xxx to initialize the address
+ * with desired values */
+
+/* Searching for a geocode of a place, specified with a structured address */
+error = maps_service_geocode_by_structured_address(maps,
+	address,
+	preference,
+	__maps_service_geocode_cb,
+	user_data,
+	&request_id);
+
+if(error != MAPS_ERROR_NONE) {
+	/* Handle Error */
+}
+

+ + +

The callback + __maps_service_geocode_cb should be implemented as following:

+static bool __maps_service_geocode_cb(maps_error_e result, int request_id,
+	int index, int total, maps_coordinates_h coordinates,
+	void* user_data)
+{
+
+	/* Handle obtained coordinates data */
+
+	/* Release results */
+	maps_coordinates_destroy(coordinates);
+	return true;
+}
+

+ +
+

Usage of Reverse Geocode API is demonstrated below.

To retrieve a reverse geocode of a specified geographical coordinates, use + maps_service_reverse_geocode().

+/* Obtaining the reverse geocode with a specified coordinates */
+error = maps_service_reverse_geocode(maps,
+	37.257865,
+	127.053659,
+	preference,
+	__maps_service_reverse_geocode_cb,
+	user_data,
+	&request_id);
+
+if(error != MAPS_ERROR_NONE) {
+	/* Handle Error */
+}
+

The callback + __maps_service_reverse_geocode_cb should be implemented as following:

+static void __maps_service_reverse_geocode_cb(maps_error_e result,
+	int request_id, int index, int total, maps_address_h address,
+	void* user_data)
+{
+
+	/* Handle obtained address */
+
+	/* Release results */
+	maps_address_destroy(address);
+}
+

Using Place Search Services

+ Hide +

To search for a place accordingly to a diversity of searching parameters, use one of approaches, listed in + this Section.

Note that each API request may be tuned as it is demonstrated in the Section Tuning API requests with preferences.

Note that to perform these operations, your application needs the http://tizen.org/privilege/internet privilege.

Search the place within a specified distance around the center coordinates using + maps_service_search_place().

+maps_coordinates_h position = NULL;
+/* Create coordinates with maps_coordinates_create() */
+
+int distance = 500;
+error = maps_service_search_place(maps,
+	position,
+	distance,
+	filter,
+	preference,
+	__maps_service_search_place_cb,
+	user_data,
+	&request_id);
+
+if(error != MAPS_ERROR_NONE) {
+	/* Handle Error */
+}
+

Search the place within a specified geographical boundary using + maps_service_search_place_by_area().

+maps_area_h boundary = NULL;
+/* Create boundary with one of:
+ * - maps_area_create_rectangle()
+ * - maps_area_create_circle() */
+
+error = maps_service_search_place_by_area(maps,
+	boundary,
+	filter,
+	preference,
+	__maps_service_search_place_cb,
+	user_data,
+	&request_id);
+
+if(error != MAPS_ERROR_NONE) {
+	/* Handle Error */
+}
+

Search the place by address within a specified geographical boundary using + maps_service_search_place_by_address().

+maps_area_h boundary = NULL;
+/* Create boundary with one of:
+ * - maps_area_create_rectangle()
+ * - maps_area_create_circle() */
+
+error = maps_service_search_place_by_address(maps,
+	"Digital City",
+	boundary,
+	filter,
+	preference,
+	__maps_service_search_place_cb,
+	user_data,
+	&request_id);
+
+if(error != MAPS_ERROR_NONE) {
+	/* Handle Error */
+}
+

The callback + __maps_service_search_place_cb() should be implemented as following:

+static bool __maps_service_search_place_cb(maps_error_e error, int request_id,
+	int index, int total, maps_place_h place, void* user_data)
+{
+
+	/* Handle obtained place data */
+
+	/* Release results */
+	maps_place_destroy(place);
+	return true;
+}
+

Using Using Routing Service

+ Hide +

To query a route from point A to point B use one of approaches, listed in this Section.

Note that each API request may be tuned as it is demonstrated in the Section Tuning API requests with preferences.

Note that to perform these operations, your application needs the http://tizen.org/privilege/internet privilege.

Simply query the route from one geographical coordinates to another using + maps_service_search_route().

+maps_coordinates_h origin = NULL, destination = NULL;
+/* Create coordinates with maps_coordinates_create() */
+
+error = maps_service_search_route(maps,
+	origin,
+	destination,
+	preference,
+	__maps_service_search_route_cb,
+	user_data,
+	&request_id);
+
+if(error != MAPS_ERROR_NONE) {
+	/* Handle Error */
+}
+

Query the route passing through a specified set of way points using + maps_service_search_route_waypoints().

+/* Specify amount of way points */
+const int waypoint_num = 5;
+
+/* Create array with coordinates of way points */
+maps_coordinates_h* waypoint_list = NULL;
+
+error = maps_service_search_route_waypoints(maps,
+	waypoint_list,
+	waypoint_num,
+	preference,
+	__maps_service_search_route_cb,
+	user_data,
+	&request_id);
+
+if(error != MAPS_ERROR_NONE) {
+	/* Handle Error */
+}
+

The callback + __maps_service_search_route_cb() should be implemented as following:

+static bool __maps_service_search_route_cb(maps_error_e error, int request_id,
+	int index, int total, maps_route_h route, void* user_data)
+{
+
+	/* Handle obtained route data */
+
+	/* Release results */
+	maps_route_destroy(route);
+	return true;
+}
+

Canceling the Service Request

+ Hide +

To cancel a Geocode, Place Search or Routing request use maps_service_cancel_request().

+/* Cancel the request with a specified id */
+error = maps_service_cancel_request(maps, request_id);
+
+if(error != MAPS_ERROR_NONE) {
+	/* Handle Error */
+}
+

+ +

+
+
Recognizing Address information
+ Hide +
+
+
The Reverse Geocode request is run with maps_service_reverse_geocode() (see + section Using Geocode and Reverse Geocode Services).
+
The result is retrieved from the Maps Service via maps_service_reverse_geocode_cb + callback as a structured address data of the specified place.
+
Parse the address information using following functions:
+
```
+/* Obtain building number */
+char *building_number = NULL;
+error = maps_address_get_building_number(address, &building_number);
+
+if(error != MAPS_ERROR_NONE) {
+	/* Handle Error */
+}
+
+/* Use building_number */
+
+free(building_number);
+
+/* Obtain street name */
+char *street = NULL;
+error = maps_address_get_street(address, &street);
+
+if(error != MAPS_ERROR_NONE) {
+/* Handle Error */
+}
+
+/* Use street */
+
+free(street);
+							
```
+
Similarly get other address features using:
+
- maps_address_get_district()
  +
- maps_address_get_city()
  +
- maps_address_get_state()
  +
- maps_address_get_country()
  +
- maps_address_get_country_code()
  +
- maps_address_get_county()
  +
- maps_address_get_postal_code()
  +
- maps_address_get_freetext()
  +
+
+
+
+
Recognizing Place information
+ Hide +
+
+
The place search request is run with maps_service_search_place() , + maps_service_search_place_by_area() or + maps_service_search_place_by_address() + (see section Using Place Search Services).
+
The result is retrieved from the Maps Service via multiple iterations of + maps_service_search_place_cb callback with an instance + of place data passed into.
+
The place data can be managed with a handle of type maps_place_h.
+
Different Maps Providers are capable to provide different sets of place data features and below is demonstrates + how to check ahead if a specified feature is available with your Maps Provider.
+
Some Maps Providers may extend place data features with extra properties that are not specified in the Maps API. + Such properties are organized as a key-value storage where keys are the names of the properties. + The method of iterating through extra properties of place data is demonstrated in the end of this section.
+
+
To get particular features of the place information, such as place name, location and rating, use following functions. +
1. To obtaining the place name use + maps_place_get_name().
  +
```
+/* Obtain place name */
+char *name = NULL;
+error = maps_place_get_name(place, &name);
+if(error != MAPS_ERROR_NONE) {
+/* Handle Error */
+}
+
+/* Use place name */
+
+free(name);
+								
```
  +
2. To obtaining the place location use + maps_place_get_location().
  +
```
+/* Obtain place location */
+maps_coordinates_h location = NULL;
+error = maps_place_get_location(place, &location);
+if(error != MAPS_ERROR_NONE) {
+	/* Handle Error */
+}
+
+/* Use route location */
+
+maps_coordinates_destroy(location);
+								
```
  +
3. To obtaining the place rating use + maps_place_get_rating().
  +
```
+/* Obtain place rating */
+maps_place_rating_h rating = NULL;
+error = maps_place_get_rating(place, &rating);
+if(error != MAPS_ERROR_NONE) {
+	/* Handle Error */
+}
+
+/* Use route rating */
+
+maps_place_rating_destroy(rating);
+								
```
  +
+
To obtain other place features follow the same approach using functions:
+
- maps_place_get_id()
  +
- maps_place_get_address()
  +
- maps_place_get_distance()
  +
- maps_place_get_uri()
  +
- maps_place_get_supplier_link()
  +
- maps_place_get_related_link()
  +
+ +
+
To get lists of features of the place information, such as categories, reviews and attributes, use following iterating functions.
+
1. To obtaining the list of place categories use + maps_place_foreach_category().
  +
```
+/* Obtain a list of place categories */
+error = maps_place_foreach_category(place, __maps_place_categories_cb,
+	user_data);
+if(error != MAPS_ERROR_NONE) {
+	/* Handle Error */
+}
+								
```
  +
2. The callback + __maps_place_categories_cb() should be implemented as following:
  +
```
+static bool __maps_place_categories_cb(int index, int total,
+	maps_place_category_h category, void* user_data)
+{
+
+	/* Handle obtained place category data */
+
+	/* Release results */
+	maps_place_category_destroy(category);
+	return true;
+}
+								
```
  +
+
To obtain other place feature lists follow the same approach using functions:
+
- maps_place_foreach_attribute
  +
- maps_place_foreach_contact
  +
- maps_place_foreach_editorial
  +
- maps_place_foreach_image
  +
- maps_place_foreach_review
  +
+ +
+
Some place data features may not be supported by your Maps Provider.
+
For example, the Maps Providers may not support place rating data. In this case the function + maps_place_get_rating() will return error + code MAPS_ERROR_NOT_SUPPORTED and the value of + output parameter rating will be meaningless.
+
As mentioned in the section Initializing the Maps Services, you can check ahead which + data features are available in your Maps Provider + using maps_service_provider_is_data_supported().
+
```
+/* Check if route path data is supported */
+bool is_place_rating_supported = false;
+error = maps_service_provider_is_data_supported(maps,
+	MAPS_PLACE_RATING, &is_place_rating_supported);
+
+if(error == MAPS_ERROR_NONE) {
+	if(is_place_rating_supported) {
+
+		/* Obtain place rating */
+	        maps_place_rating_h rating = NULL;
+		error = maps_place_get_rating(place, &rating);
+		if(error != MAPS_ERROR_NONE) {
+			/* Handle Error */
+		}
+
+		/* Use route name */
+
+		maps_place_rating_destroy(rating);
+	}
+} else {
+	/* Handle Error */
+}
+							
```
+ +
+
Some Maps Providers may extend place data features defined in Maps API with specific extra properties.
+
1. To iterate through retrieved extra properties use + maps_place_foreach_property().
  +
```
+/* Obtain Maps Provider specific place data properties */
+error = maps_place_foreach_property(place, __maps_place_properties_cb,
+	user_data);
+if(error != MAPS_ERROR_NONE) {
+	/* Handle Error */
+}
+								
```
  +
2. The callback + __maps_place_properties_cb() should be implemented as following:
  +
```
+static bool __maps_place_properties_cb(int index, int total,
+	char* key, void* value, void* user_data)
+{
+
+	/* Handle obtained a property:
+	 * property_name: key
+	 * property_value: value */
+
+	/* Release property name and value */
+	free(key);
+	free(value);
+	return true;
+}
+								
```
  +
+ +
+

Recognizing Route information

+ Hide +

The route calculation request is run with maps_service_search_route() or + maps_service_search_route_waypoints() (see + section Using Routing Service). + The result is retrieved from the Maps Service via multiple iterations of + maps_service_search_route_cb callback with an instance of route data passed into. + The route data can be managed with a handle of type maps_route_h.

Different Maps Providers are capable to provide different sets of route data features and below is demonstrated + how to check ahead if a specified feature is available with your Maps Provider.

Some Maps Providers may extend route data features with extra properties that are not specified in the Maps API. Such properties are organized as a + key-value storage where keys are the names of the properties. + The method of iterating through extra properties of place data is demonstrated in the end of this section.

+
+

To get particular features of the route information, such as route id, origin, destination and total distance, use following functions. +

To obtaining the route id use + maps_route_get_route_id().

+/* Obtain route id */
+char *id = NULL;
+error = maps_route_get_route_id(route, &id);
+if(error != MAPS_ERROR_NONE) {
+	/* Handle Error */
+}
+
+/* Use route id */
+
+free(id);
+

To obtaining the route origin and destination use + maps_route_get_origin() and + maps_route_get_destination() respectively.

+/* Obtain route origin and destination */
+maps_coordinates_h origin = NULL, destination = NULL;
+error = maps_route_get_origin(route, &origin);
+if(error != MAPS_ERROR_NONE) {
+	/* Handle Error */
+}
+error = maps_route_get_destination(route, &destination);
+if(error != MAPS_ERROR_NONE) {
+	/* Handle Error */
+}
+
+/* Use route origin and destination */
+
+maps_coordinates_destroy(origin);
+maps_coordinates_destroy(destination);
+

To obtaining the route total distance use + maps_route_get_total_distance().

+/* Obtain route total distance */
+double total_distance = .0;
+error = maps_route_get_total_distance(route, &total_distance);
+if(error != MAPS_ERROR_NONE) {
+	/* Handle Error */
+}
+/* Use route total distance */
+

To obtain other place features follow the same approach using functions:

maps_route_get_bounding_box()
+
maps_route_get_transport_mode()
+
maps_route_get_total_duration()
+
maps_route_get_distance_unit()
+
maps_place_get_supplier_link()
+
maps_place_get_related_link()
+

+
+

To get lists of features of the route information, such as path or list of segments, use following iterating functions.

To obtaining the list of geographical points, defining the route, use + maps_route_foreach_path().

+error = maps_route_foreach_path(route, __maps_route_path_cb, user_data);
+if(error != MAPS_ERROR_NONE) {
+	/* Handle Error */
+}
+

The callback + __maps_route_path_cb() should be implemented as following:

+static bool __maps_route_path_cb(int index, int total,
+	maps_coordinates_h coordinates, void* user_data)
+{
+
+	/* Handle obtained coordinates of route path */
+
+	/* Release results */
+	maps_coordinates_destroy(coordinates);
+	return true;
+}
+

To obtaining the list of route segment use + maps_route_foreach_segment().

+error = maps_route_foreach_segment(route, __maps_route_segment_cb, user_data);
+if(error != MAPS_ERROR_NONE)
+{
+	/* Handle Error */
+}
+

The callback + __maps_route_segment_cb() should be implemented as following:

+static bool __maps_route_segment_cb(int index, int total,
+	maps_route_segment_h segment, void* user_data)
+{
+
+	/* Handle obtained segment of route */
+
+	/* Release results */
+	maps_route_segment_destroy(segment);
+	return true;
+}
+

+
+

Different Maps Providers may provide the route data in different ways.

For example, one Maps Provider may represent the route as a list of geographical coordinates while another may define it as a list of segments. + Attempt to get unsupported features will causse error code MAPS_ERROR_NOT_SUPPORTED. + To check which features of route data is valuable use maps_service_provider_is_data_supported() as mentioned in + section Initializing the Maps Services. +

To obtain route path use following: + maps_route_foreach_path().

+/* Check if route path data is supported */
+bool is_route_path_supported = false;
+error = maps_service_provider_is_data_supported(maps,
+	MAPS_ROUTE_PATH, &is_route_path_supported);
+
+if(error == MAPS_ERROR_NONE) {
+	if(is_route_path_supported) {
+
+		/* Obtain route path */
+		error = maps_route_foreach_path(route, __maps_route_path_cb,
+								user_data);
+		if(error != MAPS_ERROR_NONE) {
+			/* Handle Error */
+		}
+	}
+} else {
+	/* Handle Error */
+}
+

To obtain route segments use following: + maps_route_foreach_path().

+/* Check if route segment data is supported */
+
+bool is_route_segment_path_supported = false;
+error = maps_service_provider_is_data_supported(maps,
+	MAPS_ROUTE_SEGMENTS_PATH, &is_route_segment_path_supported);
+
+bool is_route_segment_maneuvers_supported = false;
+error = maps_service_provider_is_data_supported(maps,
+	MAPS_ROUTE_SEGMENTS_MANEUVERS, &is_route_segment_maneuvers_supported);
+
+if(error == MAPS_ERROR_NONE) {
+	if(is_route_segment_path_supported
+		|| is_route_segment_maneuvers_supported) {
+
+		/* Obtain route segments */
+		error = maps_route_foreach_segment(route,
+				__maps_route_segment_cb, user_data);
+		if(error != MAPS_ERROR_NONE) {
+			/* Handle Error */
+		}
+	}
+} else {
+	/* Handle Error */
+}
+

+
+

Some Maps Providers may extend route data features defined in Maps API with specific extra properties.

To iterate through retrieved extra properties use + maps_route_foreach_property().

+/* Obtain Maps Provider specific route data properties */
+error = maps_route_foreach_property(route, __maps_route_properties_cb,
+	user_data);
+if(error != MAPS_ERROR_NONE) {
+	/* Handle Error */
+}
+

The callback + __maps_route_properties_cb() should be implemented as following:

+static bool __maps_route_properties_cb(int index, int total,
+	char* key, void* value, void* user_data)
+{
+
+	/* Handle obtained a property:
+	 * property_name: key
+	 * property_value: value */
+
+	/* Release property name and value */
+	free(key);
+	free(value);
+	return true;
+}
+

Tuning API requests with preferences

+ Hide +

All Maps API requests may be tuned with additional set of preferences.

Preparing and sending the preference parameter via API request + allows the Maps Provider to generate more accurate results.

+ +

To prepare preferences for Place Search Service use + maps_preference_set_property() with following keys:

MAPS_PLACE_FILTER_TYPE
+
MAPS_PLACE_FILTER_SORT_BY
+

The example from the section Using Place Search Services may be edited as following:

+/* Create extra preferences for Place Search Service */
+error = maps_preference_create(&preference);
+if(error != MAPS_ERROR_NONE) {
+	/* Handle Error */
+}
+error = maps_preference_set_property(preference, MAPS_PLACE_FILTER_TYPE, "restaurant");
+if(error != MAPS_ERROR_NONE) {
+	/* Handle Error */
+}
+
+maps_coordinates_h position = NULL;
+/* Create coordinates with maps_coordinates_create() */
+
+int distance = 500;
+error = maps_service_search_place(maps,
+	position,
+	distance,
+	filter,
+	preference,
+	__maps_service_search_place_cb,
+	user_data,
+	&request_id);
+
+if(error != MAPS_ERROR_NONE) {
+	/* Handle Error */
+}
+
+maps_preference_destroy(preference);
+

To prepare preferences for Routing Service use following functions: +

maps_preference_set_route_optimization()
+
maps_preference_set_route_transport_mode()
+
maps_preference_set_route_feature_weight()
+
maps_preference_set_route_feature()
+

Also use maps_preference_set_property() with following keys:

MAPS_ROUTE_FREEFORM_ADDR_TO_AVOID
+
MAPS_ROUTE_STRUCTED_ADDR_TO_AVOID
+
MAPS_ROUTE_CIRCLE_AREA_TO_AVOID
+
MAPS_ROUTE_RECT_AREA_TO_AVOID
+
MAPS_ROUTE_GEOMETRY_BOUNDING_BOX
+
MAPS_ROUTE_GEOMETRY_RETRIEVAL
+
MAPS_ROUTE_INSTRUCTION_GEOMETRY
+
MAPS_ROUTE_INSTRUCTION_BOUNDING_BOX
+
MAPS_ROUTE_INSTRUCTION_RETRIEVAL
+
MAPS_ROUTE_REALTIME_TRAFFIC
+

+ +

The example from the section Using Routing Service may be edited as following:

+/* Create extra preferences for Place Search Service */
+error = maps_preference_create(&preference);
+if(error != MAPS_ERROR_NONE) {
+	/* Handle Error */
+}
+error = maps_preference_set_property(preference, MAPS_ROUTE_FREEFORM_ADDR_TO_AVOID, "Suwon, Digital City");
+if(error != MAPS_ERROR_NONE) {
+	/* Handle Error */
+}
+error = maps_preference_set_route_optimization(preference, MAPS_ROUTE_TYPE_SHORTEST);
+if(error != MAPS_ERROR_NONE) {
+	/* Handle Error */
+}
+
+maps_coordinates_h origin = NULL, destination = NULL;
+/* Create coordinates with maps_coordinates_create() */
+
+error = maps_service_search_route(maps,
+	origin,
+	destination,
+	preference,
+	__maps_service_search_route_cb,
+	user_data,
+	&request_id);
+
+if(error != MAPS_ERROR_NONE) {
+	/* Handle Error */
+}
+
+maps_preference_destroy(preference);
+

In case of specific preferences, required by your Maps Provider, use + maps_preference_set_property() with key-value pairs, + defined in the appropriate Maps Provider documentation. +

+ + + + +

Native Application

Maps

Maps Service

Maps Features

Privacy Policy

Maps Settings

Location: Using Maps Services and Information such as geocode, place, and route in Tizen Applications

Warm-up

Follow-up

Initializing the Maps Service

Using Geocode and Reverse Geocode Services

Using Place Search Services

Using Using Routing Service

Canceling the Service Request

Recognizing Address information

Recognizing Place information

Recognizing Route information

Tuning API requests with preferences