Since Tizen 2.4

What is the Route API?

The Route API provides a routing path from an origin to a destination.

The Route API is one of the Maps Services provided by the Tizen Native Location Framework.

To start using the Route API:

1. Create an empty Tizen native application.
2. Start the Maps Service.
3. Run a route request.

Prerequisites

This document assumes that you already have basic knowledge in Tizen development. For basic information, see https://developer.tizen.org/development/getting-started/preface.

The Maps Service API requires a security key issued by the maps provider.
In case of HERE maps, the security key is a concatenation of app_id and app_code, generated on https://developer.here.com/plans/api/consumer-mapping according to your consumer plan.

“your-security-key” is “app_id/app_code”

To ensure the Maps Service API execution, set the following privileges:

• http://tizen.org/privilege/mapservice
• http://tizen.org/privilege/internet
• http://tizen.org/privilege/network.get

1 Create an Empty Tizen Native Application

In the IDE, create an empty application using the basic UI application template, and run it on an emulator or a device.

The "Hello Tizen" label appears on the screen at application startup.

2 Start the Maps Service

1. Include the Maps Service API header file in your application:

   #include <maps_service.h>

   Note This inclusion allows you to use all native Maps Service API functions and features. For more details, see https://developer.tizen.org/development/api-references/, and go to 2.4 API References -> Native Application -> Mobile Native -> Native API Reference -> Location -> Maps Service.
2. Add a Maps Service handle to the appdata_s structure:
   

   typedef struct 
   appdata 
   {
      Evas_Object *win;
      Evas_Object *conform;
      Evas_Object *label;
      maps_service_h maps; // Maps Service handle
   } appdata_s;

3. Create the Maps Service instance in the app_create() function:
   

   static bool
   app_create(void *data)
   {
      appdata_s *ad = data;
      create_base_gui(ad);
   
      // Specify the maps provider name
      if (maps_service_create("HERE", &ad->maps) != MAPS_ERROR_NONE)
         return false;
   
      // Set the security key issued by the maps provider
      maps_service_set_provider_key(ad->maps, "your-security-key");
   
      return true;
   }

4. When no longer needed, destroy the Maps Service instance in the app_terminate() function:
   

   static void
   app_terminate(void *data)
   {
      // Release all resources
      appdata_s *ad = data;
      maps_service_destroy(ad->maps);
   }

3 Run a Route Request

To run a route request:

1. Add the route request into the app_create() function:

   int request_id = 0;
   maps_coordinates_h origin = NULL, destination = NULL;
   maps_coordinates_create(50.0734902, 14.4279653, &origin);
   maps_coordinates_create(50.0860608, 14.4145915, &destination);
   
   // Use the Route API
   maps_service_search_route(ad->maps, origin, destination, NULL, search_route_cb, ad, &request_id);

   After creating the request, release any temporary data:

   maps_coordinates_destroy(origin);
   maps_coordinates_destroy(destination);

2. Implement the route callback:
   

   static bool
   search_route_cb(maps_error_e error, int request_id, int index, int total,
   		maps_route_h route, void* user_data)
   {
      double distance = .0;
      long duration = 0;
      char route_info[0x100] = {0};
   
      maps_route_get_total_distance(route, &distance);
      maps_route_get_total_duration(route, &duration);
   
      snprintf(route_info, 0x100, "Route duration %.0f min, length %.3f km",
   	    ceil(1. * duration / 60), distance / 1000);
   
      appdata_s *ad = user_data;
      elm_object_text_set(ad->label, route_info);
   
      // Release the route handle
      maps_route_destroy(route);
   
      // If return true, you receive other routes,
      // corresponding to the search parameters
      // In this example, 1 route is enough
      return true;
   }

3. Run the application.

   At first, the familiar "Hello Tizen" line appears. A moment later, however, it changes to "Route duration 9 min, length 2.889 km".
   This indicates the calculated route from a Prague pub to the Karluv Most bridge.

Bonus: Working with a Route Maneuver List

To use route maneuvers:

