Mappls Distance-Time Matrix API for Predictive ETA¶

Easy To Integrate Maps & Location APIs & SDKs For Web & Mobile Applications

Powered with India's most comprehensive and robust mapping functionalities.

You can get your api key to be used in this document here: https://about.mappls.com/api/

Disclaimer¶

This API is released for select use cases only; Please contact Mappls API Support or your account manager for discussions on usage of this solution.
Mappls reserves the right to revoke access of this API at its own discrection.

Document Version History¶

Version	Last Updated	Author
0.0.1	November 2021	Mappls API Team (KB)
0.0.2	July 2023	Mappls API Team (KB)

API Version History¶

Version	Last Updated	Author	Revised Sections
0.1	2021-06-17	Mappls API Team (PS)	Initial release
0.2	2021-07-01	Mappls API Team (PS)	standardizing request & response

Introduction¶

This API computes the distance and duration of a route between a set of source positions and a set of supplied target or destination positions. Optionally one can specify the date_time parameter and get the distance and duration optimized for that part of day of a week. Time based functionality is available for selected areas only. Supported region (countries) is India at the moment. Please note that maximum number of points are limited to 100 only including source and destination positions.

Getting Access¶

Before using the API in the your solution, please ensure that the related access is enabled in the Mappls Console, within your app - be it for Mobile OR Web or Cloud integration.

Copy and paste the key from your credentials section from your API keys into the access_token query parameter.
- Your static key can be secured by whitelisting its usage for particular IPs (in case of cloud app usage) OR a set of domains (in case of a web app)
- Your static key obtained from your Console is to be passed as a query parameter: access_token.

Authentication Object - `access_token` mandatory query parameter.¶

access_token: "hklmgbwzrxncdyavtsuojqpiefrbhqplnm".

Input Method¶

GET

Contructing the request cURL¶

curl --location --request GET 'https://route.mappls.com/routev2/dm/distance?source=77.26893112158996,28.550614332693453&target=77.20815617692985,28.566618140144396&profile=driving&speedTypes=predictive&date_time=1,2021-12-20T11:00&access_token=hklmgbwzrxncdyavtsuojqpiefrbhqplnm'

Request Parameters¶

Mandatory Parameters¶

source: The set of source positions, separated by a semi-colon. The input is supported as a set of latitude,longitude separated by a semi-colon(;).
- For example 77.08572454324664,28.555390931473642;77.42172454324664,28.152390931473642.
target: The set of destination positions, separated by a semi-colon. The input is supported as a set of latitude,longitude separated by a semi-colon(;).
- For example 77.08572454324664,28.555390931473642;77.42172454324664,28.152390931473642.
profile: Profile for routing engine. Choose of the available profiles available:
- driving: for 4 wheelers.
- walking: for pedestrians.
- biking: for motorized 2 wheelers.
- trucking: for heavy vehicles.
Example profile=driving. 4. speedTypes: To specify the type of ETA calculations. Available values are: - predictive (default) - used to specify predictive ETA calculation. In case if this is used, then the optional parameter of date_time becomes mandatory. - optimal: To specify ETA calculation acc. to current time but on the basis of historical traffic patterns. - traffic: To specify ETA calculation on the basis of live traffic. If speedTypes is traffic, then input date_time value of 0,"" is required.

The default value is optimal.

Optional Parameters¶

date_time: This is the local date and time at the source location along with its type. The date and time is specified in ISO 8601 format (YYYY-MM-DDThh:mm) in the local time zone of departure. For example 2020-07-24T12:00. Applicable types are:
- 0: Current departure time.
- 1: Specified departure time.
- 2: Specified arrival time.
Example: date_time=1,2021-12-20T11:00

Response Type¶

JSON: response will served as JSON

Response Parameters¶

sources: array of arrays of source coordinates object.
- lon: Longitude of the source in degrees.
- lat: Latitude of the source in degrees.
targets: array of arrays of target coordinates object.
- lon: Longitude of the target in degrees.
- lat: Latitude of the target in degrees.
sources_to_targets: Returns an array of time and distance between the sources and the targets. The array is row-ordered. This means that the time and distance from the first location to all targets forms the first row of the array, followed by the time and distance from the second source location to all target locations, etc.
- distance - The computed distance between each set of points in units specified by the units response parameter.
- time - Time in seconds. The computed time between each set of points.
- from_index - The origin index into the locations array.
- to_index - The destination index into the locations array.
units: Distance units for output. Allowable unit types are mi (miles) and km (kilometers). If no unit type is specified, the units defaults to kilometers.

Optional Parametes for `trucking` profile¶

height: (float) - The height of the truck (in meters).
width: (float) - The width of the truck (in meters).
length: (float) - The length of the truck (in meters). Default is 21.64.
weight: (float) - The weight of the truck (in metric tons). Default is 21.77.
axle_load: (float) - The axle load of the truck (in metric tons). Default is 9.07.
hazmat: (boolean) - A value indicating if the truck is carrying hazardous materials. Default is false.

Response Codes¶

Status Code	Status	Description
200	Successful Response	A happy bit of json describing your result
400	Failed to parse request	You need a valid request
400	Failed to parse location	You need a valid location object in your json request
400	Failed to parse correlated location	There was a problem with the location once correlated to the routing network
400	No profile provided	You forgot the profile parameter
400	Insufficient number of locations provided	You didn't provide enough locations
400/401	Exceeded max route locations of X	You are asking for too many locations
400	Locations are in unconnected regions.	You are routing between regions of no connectivity
400	No profile method found for 'X'	You are asking for a non-existent profile mode
400	No suitable road network near location	There were no roads applicable to your mode of travel near the input location
400	No data found for location	There was no route data found at the input location
400	No path could be found for input	There was no path found between the input locations
401	Unauthorized	Developer’s key is not allowed to send a request
403	Forbidden	Developer’s key has hit its daily/hourly limit.
405	Try a GET request instead	We only support GET requests
412	Precondition Failed	Mandatory parameter is missing
500	Internal Server Error	The request caused an error in our systems.
501	Not implemented	Not Implemented
503	Service Unavailable	Maintenance break or server down-times

Sample Response¶

{
    "sources_to_targets": [
        [
            {
                "from_index": 0,
                "distance": 23.366,
                "time": 1860,
                "to_index": 0
            }
        ]
    ],
    "sources": [
        [
            {
                "lon": 77.268931,
                "lat": 28.550614
            }
        ]
    ],
    "units": "kilometers",
    "targets": [
        [
            {
                "lon": 77.085725,
                "lat": 28.555391
            }
        ]
    ]
}