--- /dev/null
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+<meta http-equiv="content-type" content="text/html; charset=utf-8" />
+<meta http-equiv="X-UA-Compatible" content="IE=9" />
+<link rel="stylesheet" type="text/css" href="../../css/styles.css" />
+<link rel="stylesheet" type="text/css" href="../../css/snippet.css" />
+<script type="text/javascript" src="../../scripts/snippet.js"></script>
+<script type="text/javascript" src="../../scripts/jquery.util.js" charset="utf-8"></script>
+<script type="text/javascript" src="../../scripts/common.js" charset="utf-8"></script>
+<script type="text/javascript" src="../../scripts/core.js" charset="utf-8"></script>
+<script type="text/javascript" src="../../scripts/search.js" charset="utf-8"></script>
+<title>Maps: Using Maps API in Tizen Applications</title>
+</head>
+
+
+<body onload="prettyPrint()" style="overflow: auto;">
+
+
+<div id="navigation">
+ <div id="profile">
+ <p><img alt="Mobile native" src="../../images/mn_icon.png"/></p>
+ </div>
+ <div id="toc_border">
+ <div id="toc">
+ <p class="toc-title">Content</p>
+ <ul class="toc">
+ <li><a class="opensection" href="#initial">Initializing the Maps Services</a></li>
+ <li><a class="opensection" href="#geocode">Using Geocode and Reverse Geocode Services</a></li>
+ <li><a class="opensection" href="#search_place">Using Place Search Services</a></li>
+ <li><a class="opensection" href="#search_route">Using Routing Service</a></li>
+ <li><a class="opensection" href="#cancel">Canceling the Service Request</a></li>
+ <li><a class="opensection" href="#address">Recognizing Address information</a></li>
+ <li><a class="opensection" href="#place">Recognizing Place information</a></li>
+ <li><a class="opensection" href="#route">Recognizing Route information</a></li>
+ <li><a class="opensection" href="#preference">Tuning API requests with preferences</a></li>
+ </ul>
+ <p class="toc-title">Related Info</p>
+ <ul class="toc">
+ <li><a href="../../../../org.tizen.guides/html/native/location/maps_n.htm">Maps Service Guide</a></li>
+ <li><a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__MAPS_SERVICE__MODULE.html">Maps Service API for Mobile Native</a></li>
+ </ul>
+ </div>
+ </div>
+</div>
+
+
+<div id="container">
+ <div id="contents">
+ <div class="content">
+ <h1>Location: Using Maps Services and Information such as geocode, place, and route in Tizen Applications</h1>
+ <div class="cont">
+ <div class="static-cont">
+ <p>The tutorial demonstrates how you can use Maps API in Tizen Applications.</p>
+ <p>Two Maps Providers are supported:
+ <ul>
+ <li><a href="https://developer.here.com">HERE Maps</a> based on <a href="https://developer.here.com/rest-apis">HERE REST API</a></li>
+ <li><a href="http://developer.mapquest.com">MapQuest</a> based on <a href="http://open.mapquestapi.com">Open MapQuest API</a></li>
+ </ul>
+ <p>A user have to get access key of Maps Providers from developer sites</p>
+ <p>Note that Maps Service must be used under "Term of Use" of Maps Service Providers.</p>
+
+ <h2>Warm-up</h2>
+ <p>Become familiar with Location Maps API basics by learning about:</p>
+ <ul>
+ <li><a class="opensection" href="#initial">Initializing the Maps Service</a>
+ <p>Select Maps Provider, check available capabilities, fulfill the
+ prerequisites, creates the instance of Maps Service and destroys it
+ when no longer needed.</p></li>
+
+ <li><a class="opensection" href="#geocode">Using Geocode and Reverse Geocode Services</a>
+ <p>Getting the Geocode of a specified place and Reverse Geocode,
+ corresponding to the specified geographical coordinates.</p></li>
+
+ <li><a class="opensection" href="#search_place">Using Place Search Service</a>
+ <p>Searching for places near a specified geographical position or inside
+ specified geographical area.</p></li>
+
+ <li><a class="opensection" href="#search_route">Using Routing Service</a>
+ <p>Querying the route from point A to point B, optionally, passing through
+ a number of specified way points.</p></li>
+
+ <li><a class="opensection" href="#cancel">Canceling the Service request</a></li>
+ </ul>
+
+ <h2>Follow-up</h2>
+ <p>Once we have learned the basics of the Location Maps API, we can now move on
+ to other useful tasks, including:</p>
+ <ul>
+ <li><a class="opensection" href="#address">Recognizing Address information</a>
+ <p>Parsing the information, obtained from Geocode Service.</p></li>
+
+ <li><a class="opensection" href="#place">Recognizing Place information</a>
+ <p>Parsing the information, obtained from Place Search Service.</p></li>
+
+ <li><a class="opensection" href="#route">Recognizing Route information</a>
+ <p>Parsing the information, obtained from Routing Service.</p></li>
+
+ <li><a class="opensection" href="#preference">Tuning API requests with preferences</a>
+ <p>Preparing and sending via API request a set of extra preferences, allowing the
+ Maps Provider to generate more accurate result.</p></li>
+ </ul>
+
+
+ <div class="devicespecs-util mt5 clfix">
+ <ul class="dutil">
+ <li><a href="#" class="showA">Show All</a></li>
+ <li class="none"><a href="#" class="hideA">Hide All</a></li>
+ </ul>
+ </div>
+
+ <ul class="devicespecifications">
+ <li>
+ <div class="devicespec-tit">
+ <h2 id="initial" name="initial" class="items-tit-h2">Initializing the Maps Service</h2>
+ <span class="fr"><a href="#" class="bt-arr"><em>Hide</em></a></span>
+ </div>
+ <div class="devicespec-con">
+ <p>Using Maps API in maps-aware application requires:</p>
+ <ol>
+ <li><p>Selecting one of available Maps Providers,</p>
+ <li><p>Creating the Maps Service, relying on the selected Maps Provider,</p>
+ <li><p>Setting Maps Provider access key and other preferences,</p>
+ <li><p>Using Maps Services requests (Geocode, Place Search, Routing),</p>
+ <li><p>Destroying Maps Service.</p>
+ </ol>
+ <p>This Section explains steps 1, 2, 3 and 5. Step 4 is explained in further Sections.</p>
+ <br>
+ <p>Below demonstrated how to start using the Maps Service and API.</p>
+ <ol>
+ <li><p>To use the features of Location Maps API, include the
+ <span style="font-family: Courier New,Courier,monospace;"> <maps_service.h> </span>
+ header file in your application:</p>
+ <pre class="prettyprint">#include <maps_service.h></pre>
+ </li>
+
+ <li><p>Maps Service instance is relying on a particular Maps Provider. In order to get the list of available
+ Maps Providers use
+ <span style="font-family: Courier New,Courier,monospace;"> maps_service_foreach_provider()</span>:</p>
+ <pre class="prettyprint">
+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 */
+ }
+}
+ </li>
+
+ <li><p>Create an instance of Maps Service using the
+ <span style="font-family: Courier New,Courier,monospace;"> maps_service_create()</span> function before you use Maps API.</p>
+ <pre class="prettyprint">
+maps_service_h maps = NULL;
+int error = maps_service_create("Maps Provider", &maps);
+ </pre>
+ </li>
+
+ <li><p>Set the security key, appropriate to selected Maps Provider using
+ <span style="font-family: Courier New,Courier,monospace;"> maps_service_set_provider_key()</span>.</p>
+ <pre class="prettyprint">
+error = maps_service_set_provider_key(maps, "XXXYYYZZZ");
+ </pre>
+ </li>
+
+ <li><p>Check which services are supported by selected Maps Provider using
+ <span style="font-family: Courier New,Courier,monospace;"> maps_service_provider_is_service_supported()</span>.</p>
+ <pre class="prettyprint">
+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;
+ </pre>
+ <p>To check other services availability follow the same approach using keys from
+ <span style="font-family: Courier New,Courier,monospace;"> maps_service_e</span>:</p>
+ <ul>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">MAPS_SERVICE_GEOCODE</span></p></li>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">MAPS_SERVICE_GEOCODE_INSIDE_AREA</span></p></li>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">MAPS_SERVICE_GEOCODE_BY_STRUCTURED_ADDRESS</span></p></li>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">MAPS_SERVICE_REVERSE_GEOCODE</span></p></li>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">MAPS_SERVICE_SEARCH_PLACE</span></p></li>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">MAPS_SERVICE_SEARCH_PLACE_BY_AREA</span></p></li>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">MAPS_SERVICE_SEARCH_PLACE_BY_ADDRESS</span></p></li>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">MAPS_SERVICE_CANCEL_REQUEST</span></p></li>
+ </ul>
+ </li>
+
+ <li><p>Optionally, check which data features are available for desired services using
+ <span style="font-family: Courier New,Courier,monospace;"> maps_service_provider_is_data_supported()</span>.</p>
+ <pre class="prettyprint">
+/* 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 */
+}
+ </pre>
+ <p>To check other data features availability follow the same approach using keys from
+ <span style="font-family: Courier New,Courier,monospace;"> maps_service_data_e</span>:</p>
+ <ul>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">MAPS_PLACE_ADDRESS</span></p></li>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">MAPS_PLACE_RATING</span></p></li>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">MAPS_PLACE_CATEGORIES</span></p></li>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">MAPS_PLACE_ATTRIBUTES</span></p></li>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">MAPS_PLACE_CONTACTS</span></p></li>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">MAPS_PLACE_EDITORIALS</span></p></li>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">MAPS_PLACE_REVIEWS</span></p></li>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">MAPS_PLACE_IMAGE</span></p></li>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">MAPS_PLACE_SUPPLIER</span></p></li>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">MAPS_PLACE_RELATED</span></p></li>
+ </ul>
+ </li>
+
+ <li><p>Set general preferences, such as language and distance units using
+ <span style="font-family: Courier New,Courier,monospace;"> maps_service_set_preference()</span>.</p>
+ <pre class="prettyprint">
+/* 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 */
+}
+ </pre>
+ <p>Optionally you can set the maximum amount of search results and default country code
+ using <span style="font-family: Courier New,Courier,monospace;">maps_preference_set_max_results() </span>
+ and <span style="font-family: Courier New,Courier,monospace;">maps_preference_set_country_code()</span> respectively.</p>
+ <p>In order to set Maps Provider specific preferences use
+ <span style="font-family: Courier New,Courier,monospace;"> maps_preference_set_property() </span>
+ with key-value pairs, defined in the appropriate Maps Provider documentation.</p>
+ <p>To get preferences, currently applied in the Maps Provider use following functions:</p>
+ <ul>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">maps_preference_get_distance_unit()</span></p></li>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">maps_preference_get_language()</span></p></li>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">maps_preference_get_max_results()</span></p></li>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">maps_preference_get_country_code()</span></p></li>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">maps_preference_get()</span> and
+ <span style="font-family: Courier New,Courier,monospace;"> maps_preference_foreach_property()</span></p></li>
+ </ul>
+ <p>The former pair of functions retrieve the Maps Provider specific preferences, not defined in the Maps API.</p>
+ </li>
+ </ol>
+
+ </div>
+ </li>
+ <li>
+ <div class="devicespec-tit">
+ <h2 id="geocode" name="geocode" class="items-tit-h2">Using Geocode and Reverse Geocode Services</h2>
+ <span class="fr"><a href="#" class="bt-arr"><em>Hide</em></a></span>
+ </div>
+ <div class="devicespec-con">
+ <p>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.</p>
+ <p>Note that each API request may be tuned as it is demonstrated in the section <a class="opensection" href="#preference">Tuning API requests with preferences</a>.</p>
+ <p>Note that to perform these operations, your application needs the http://tizen.org/privilege/internet privilege.</p>
+ <br>
+ <p>Usage of Geocode API is demonstrated below.</p>
+ <ol>
+ <li><p>Request the geocode by free formed address using
+ <span style="font-family: Courier New,Courier,monospace;"> maps_service_geocode()</span>.</p>
+ <pre class="prettyprint">
+/* 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 */
+}
+ </pre>
+ </li>
+
+ <li><p>Request the geocode inside a specified area using
+ <span style="font-family: Courier New,Courier,monospace;"> maps_service_geocode_inside_area()</span>.</p>
+ <pre class="prettyprint">
+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 */
+}
+ </pre>
+ </li>
+
+ <li><p>Request the geocode for a place, specified as a structured address using
+ <span style="font-family: Courier New,Courier,monospace;"> maps_service_geocode_by_structured_address()</span>.</p>
+ <pre class="prettyprint">
+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 */
+}
+ </pre>
+
+
+ <li><p>The callback
+ <span style="font-family: Courier New,Courier,monospace;"> __maps_service_geocode_cb</span> should be implemented as following:</p>
+ <pre class="prettyprint">
+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;
+}
+ </pre>
+ </li>
+ </ol>
+
+ <br>
+ <p>Usage of Reverse Geocode API is demonstrated below.</p>
+ <ol>
+ <li><p>To retrieve a reverse geocode of a specified geographical coordinates, use
+ <span style="font-family: Courier New,Courier,monospace;"> maps_service_reverse_geocode()</span>.</p>
+ <pre class="prettyprint">
+/* 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 */
+}
+ </pre>
+ </li>
+
+ <li><p>The callback
+ <span style="font-family: Courier New,Courier,monospace;"> __maps_service_reverse_geocode_cb</span> should be implemented as following:</p>
+ <pre class="prettyprint">
+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);
+}
+ </pre>
+ </li>
+
+ </ol>
+ </div>
+ </li>
+
+
+ <li>
+ <div class="devicespec-tit">
+ <h2 id="search_place" name="search_place" class="items-tit-h2">Using Place Search Services</h2>
+ <span class="fr"><a href="#" class="bt-arr"><em>Hide</em></a></span>
+ </div>
+ <div class="devicespec-con">
+ <p>To search for a place accordingly to a diversity of searching parameters, use one of approaches, listed in
+ this Section.</p>
+ <p>Note that each API request may be tuned as it is demonstrated in the Section <a class="opensection" href="#preference">Tuning API requests with preferences</a>.</p>
+ <p>Note that to perform these operations, your application needs the http://tizen.org/privilege/internet privilege.</p>
+ <ol>
+ <li><p>Search the place within a specified distance around the center coordinates using
+ <span style="font-family: Courier New,Courier,monospace;"> maps_service_search_place()</span>.</p>
+ <pre class="prettyprint">
+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 */
+}
+ </pre>
+ </li>
+
+ <li><p>Search the place within a specified geographical boundary using
+ <span style="font-family: Courier New,Courier,monospace;"> maps_service_search_place_by_area()</span>.</p>
+ <pre class="prettyprint">
+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 */
+}
+ </pre>
+ </li>
+
+ <li><p>Search the place by address within a specified geographical boundary using
+ <span style="font-family: Courier New,Courier,monospace;"> maps_service_search_place_by_address()</span>.</p>
+ <pre class="prettyprint">
+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 */
+}
+ </pre>
+ </li>
+
+
+ <li><p>The callback
+ <span style="font-family: Courier New,Courier,monospace;"> __maps_service_search_place_cb()</span> should be implemented as following:</p>
+ <pre class="prettyprint">
+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;
+}
+ </pre>
+ </li>
+ </ol>
+ </div>
+ </li>
+
+
+ <li>
+ <div class="devicespec-tit">
+ <h2 id="search_route" name="search_route" class="items-tit-h2">Using Using Routing Service</h2>
+ <span class="fr"><a href="#" class="bt-arr"><em>Hide</em></a></span>
+ </div>
+ <div class="devicespec-con">
+ <p>To query a route from point A to point B use one of approaches, listed in this Section.</p>
+ <p>Note that each API request may be tuned as it is demonstrated in the Section <a class="opensection" href="#preference">Tuning API requests with preferences</a>.</p>
+ <p>Note that to perform these operations, your application needs the http://tizen.org/privilege/internet privilege.</p>
+ <ol>
+ <li><p>Simply query the route from one geographical coordinates to another using
+ <span style="font-family: Courier New,Courier,monospace;"> maps_service_search_route()</span>.</p>
+ <pre class="prettyprint">
+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 */
+}
+ </pre>
+ </li>
+
+
+ <li><p>Query the route passing through a specified set of way points using
+ <span style="font-family: Courier New,Courier,monospace;"> maps_service_search_route_waypoints()</span>.</p>
+ <pre class="prettyprint">
+/* 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 */
+}
+ </pre>
+ </li>
+
+
+ <li><p>The callback
+ <span style="font-family: Courier New,Courier,monospace;"> __maps_service_search_route_cb()</span> should be implemented as following:</p>
+ <pre class="prettyprint">
+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;
+}
+ </pre>
+ </li>
+ </ol>
+ </div>
+ </li>
+
+
+ <li>
+ <div class="devicespec-tit">
+ <h2 id="cancel" name="cancel" class="items-tit-h2">Canceling the Service Request</h2>
+ <span class="fr"><a href="#" class="bt-arr"><em>Hide</em></a></span>
+ </div>
+ <div class="devicespec-con">
+ <p>To cancel a Geocode, Place Search or Routing request use <span style="font-family: Courier New,Courier,monospace;">maps_service_cancel_request()</span>.</p>
+ <pre class="prettyprint">
+/* Cancel the request with a specified id */
+error = maps_service_cancel_request(maps, request_id);
+
+if(error != MAPS_ERROR_NONE) {
+ /* Handle Error */
+}
+ </pre>
+
+ </div>
+ </li>
+
+
+ <li>
+ <div class="devicespec-tit">
+ <h2 id="address" name="address" class="items-tit-h2">Recognizing Address information</h2>
+ <span class="fr"><a href="#" class="bt-arr"><em>Hide</em></a></span>
+ </div>
+ <div class="devicespec-con">
+ <p>The Reverse Geocode request is run with <span style="font-family: Courier New,Courier,monospace;">maps_service_reverse_geocode()</span> (see
+ section <a class="opensection" href="#geocode">Using Geocode and Reverse Geocode Services</a>).</p>
+ <p>The result is retrieved from the Maps Service via <span style="font-family: Courier New,Courier,monospace;">maps_service_reverse_geocode_cb</span>
+ callback as a structured address data of the specified place.</p>
+ <p>Parse the address information using following functions:</p>
+ <pre class="prettyprint">
+/* 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);
+ </pre>
+ <p>Similarly get other address features using:</p>
+ <ul>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">maps_address_get_district()</span></p>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">maps_address_get_city()</span></p>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">maps_address_get_state()</span></p>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">maps_address_get_country()</span></p>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">maps_address_get_country_code()</span></p>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">maps_address_get_county()</span></p>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">maps_address_get_postal_code()</span></p>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">maps_address_get_freetext()</span></p>
+ </ul>
+ </div>
+ </li>
+
+
+ <li>
+ <div class="devicespec-tit">
+ <h2 id="place" name="place" class="items-tit-h2">Recognizing Place information</h2>
+ <span class="fr"><a href="#" class="bt-arr"><em>Hide</em></a></span>
+ </div>
+ <div class="devicespec-con">
+ <p>The place search request is run with <span style="font-family: Courier New,Courier,monospace;">maps_service_search_place()</span> ,
+ <span style="font-family: Courier New,Courier,monospace;"> maps_service_search_place_by_area()</span> or
+ <span style="font-family: Courier New,Courier,monospace;"> maps_service_search_place_by_address()</span>
+ (see section <a class="opensection" href="#search_place">Using Place Search Services</a>).</p>
+ <p>The result is retrieved from the Maps Service via multiple iterations of
+ <span style="font-family: Courier New,Courier,monospace;"> maps_service_search_place_cb</span> callback with an instance
+ of place data passed into.</p>
+ <p>The place data can be managed with a handle of type <span style="font-family: Courier New,Courier,monospace;">maps_place_h</span>.</p>
+ <p>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.</p>
+ <p>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.</p>
+ <br>
+ <p>To get particular features of the place information, such as place name, location and rating, use following functions.
+ <ol>
+ <li><p>To obtaining the place name use
+ <span style="font-family: Courier New,Courier,monospace;"> maps_place_get_name()</span>.</p>
+ <pre class="prettyprint">
+/* 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);
+ </pre>
+ </li>
+
+ <li><p>To obtaining the place location use
+ <span style="font-family: Courier New,Courier,monospace;"> maps_place_get_location()</span>.</p>
+ <pre class="prettyprint">
+/* 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);
+ </pre>
+ </li>
+
+ <li><p>To obtaining the place rating use
+ <span style="font-family: Courier New,Courier,monospace;"> maps_place_get_rating()</span>.</p>
+ <pre class="prettyprint">
+/* 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);
+ </pre>
+ </li>
+
+ </ol>
+ <p>To obtain other place features follow the same approach using functions:</p>
+ <ul>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">maps_place_get_id()</span></p>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">maps_place_get_address()</span></p>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">maps_place_get_distance()</span></p>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">maps_place_get_uri()</span></p>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">maps_place_get_supplier_link()</span></p>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">maps_place_get_related_link()</span></p>
+ </ul>
+
+ <br>
+ <p>To get lists of features of the place information, such as categories, reviews and attributes, use following iterating functions.</p>
+ <ol>
+ <li><p>To obtaining the list of place categories use
+ <span style="font-family: Courier New,Courier,monospace;"> maps_place_foreach_category()</span>.</p>
+ <pre class="prettyprint">
+/* 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 */
+}
+ </pre>
+ </li>
+
+ <li><p>The callback
+ <span style="font-family: Courier New,Courier,monospace;"> __maps_place_categories_cb()</span> should be implemented as following:</p>
+ <pre class="prettyprint">
+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;
+}
+ </pre>
+ </li>
+ </ol>
+ <p>To obtain other place feature lists follow the same approach using functions:</p>
+ <ul>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">maps_place_foreach_attribute</span></p>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">maps_place_foreach_contact</span></p>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">maps_place_foreach_editorial</span></p>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">maps_place_foreach_image</span></p>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">maps_place_foreach_review</span></p>
+ </ul>
+
+ <br>
+ <p>Some place data features may not be supported by your Maps Provider.</p>
+ <p>For example, the Maps Providers may not support place rating data. In this case the function
+ <span style="font-family: Courier New,Courier,monospace;"> maps_place_get_rating()</span> will return error
+ code <span style="font-family: Courier New,Courier,monospace;">MAPS_ERROR_NOT_SUPPORTED</span> and the value of
+ output parameter <span style="font-family: Courier New,Courier,monospace;">rating</span> will be meaningless.</p>
+ <p>As mentioned in the section <a class="opensection" href="#initial">Initializing the Maps Services</a>, you can check ahead which
+ data features are available in your Maps Provider
+ using <span style="font-family: Courier New,Courier,monospace;">maps_service_provider_is_data_supported()</span>.</p>
+ <pre class="prettyprint">
+/* 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 */
+}
+ </pre>
+
+ <br>
+ <p>Some Maps Providers may extend place data features defined in Maps API with specific extra properties.</p>
+ <ol>
+ <li><p>To iterate through retrieved extra properties use
+ <span style="font-family: Courier New,Courier,monospace;"> maps_place_foreach_property()</span>.</p>
+ <pre class="prettyprint">
+/* 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 */
+}
+ </pre>
+ </li>
+
+ <li><p>The callback
+ <span style="font-family: Courier New,Courier,monospace;"> __maps_place_properties_cb()</span> should be implemented as following:</p>
+ <pre class="prettyprint">
+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;
+}
+ </pre>
+ </li>
+ </ol>
+
+ </div>
+ </li>
+
+
+ <li>
+ <div class="devicespec-tit">
+ <h2 id="route" name="route" class="items-tit-h2">Recognizing Route information</h2>
+ <span class="fr"><a href="#" class="bt-arr"><em>Hide</em></a></span>
+ </div>
+ <div class="devicespec-con">
+ <p>The route calculation request is run with <span style="font-family: Courier New,Courier,monospace;">maps_service_search_route()</span> or
+ <span style="font-family: Courier New,Courier,monospace;"> maps_service_search_route_waypoints()</span> (see
+ section <a class="opensection" href="#search_route">Using Routing Service</a>).
+ The result is retrieved from the Maps Service via multiple iterations of
+ <span style="font-family: Courier New,Courier,monospace;"> maps_service_search_route_cb</span> callback with an instance of route data passed into.
+ The route data can be managed with a handle of type <span style="font-family: Courier New,Courier,monospace;">maps_route_h</span>.</p>
+ <p>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.</p>
+ <p>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.</p>
+ <br>
+ <p>To get particular features of the route information, such as route id, origin, destination and total distance, use following functions.
+ <ol>
+ <li><p>To obtaining the route id use
+ <span style="font-family: Courier New,Courier,monospace;"> maps_route_get_route_id()</span>.</p>
+ <pre class="prettyprint">
+/* 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);
+ </pre>
+ </li>
+
+ <li><p>To obtaining the route origin and destination use
+ <span style="font-family: Courier New,Courier,monospace;"> maps_route_get_origin()</span> and
+ <span style="font-family: Courier New,Courier,monospace;"> maps_route_get_destination()</span> respectively.</p>
+ <pre class="prettyprint">
+/* 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);
+ </pre>
+ </li>
+
+ <li><p>To obtaining the route total distance use
+ <span style="font-family: Courier New,Courier,monospace;"> maps_route_get_total_distance()</span>.</p>
+ <pre class="prettyprint">
+/* 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 */
+ </pre>
+ </li>
+ </ol>
+ <p>To obtain other place features follow the same approach using functions:</p>
+ <ul>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">maps_route_get_bounding_box()</span></p>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">maps_route_get_transport_mode()</span></p>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">maps_route_get_total_duration()</span></p>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">maps_route_get_distance_unit()</span></p>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">maps_place_get_supplier_link()</span></p>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">maps_place_get_related_link()</span></p>
+ </ul>
+ <br>
+ <p>To get lists of features of the route information, such as path or list of segments, use following iterating functions.</p>
+ <ol>
+ <li><p>To obtaining the list of geographical points, defining the route, use
+ <span style="font-family: Courier New,Courier,monospace;"> maps_route_foreach_path()</span>.</p>
+ <pre class="prettyprint">
+error = maps_route_foreach_path(route, __maps_route_path_cb, user_data);
+if(error != MAPS_ERROR_NONE) {
+ /* Handle Error */
+}
+ </pre>
+ </li>
+
+ <li><p>The callback
+ <span style="font-family: Courier New,Courier,monospace;"> __maps_route_path_cb()</span> should be implemented as following:</p>
+ <pre class="prettyprint">
+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;
+}
+ </pre>
+ </li>
+
+ <li><p>To obtaining the list of route segment use
+ <span style="font-family: Courier New,Courier,monospace;"> maps_route_foreach_segment()</span>.</p>
+ <pre class="prettyprint">
+error = maps_route_foreach_segment(route, __maps_route_segment_cb, user_data);
+if(error != MAPS_ERROR_NONE)
+{
+ /* Handle Error */
+}
+ </pre>
+ </li>
+
+ <li><p>The callback
+ <span style="font-family: Courier New,Courier,monospace;"> __maps_route_segment_cb()</span> should be implemented as following:</p>
+ <pre class="prettyprint">
+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;
+}
+ </pre>
+ </li>
+ </ol>
+ <br>
+ <p>Different Maps Providers may provide the route data in different ways.</p>
+ <p>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 <a class="opensection" href="#initial">Initializing the Maps Services</a>.
+ <ol>
+ <li><p>To obtain route path use following:
+ <span style="font-family: Courier New,Courier,monospace;"> maps_route_foreach_path()</span>.</p>
+ <pre class="prettyprint">
+/* 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 */
+}
+ </pre>
+ </li>
+
+ <li><p>To obtain route segments use following:
+ <span style="font-family: Courier New,Courier,monospace;"> maps_route_foreach_path()</span>.</p>
+ <pre class="prettyprint">
+/* 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 */
+}
+ </pre>
+ </li>
+ </ol>
+ <br>
+ <p>Some Maps Providers may extend route data features defined in Maps API with specific extra properties.</p>
+ <ol>
+ <li><p>To iterate through retrieved extra properties use
+ <span style="font-family: Courier New,Courier,monospace;"> maps_route_foreach_property()</span>.</p>
+ <pre class="prettyprint">
+/* 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 */
+}
+ </pre>
+ </li>
+
+ <li><p>The callback
+ <span style="font-family: Courier New,Courier,monospace;"> __maps_route_properties_cb()</span> should be implemented as following:</p>
+ <pre class="prettyprint">
+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;
+}
+ </pre>
+ </li>
+ </ol>
+ </div>
+ </li>
+
+
+ <li>
+ <div class="devicespec-tit">
+ <h2 id="preference" name="preference" class="items-tit-h2">Tuning API requests with preferences</h2>
+ <span class="fr"><a href="#" class="bt-arr"><em>Hide</em></a></span>
+ </div>
+ <div class="devicespec-con">
+ <p>All Maps API requests may be tuned with additional set of preferences.</p>
+ <p>Preparing and sending the <span style="font-family: Courier New,Courier,monospace;">preference</span> parameter via API request
+ allows the Maps Provider to generate more accurate results.</p>
+
+ <ol>
+ <li><p>To prepare preferences for Place Search Service use
+ <span style="font-family: Courier New,Courier,monospace;"> maps_preference_set_property()</span> with following keys:</p>
+ <ul>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">MAPS_PLACE_FILTER_TYPE</span></p>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">MAPS_PLACE_FILTER_SORT_BY</span></p>
+ </ul>
+ <p>The example from the section <a class="opensection" href="#search_place">Using Place Search Services</a> may be edited as following:</p>
+ <pre class="prettyprint">
+/* 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);
+ </pre>
+ </li>
+
+ <li><p>To prepare preferences for Routing Service use following functions:
+ <ul>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">maps_preference_set_route_optimization()</span></p>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">maps_preference_set_route_transport_mode()</span></p>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">maps_preference_set_route_feature_weight()</span></p>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">maps_preference_set_route_feature()</span></p>
+ </ul>
+ <p>Also use maps_preference_set_property() with following keys:</p>
+ <ul>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">MAPS_ROUTE_FREEFORM_ADDR_TO_AVOID</span></p>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">MAPS_ROUTE_STRUCTED_ADDR_TO_AVOID</span></p>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">MAPS_ROUTE_CIRCLE_AREA_TO_AVOID</span></p>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">MAPS_ROUTE_RECT_AREA_TO_AVOID</span></p>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">MAPS_ROUTE_GEOMETRY_BOUNDING_BOX</span></p>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">MAPS_ROUTE_GEOMETRY_RETRIEVAL</span></p>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">MAPS_ROUTE_INSTRUCTION_GEOMETRY</span></p>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">MAPS_ROUTE_INSTRUCTION_BOUNDING_BOX</span></p>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">MAPS_ROUTE_INSTRUCTION_RETRIEVAL</span></p>
+ <li><p><span style="font-family: Courier New,Courier,monospace;">MAPS_ROUTE_REALTIME_TRAFFIC</span></p>
+ </ul>
+
+ <p>The example from the section <a class="opensection" href="#search_route">Using Routing Service</a> may be edited as following:</p>
+ <pre class="prettyprint">
+/* 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);
+ </pre>
+ </li>
+ </ol>
+ <p>In case of specific preferences, required by your Maps Provider, use
+ <span style="font-family: Courier New,Courier,monospace;"> maps_preference_set_property()</span> with key-value pairs,
+ defined in the appropriate Maps Provider documentation.
+ </div>
+ </li>
+ </ul>
+ </div>
+ </div>
+
+ <script type="text/javascript" src="../../scripts/jquery.zclip.min.js"></script>
+ <script type="text/javascript" src="../../scripts/showhide.js"></script>
+
+ </div>
+ </div>
+</div>
+
+
+<a class="top sms" href="#"><img src="../../images/btn_top.gif" alt="Go to top" /></a>
+
+<div id="footer">
+ <p class="footer">Except as noted, this content - excluding the Code Examples - is licensed under <a href="http://creativecommons.org/licenses/by/3.0/legalcode" target="_blank"> Creative Commons Attribution 3.0</a> and all of the Code Examples contained herein are licensed under <a href="https://www.tizen.org/bsd-3-clause-license" target="_blank">BSD-3-Clause</a>.<br/>For details, see the <a href="https://www.tizen.org/content-license" target="_blank">Content License</a>.</p>
+</div>
+
+<script type="text/javascript">
+ var _gaq = _gaq || [];
+ _gaq.push(['_setAccount', 'UA-25976949-1']);
+ _gaq.push(['_trackPageview']);
+ (function() {
+ var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+ ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+ })();
+</script>
+
+ </body>
+ </html>