Maps Service: Using the Map Service

This tutorial demonstrates how you can use the map service to query geocodes and routes, and search for places.

This feature is supported in mobile applications only.

Warm-up

Become familiar with the Maps Service API basics by learning about:

• Initializing the Map Service

  Select a map provider, check available capabilities, fulfill the prerequisites, create the Maps Service instance, and destroy it when no longer needed.

• Using Geocode and Reverse Geocode Services

  Get the geocode of a specified place, and the reverse geocode corresponding to specified geographical coordinates.

• Using the Place Search Service

  Search for places near a specified geographical position or inside a specified geographical area.

• Using the Routing Service

  Query the route from point A to point B, optionally passing through a number of specified waypoints.

• Canceling the Service Request

  Cancel the map service (geocode, routing, or place search) request.

Follow-up

Once we have learned the basics of the Maps Service API, we can now move on to more advanced tasks, including:

• Recognizing the Address Information

  Parse the information obtained from the reverse geocode service.

• Recognizing the Place Information

  Parse the information obtained from the place search service.

• Recognizing the Route Information

  Parse the information obtained from the routing service.

• Customizing the Service Requests

  Prepare and send a set of extra preferences through a map service request to allow the map provider to generate a more accurate result.

Initializing the Map Service

To start using the map service:

1. To use the functions and data types of the Maps Service API, include the <maps_service.h> header file in your application:

   #include <maps_service.h>
   

2. The Maps Service instance relies on a particular map provider. To get a list of available map providers, use the maps_service_foreach_provider() function.

   static bool 
   _maps_service_provider_info_cb(char* maps_provider, void* user_data)
   {
      // Handle the map 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) 
      {
         // Select a provider from the available_providers vector
      } 
      else 
      {
         // Error handling
      }
   }
   

3. Before you use the Maps Service API, create a Maps Service instance using the maps_service_create() function:

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

4. Set the security key appropriate to the selected map provider using the maps_service_set_provider_key() function:

   error = maps_service_set_provider_key(maps, "XXXYYYZZZ");
   

5. Check which services are supported by the selected map provider using the maps_service_provider_is_service_supported() function:

   bool supported = false;
   
   // Check whether 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 whether routing through 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 for the availability of other services, follow the same approach using the keys from the maps_service_e enumerator.

6. Optionally, check which data features are available for the desired services using the maps_service_provider_is_data_supported() function:

   // Check whether 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) 
   {
      // Use route path
   }
   
   // Check whether segment 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) 
   {
      // Use segment path
   }
   
   // Check whether segment maneuver 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) 
   {
      // Use segment maneuvers
   }
   

   To check the availability of other data features, follow the same approach using the keys from the maps_service_data_e enumerator.

7. Set general preferences, such as language and distance units, using the maps_service_set_preference() function:

   // Create a preference set instance
   maps_preference_h preference = NULL;
   int error = maps_preference_create(&preference);
   if (error != MAPS_ERROR_NONE) 
   {
      // Error handling
   }
   
   // Set the distance unit preference
   error = maps_preference_set_distance_unit(preference, MAPS_DISTANCE_UNIT_M);
   if (error != MAPS_ERROR_NONE) 
   {
      // Error handling
   }
   
   // Set the language preference
   error = maps_preference_set_language(preference, "en-US");
   if (error != MAPS_ERROR_NONE) 
   {
      // Error handling
   }
   
   // Apply the set of preferences for the map service
   error = maps_service_set_preference(maps, preference);
   if (error != MAPS_ERROR_NONE) 
   {
      // Error handling
   }
   
   // Destroy the preference set instance
   error = maps_preference_destroy(preference);
   if (error != MAPS_ERROR_NONE) 
   {
      // Error handling
   }
   

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

   To set specific preferences for the map provider, use the maps_preference_set_property() function with key-value pairs, defined in the appropriate map provider documentation.

   To get the preferences currently applied in the map provider, use the 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()

     These 2 functions retrieve the map provider-specific preferences not defined in the Maps Service API.

