You are here: Map API

Map API

A Map widget displays geographical locations on a map in your application. Using the Map API, you can customize maps with desired content and add more capabilities to the Map widget. The Map API uses voltmx.map Namespace and the following API elements.

To search for all possible routes between any two points on the map, use the voltmx.map.searchRoutes function. Find the latitude and longitude values of each point in the selected search route by using the voltmx.map.decode function. Using this information, you can calculate the distance between the two locations with the voltmx.map.distanceBetween function. You can also determine if a specific location falls within a circle or along a polyline on the map using the voltmx.map.containsLocation function.

Searching Routes

You can search for routes between the source and destination locations using the voltmx.map.searchRoutes function. Your can also use polylines to display routes on maps and find the distance between a given set of locations.

The route searching capabilities of underlying platforms varies as each platform supports a different set of request parameter configurations. The format of the search results also varies from platform to platform.

Here are the list of request parameters available for all platforms.

Route Search Results

Route search results are delivered through the successCallback callback function of the searchRoute function and provided in JSON format. The routes parameter is a JSON array that contains one or more routes depending on the search criteria parameter alternatives which influences the returned results to include alternative routes.

The high level structure of a typical JSON response would be similar to the following example.

routes = [ {
        legs : [ {
            steps: [ {    		
                     }
		    	     …. //other speps
                   ]	
                 }
                 …. //other legs
               ]
            }
            ….. //additional alternative routes
         ];
			

Note: In Android, the availability of certain platform specific keys in search results depend on the search criteria. Please refer the Google Direction API documentation for detailed information on when certain keys are included in search result.

Routes

Search results are returned as JSON arrays with one or more routes that indicate possible directions that are available between the source and the destination locations. Each route contains the following information.

• startLocation [JSObject]: Starting location for the route. It may be different from the source location given in search criteria.
• endLocation [JSObject]: Ending location for the route. It may be different from the destination location given in search criteria.
• distance [Number]: Total distance of the route in meters.
• duration [Number]: Total duration of the route in seconds
• legs [Array]: An array of legs which constitute the route. A separate leg will be present for each waypoint or destination specified. If the search criteria does not contain any waypoints, only one leg will be returned. iOS platform does not support waypoints, so it always returns single leg covering the total route.

Each leg contains a startLocation, endLocation, distance, duration, and steps. An array of steps constitute the leg. A step is the most atomic unit of a direction’s route, containing a single step describing a specific, single instruction on the journey.

To know more about a step, refer here.

Apart from the common properties, platforms can also provide additional information in each route.

Android :

• durationInTraffic [ Number ]Indicates the total duration of this leg, taking into account current traffic conditions. Availability of this key is based on certain condition. For more information, refer here.
• arrivalTime [String]: Contains the estimated time of arrival for this leg.
• departureTime [String] : Contains the estimated time of departure for this leg.
• startAddress [String] : Contains the human-readable address (typically a street address) reflecting the start_location of this leg.
• endAddress [String] : Contains the human-readable address (typically a street address) reflecting the end_location of this leg.

Windows:

None.

• polylinePoints [Array]: An Array of Lat/Lon values that can be used to draw path that follows the road closely. Developers can use addPolyline() api to draw the path.

Steps

Each step contains the following information

• startLocation [JSObject]: Starting location for the step.
• endLocation [JSObject]: Ending location for the step.
• distance [Number] : Total distance of the step in meters.
• instruction [String]: Instruction for step to present turn-by-turn direction hint
• transportMode [String] : Mode of the transport.

Apart from common properties, platforms can also provide additional information in each step.

Android:

• duration [Number]: Total duration of the step in seconds
• encodedPolylinePoints[String] : Contains an encoded polyline representation of the step. This polyline is an approximate (smoothed) path of the step. More details about encoded polyline can be found here. Developers need to decode the encoded polyline using voltmx.map.decode() utility function to get the series of lat/lon values which can be used to draw a smooth polyline using addPolyline() function.

iOS:

• notice [ String ] : Additional localized legal or warning notice related to this step (e.g. “Do not cross tracks when lights flash”)

Platform Specific properties

Apart from common properties, platforms can also provide additional information in each route.

iOS

• name [String]: Localized description of the route’s significant feature. For example, “US-101”
• advisoryNotices [NSArray]: Localized notices of route conditions as NSStrings. For example, “Avoid during winter storms”

Android

• copyrights [ String ]: Contains the copyrights text to be displayed for this route. You must handle and display this information yourself.
• warnings [Array]: Contains an array of warnings to be displayed when showing these directions. You must handle and display these warnings yourself.

Windows :

• HasBlockedRoads [bool ]: Gets a value that indicates the route has been modified from the “best” route to avoid blocked roads.
• IsTrafficBased [bool]: Gets a value indicating whether the MapRoute is based on traffic.

Limitations

Android

Applications which use the apiKey parameter in their search criteria must enable the Directions API in the Google Developer Console. The usage quota for the Google Directions API is counted against the apiKey.

Google’s usage limits are as follows:

• Free: 2,500 directions requests per 24 hour period, Up to 8 waypoints allowed in each request and 2 requests per second. Waypoints are not available for transit directions.
• Paid: 100,000 directions requests per 24 hour period.

iOS

iOS does not support directions in all countries. For a list of countries where directions are available, please refer here.

To view the functionality of the Map API in action, download the sample application from the link below. Once the application is downloaded, build and preview the application using the Volt MX App.