Open topic with navigation

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 kony.map Namespace and the following API elements.

Function Description
kony.map.containsLocation Tests to see whether a specified location is within a circle or polygon on a map or whether it lies along a polyline on a map.
kony.map.distanceBetween Finds the linear distance between two locations on a map.
kony.map.decode Enables apps to to decode the encoded polyline points which are provided in search route results.
kony.map.searchRoutes Searches for routes between the start and destination locations.
 

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

Searching Routes

You can search for routes between the source and destination locations using the kony.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.

ParameterDescriptionAndroidiOS
origin [JSObject] [Mandatory] [All]

Source address or latitude/ longitude values for which you want to get the route details. If both lat/lon and address are mentioned, the lat/lon values are considered. Address is supported only in Android & iOS.

Ex: searchCriteria = {origin : {lat:17.499467, lon: 78.386760, address= "9225 Bee Cave Rd, Austin, TX 78746"} };

YY
destination [JSObject] [Mandatory] [All]

Destination address or latitude/ longitude values for which you want to get the route details. If both lat/lon and address are mentioned, the lat/lon values are considered. Address is supported only in Android.

Ex: searchCriteria = { destination : {lat:17.499467, lon: 78.386760, address= "9225 Bee Cave Rd, Austin, TX 78746"} };

YY
transportMode [String] [Optional] [All]

Mode of the transport used to calculate the directions. Here are the list of supported modes by platform.

  • Driving – Applies to Android, iOS, and Windows
  • Walking – Applies to Android, iOS, and Windows
  • Bicycling – Applies to Android only
  • Transit – applies to Android only

If transportMode is not specified, underlying platforms assumes the default values. Here are the default values assumed by each platform in the absense of mode key.

  • iOS: Any
  • Android: Driving
  • Windows: Driving

If an unsupported mode is received, platforms fallback on default mode.

YY
directionServiceUrl [String] [Mandatory] [Android]

URL that the Android platform uses to fetch direction details from Google Direction API service. Google offers two URLs (secure/ non-secure) for the direction service. You can use any one of them as required.

Google Direction Service URLs: "https://maps.googleapis.com/maps/api/directions/json"

Note: If the application is using SSL pinning (Allow Self Signed certificates – Only Bundled), the application must obtain the certificate for the URL and bundle along with the other pinned certificates. You must be cautious about the validity of the bundled certificate as Google certificates have a limited validity period. This requirement is not applicable from Visualizer V8 SP4 onwards.

YN
waypoints [Array] [Optional] [Android, Win]

Specifies an array of waypoints. A waypoint is specified as either a latitude/ longitude coordinate or as an address. Number of legs returned in resultant routes depends on the number of waypoints specified. If no waypoint is specified, single leg is returned covering the entire route. Since this property is not supported for iOS, search results always contains single leg for each route for iOS.

For example, searchCriteria = {… waypoints:[{lat:17.495106, lon:78.324235}, {lat:17.495024, lon:78.345263}] …};

Note: Google Map restriction for Android allows up to 8 waypoints for Google Map free API and 23 waypoints for Google Map for Work in each request. Waypoints are not available for transit directions.

Note: iOS core OS does not have direct support for waypoints. To support, Kony iOS platform need to make multiple MapKit API calls internally.

YN
alternatives [Boolean] [Optional] [All]

Boolean flag to indicate whether to search for alternative routes or not. If true, search results may contain more than one route. Searching for alternative routes may increase the response time.

For example, searchCriteria = {… alternatives:true …}

YY
avoid [Array] [Optional] [Android,Win]

Indicates that the calculated route(s) should avoid certain features.

  • tolls, highways, ferries - avoided in iOS and Windows.
  • tunnels, dirtroad, motorrail - avoided in Windows, but not in Android.
  • Indoor is avoided in Android, but not in Windows.
YN
departureTime [Number] [Optional] [Android, iOS]

Desired time of departure in seconds which is calculated since January 1, 1970 UTC. This property is applicable for Android when transportMode is transit.

For example, searchCriteria = {… departureTime : …}

Note: Both departureTime and arrivalTime should not present search criteria for Android.

YY
arrivalTime [Number] [Optional] [Android, iOS]

Desired time of arrival in seconds which is calculated since January 1, 1970 UTC. This property is applicable for Android when transportMode is transit.

For example, searchCriteria = {… arrivalTime : …}

Note: Both departureTime and arrivalTime should not present search criteria for Android.

YY
language [String] [Optional] [Android]

Specifies the language in which you want to return results. If the language is not set, the service will attempt to use the native language of the domain from which the request is sent. A list of latest supported language codes can be found here.

For example, searchCriteria = {… language = “fr” …}

YN
region [String] [Optional] [Android]

Specify ccTLD country code to get the search results biased to the specified region. For more info about region specifications refer here.

For example, searchCriteria = {… region : “es” …}

YN
transitMode [Array] [Optional] [Android]

Specifies one or more preferred modes of transit. This parameter may only be specified for transit directions, and only if the request includes an API key or a Google Maps API for Work client ID. The parameter supports the following arguments:

  • bus: indicates that the calculated route should prefer travel by bus.

  • Subway: indicates that the calculated route should prefer travel by subway.

  • train: indicates that the calculated route should prefer travel by train.

  • tram: indicates that the calculated route should prefer travel by tram and light rail.

  • rail: indicates that the calculated route should prefer travel by train, tram, light rail, and subway. This is equivalent to transit_mode=train|tram|subway.

Ex : searchCriteria = {… transitMode : [“bus”,”tram”] …};

YN
transitRoutingPreference [Array] [Optional][Android]

Specifies preferences for transit routes. This parameter may only be specified for transit directions, and only if the request includes an API key or a Google Maps API for Work client ID.

The parameter supports the following arguments:

  • less_walking: indicates that the calculated route should prefer limited amounts of walking.

  • fewer_transfers : indicates that the calculated route should prefer a limited number of transfers.

  • routeOptimization [String] [Optional] [Windows] : Route optimization criteria. Here are the supported values.

YN
apiKey [String] [Optional] [Android]Google Maps V2 api key that the Google Direction API uses to determine your usage quota and rate limits. If you do not have a key, you can obtain one here.YN
clientID [String] [Optional] [Android]

Use clientID to access the special features of the Google Maps API for Work along with the signature property. More details about acquiring and using clientID can be found here.

Note: You must mention the apiKey or [clientID + signature], otherwise, the request will fail. apiKey and clientID are mutually exclusive and using both in the same request causes the route search to fail.

YN
signature [String] [Optional] [Android]Use signature to access the special features of the Google Maps API for Work along with clientID property. More details about acquiring and using signature can be found here.YN
 

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.

Platform Specific properties

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

iOS

Android

Windows :

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:

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 Kony Quantum App.

Copyright © 2013 Kony, Inc. All rights reserved.

Open topic with navigation