Using Geocode and Reverse Geocode Services

To retrieve a geocode of a specified place, or the place information corresponding to given geographic coordinates, use one of the following approaches. The service requests can be customized.

To retrieve a geocode:

1. Make sure that your application has the http://tizen.org/privilege/internet privilege.
2. Request the geocode:
   • Use the maps_service_geocode() function for a request based on a free-formed address:

     // Search for geocode of the Samsung's 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) 
     {
        // Error handling
     }
     

   • Use the maps_service_geocode_inside_area() function for a request inside a specified area:

     maps_area_h bounds = NULL;
     // Use maps_area_create_rectangle() or maps_area_create_circle() to create geographic bounds for geocoding
     
     // Search for geocode of the Digital City within a specified geographic 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) 
     {
        // Error handling
     }
     

   • Use the maps_service_geocode_by_structured_address() function for a request for a place, specified as a structured address:

     maps_address_h address = NULL;
     // Use maps_address_create() to create an instance of an address
     // Then use maps_address_set_XXX() to initialize the address with the desired values
     
     // Search 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) 
     {
        // Error handling
     }
     

3. Implement the __maps_service_geocode_cb() callback to receive the service response:

   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 the obtained coordinate data
   
      // Release the results
      maps_coordinates_destroy(coordinates);
   
      return true;
   }
   

To retrieve a reverse geocode:

1. To retrieve a reverse geocode of specified geographic coordinates, use the maps_service_reverse_geocode() function:

   // Obtain the reverse geocode with 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) 
   {
      // Error handling
   }
   

2. Implement the __maps_service_reverse_geocode_cb() callback to receive the service response:

   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 the obtained address
   
      // Release the results
      maps_address_destroy(address);
   }
   

Using the Place Search Service

To search for a place with a diversity of search parameters, use one of the following approaches. The service requests can be customized.

To search for a place:

1. Make sure that your application has the http://tizen.org/privilege/internet privilege.
2. Search for a place:
   • Use the maps_service_search_place() function for a search within a specified distance around the center coordinates:

     maps_coordinates_h position = NULL;
     // Create the 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) 
     {
        // Error handling
     }
     

   • Use the maps_service_search_place_by_area() function for a search for a place within a specified geographic boundary:

     maps_area_h boundary = NULL;
     // Create the boundary with maps_area_create_rectangle() or 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) 
     {
        // Error handling
     }
     

   • Use the maps_service_search_place_by_address() function for a search for a place based on an address within a specified geographic boundary:

     maps_area_h boundary = NULL;
     // Create the boundary with maps_area_create_rectangle() or 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) 
     {
        // Error handling
     }
     

3. Implement the __maps_service_search_place_cb() callback to receive the service response:

   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 the obtained place data
   
      // Release the results
      maps_place_destroy(place);
   
      return true;
   }
   

Using the Routing Service

To query a route from point A to point B, use one of the following approaches. The service requests can be customized.

To query a route:

1. Make sure that your application has the http://tizen.org/privilege/internet privilege.
2. Query the route:
   • Use the maps_service_search_route() function for a route from one set of geographic coordinates to another:

     maps_coordinates_h origin = NULL, destination = NULL;
     // Create the 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) 
     {
        // Error handling
     }
     

   • Use the maps_service_search_route_waypoints() function for a route passing through a specified set of waypoints:

     // Specify the number of waypoints
     const int waypoint_num = 5;
     
     // Create an array with the waypoint coordinates 
     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) 
     {
        // Error handling
     }
     

3. Implement the __maps_service_search_route_cb() callback to receive the service response:

   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 the obtained route data
   
      // Release the results 
      maps_route_destroy(route);
   
      return true;
   }
   

Canceling the Service Request

To cancel a geocode, place search, or routing request, use the maps_service_cancel_request() function:

// Cancel the request with a specified ID
error = maps_service_cancel_request(maps, request_id);