1. To set the distance units of the route, modify the app_create() function as follows:

   static bool
   app_create(void *data)
   {
      // Hook to take necessary actions before main event loop starts
      // Initialize UI resources and application data
      // If this function returns true, the main loop of application starts
      // If this function returns false, the application is terminated
      appdata_s *ad = data;
   
      create_base_gui(ad);
   
      // Specify the maps provider name
      if (maps_service_create("HERE", &ad->maps) != MAPS_ERROR_NONE)
         return false;
   
      // Set the security key issued by the maps provider
      maps_service_set_provider_key(ad->maps, "your-security-key");
   
      // Set distance units
      maps_preference_h preference = NULL;
      maps_preference_create(&preference);
      maps_preference_set_distance_unit(preference, MAPS_DISTANCE_UNIT_M);
   
      int request_id = 0;
      maps_coordinates_h origin = NULL, destination = NULL;
      maps_coordinates_create(50.0734902, 14.4279653, &origin);
      maps_coordinates_create(50.0860608,14.4145915, &destination);
   
      // Use the Route API
      maps_service_search_route(ad->maps, origin, destination, preference, search_route_cb, ad, &request_id);
   
      maps_coordinates_destroy(origin);
      maps_coordinates_destroy(destination);
      maps_preference_destroy(preference);
   
      return true;
   }

2. To iterate through the segment and maneuver lists of the route, modify the search_route_cb() function as follows:
   

   static bool
   search_route_cb(maps_error_e error, int request_id, int index, int total,
   		maps_route_h route, void* user_data)
   {
      double distance = .0;
      long duration = 0;
      char route_info[0x1000] = {0};
   
      maps_route_get_total_distance(route, &distance);
      maps_route_get_total_duration(route, &duration);
   
      snprintf(route_info, 0x1000, "Route duration %.0f min, length %.3f km",
   	    ceil(1. * duration / 60), distance / 1000);
   
      // Bonus: print list of maneuvers to reach the destination
      maps_route_foreach_segment(route, route_segment_cb, route_info);
   
      appdata_s *ad = user_data;
      elm_object_text_set(ad->label, route_info);
   
      // Release the route handle
      maps_route_destroy(route);
   
      // If return true, you receive other routes,
      // corresponding to the search parameters
      // In this example, 1 route is enough
      return true;
   }

3. Implement the segment and maneuver list callbacks:
   

   static bool
   route_segment_maneuver_cb(int index, int total, maps_route_maneuver_h maneuver, void *user_data)
   {
      char *route_info = (char *)user_data;
      char *instruction_text = NULL;
      const int max_line_len = 64;
      const int half_line_len = max_line_len / 2;
      char num[0x10] = {0};
   
      maps_route_maneuver_get_instruction_text(maneuver, &instruction_text);
      if (instruction_text && strlen(instruction_text)) 
      {
         // Add the instruction number
         snprintf(num, 0x10, "  %d: ", index + 1);
         strcat(route_info, num);
   
         // Add the instruction text
         const int l = strlen(instruction_text);
         if (l > max_line_len) 
         { // If the instruction is too long, extract the middle part
            // Add the first part of the instruction
   	 char instruction_head[half_line_len + 1] = {0};
   	 snprintf(instruction_head, half_line_len - 3, "%s", instruction_text);
   	 strcat(route_info, instruction_head);
   
   	 // Add the first and second part separator
   	 strcat(route_info, "...");
   
   	 // Add the second part of the instruction
   	 char instruction_tail[half_line_len + 1] = {0};
   	 snprintf(instruction_tail, half_line_len, "%s", instruction_text + l - half_line_len);
   	 strcat(route_info, instruction_tail);
         } 
         else
            // Add whole instruction
   	 strcat(route_info, instruction_text);
      }
      free(instruction_text);
      maps_route_maneuver_destroy(maneuver);
   
      return true;
   }
   
   static bool
   route_segment_cb(int index, int total, maps_route_segment_h segment, void *user_data)
   {
      maps_route_segment_foreach_maneuver(segment, route_segment_maneuver_cb, user_data);
      maps_route_segment_destroy(segment);
   
      return true;
   }

4. Run the application.

   A moment after startup, the application shows the familiar route information and a list of 13 maneuvers required to get from the specified origin to the destination.

   

Reference

https://developer.tizen.org/development/tutorials/native-application/location/maps-service#search_route