if (error != MAPS_ERROR_NONE) 
{
   // Error handling
}

Recognizing the Address Information

The result of the reverse geocode request (maps_service_reverse_geocode()) is retrieved from the map service using the maps_service_reverse_geocode_cb() callback. The result is structured address data of the specified place.

Parse the address information using the following functions:

// Obtain the building number 
char *building_number = NULL;
error = maps_address_get_building_number(address, &building_number);

if (error != MAPS_ERROR_NONE) 
{
   // Error handling
}

// Use the building_number

free(building_number);

// Obtain the street name
char *street = NULL;
error = maps_address_get_street(address, &street);

if (error != MAPS_ERROR_NONE) 
{
   // Error handling
}

// Use the street name

free(street);

Similarly, you can get other address features using the following functions:

• 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 the Place Information

The result of the place search request (maps_service_search_place(), maps_service_search_place_by_area(), or maps_service_search_place_by_address()) is retrieved from the map service using multiple iterations of the maps_service_search_place_cb() callback. The result is an instance of place data.

Note

Different map providers are capable of providing different sets of place data features. Some map providers can extend the place data features with extra properties that are not specified in the Maps Service API. Such properties are organized as a key-value storage where the keys are the names of the properties. If your map provider does not support a specific feature, the get function for the feature returns an error. To prevent problems, you can check which data features are available in your map provider using the maps_service_provider_is_data_supported() function.

To parse place data:

1. To get the place information features, such as place name, location, and rating, use the following functions with a maps_place_h place handle:

   • To obtain the place name, use the maps_place_get_name() function:

     // Obtain the place name
     char *name = NULL;
     error = maps_place_get_name(place, &name);
     if (error != MAPS_ERROR_NONE) 
     {
        // Error handling 
     }
     
     // Use the place name
     
     free(name);
     

   • To obtain the place location, use the maps_place_get_location() function:

     // Obtain the place location
     maps_coordinates_h location = NULL;
     error = maps_place_get_location(place, &location);
     if (error != MAPS_ERROR_NONE) 
     {
        // Error handling
     }
     
     // Use the place location
     
     maps_coordinates_destroy(location);
     

   • To obtain the place rating, use the maps_place_get_rating() function:

     // Obtain the place rating
     maps_place_rating_h rating = NULL;
     error = maps_place_get_rating(place, &rating);
     if (error != MAPS_ERROR_NONE) 
     {
        // Error handling
     }
     
     // Use the place rating
     
     maps_place_rating_destroy(rating);
     

   To obtain other place features, follow the same approach using the following 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()

2. To get lists of place information features, such as categories, reviews, and attributes, use the following iterating functions:

   1. To obtain a list of place categories, use the maps_place_foreach_category() function:

      // Obtain a list of place categories 
      error = maps_place_foreach_category(place, __maps_place_categories_cb, user_data);
      if (error != MAPS_ERROR_NONE) 
      {
         // Error handling
      }
      

   2. Implement the __maps_place_categories_cb() callback:

      static bool 
      __maps_place_categories_cb(int index, int total, maps_place_category_h category, void* user_data)
      {
         // Handle the obtained place category data
      
         // Release the results
         maps_place_category_destroy(category);
      
         return true;
      }
      

   To obtain other place feature lists, follow the same approach using the following functions:

   • maps_place_foreach_attribute()
   • maps_place_foreach_contact()
   • maps_place_foreach_editorial()
   • maps_place_foreach_image()
   • maps_place_foreach_review()

3. To get the extra properties that some map providers provide to extend the place data features defined in the Maps Service API:

   1. To iterate through the retrieved extra properties, use the maps_place_foreach_property() function:

      // Obtain the map provider-specific place data properties
      error = maps_place_foreach_property(place, __maps_place_properties_cb, user_data);
      if (error != MAPS_ERROR_NONE) 
      {
         // Error handling
      }
      

   2. Implement the __maps_place_properties_cb() callback:

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

Recognizing the Route Information

The result of the route calculation request (maps_service_search_route() or maps_service_search_route_waypoints()) is retrieved from the map service using multiple iterations of the maps_service_search_route_cb() callback. The result is an instance of route data.

Note

Different map providers are capable of providing different sets of route data features. Some map providers can extend the route data features with extra properties that are not specified in the Maps Service API. Such properties are organized as a key-value storage where the keys are the names of the properties. If your map provider does not support a specific feature, the get function for the feature returns an error. To prevent problems, you can check which data features are available in your map provider using the maps_service_provider_is_data_supported() function.

To parse route data:

1. To get the route information features, such as route ID, origin, destination, and total distance, use the following functions with a maps_route_h place handle:

   • To obtain the route ID, use the maps_route_get_route_id() function:

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

   • To obtain the route origin and destination, use the maps_route_get_origin() and maps_route_get_destination() functions:

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

   • To obtain the route total distance, use the maps_route_get_total_distance() function:

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

   To obtain other route features, follow the same approach using the following 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()

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

   • To obtain the list of geographic points defining the route, use the maps_route_foreach_path() function:

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

     Implement the __maps_route_path_cb() callback:

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

   • To obtain the list of route segments, use the maps_route_foreach_segment() function:

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

     Implement the __maps_route_segment_cb() callback:

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

3. To get the extra properties that some map providers provide to extend the route data features defined in the Maps Service API:

   1. To iterate through the retrieved extra properties, use the maps_route_foreach_property() function:

      // Obtain the map provider-specific route data properties
      error = maps_route_foreach_property(route, __maps_route_properties_cb, user_data);
      if (error != MAPS_ERROR_NONE) 
      {
         // Error handling 
      }
      

   2. Implement the __maps_route_properties_cb() callback:

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

Customizing the Service Requests

All Maps Service API requests can be customized with additional preferences. Preparing and sending the preference parameter with the service request allows the map provider to generate more accurate results.

To customize the service request:

• To prepare preferences for the place search service, use the maps_preference_set_property() function with the following keys:
  • MAPS_PLACE_FILTER_TYPE
  • MAPS_PLACE_FILTER_SORT_BY

  The example from Using the Place Search Service can be modified as follows to include the customized preferences:

  // Create extra preferences for the place search service
  error = maps_preference_create(&preference);
  if (error != MAPS_ERROR_NONE) 
  {
     // Error handling
  }
  error = maps_preference_set_property(preference, MAPS_PLACE_FILTER_TYPE, "restaurant");
  if (error != MAPS_ERROR_NONE) 
  {
     // Error handling
  }
  
  maps_coordinates_h position = NULL;
  // Create the 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) 
  {
     // Error handling 
  }
  
  maps_preference_destroy(preference);
  

• To prepare preferences for the routing service, use the following functions:
  • maps_preference_set_route_optimization()
  • maps_preference_set_route_transport_mode()
  • maps_preference_set_route_feature_weight()
  • maps_preference_set_route_feature()

  You can also use the maps_preference_set_property() function with the 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 Using the Routing Service can be modified as follows to include the customized preferences:

  // Create extra preferences for the routing service
  error = maps_preference_create(&preference);
  if (error != MAPS_ERROR_NONE) 
  {
     // Error handling 
  }
  error = maps_preference_set_property(preference, MAPS_ROUTE_FREEFORM_ADDR_TO_AVOID, "Suwon, Digital City");
  if (error != MAPS_ERROR_NONE) 
  {
     // Error handling 
  }
  error = maps_preference_set_route_optimization(preference, MAPS_ROUTE_TYPE_SHORTEST);
  if (error != MAPS_ERROR_NONE) 
  {
     // Error handling 
  }
  
  maps_coordinates_h origin = NULL, destination = NULL;
  // Create the 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) 
  {
     // Error handling 
  }
  
  maps_preference_destroy(preference);
  

If your map provider requires any specific preferences, use the maps_preference_set_property() function with key-value pairs defined in the appropriate map provider documentation.