Mappls Driving Distance - Time Matrix API¶

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

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

Global Coverage Now Available !¶

Distance Matrix API is Now Available for 238 countries across the world.

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

Document Version History¶

Version	Last Updated	Author
0.0.5	July 2021	Mappls API Team (KB)
0.0.4	December 2020	Mappls API Team (KB)
0.0.3	December 2019	Mappls API Team (KB)
0.0.2	May 2019	Mappls API Team (KB)
0.0.1	February 2019	Mappls API Team (KB)

API Version History¶

Version	Last Updated	Author	Revised Sections
270.19.5222	2021-07-13	Mappls API Team (PS)	Global support added for `distance_matrix` resource.
250.19.5222	2020-12-15	Mappls API Team (PS)	eLoc support released
220.19.522	2019-12-19	Mappls API Team (PS)	Data update ver 22.0, Many to Many distance matrix released
200.17	2018-05-21	Mappls API Team (PS)	Data update ver 20.0, CORS enabled, “distance_matrix_traffic” introduced as resource
191.17	2018-02-07	Mappls API Team (PS)	Initial release

Introduction¶

Driving Distance-Time Matrix¶

Adding driving directions API would help to add predicted travel time & duration from a given origin point to a number of points. This REST API computes the distance and duration of a route between a source/primary position (geographical coordinates) and a list of all supplied secondary positions using to mode of route calculation i.e. optimal and shortest. Distance matrix is supported for 238 countries via the region parameter. Please note that maximum number of points are limited to 100 only including source and secondary positions.

Security Type¶

License key based authentication
IP/domain based whitelisting

Input Method¶

GET

Constructing the request URL¶

Table 1. Requesting a Route
Element	Value	Description
Base URL	`https://apis.mappls.com/advancedmaps/v1/`	Production environment
Base URL
Authorization	`"assigned_REST_license_key"`	The REST API license key authorized to access the resource
Resources	`distance_matrix`	to calculate the route & duration without considering traffic conditions.
	`distance_matrix_eta`	to get the updated duration considering live traffic; Applicable for India only “region=ind”; and “rtype=1” is not supported. This is different from `distance_matrix_traffic`; since this doesn't search for a route considering traffic, it only applies delays to the default route.
	`distance_matrix_traffic`	to search for routes considering live traffic; Applicable for India only “region=ind”; and “rtype=1” is not supported
Profile	`driving`	Meant for car routing
	`biking`	Meant for two-wheeler routing. Distance calculation with this profile is restricted to `distance_matrix` resource only. `region` & `rtype` request parameters are not supported in two-wheeler routing.
	`trucking`	Meant for truck routing. Distance calculation with this profile is restricted to `distance_matrix` resource only. `region` & `rtype` request parameters are not supported in truck routing.
Coordinates	`"start and secondary coordinates"`	The coordinates pairs on which route is to be calculated. Minumum two pairs needed.

Example URL:¶

https://apis.mappls.com/advancedmaps/v1/<assigned_license_key>/distance_matrix/driving/77.983936,28.255904;77.05993,28.487555;17ZUL7?

where: - "distance_matrix" is the chosen resource. - profile is "driving" - "77.983936,28.255904" & other similar parts after it are the positions.

Note: The position input is in decimal degree notation of longitude,latitude.

Request Parameters¶

Mandatory Parameters¶

The “bold” one’s are mandatory, and the “italic” one’s are optional.

lic_key: Allocated REST API license key. (part of URL).
source: The first location is either
- a pair of comma separated longitude & latitude value OR
- an eLoc
which is taken as the source from which distance and ETA is to be calculated for the other locations specified in the rest of the ‘secondary_locations’ (part of URL). 3. secondary_locations: The geopositions of rest of the locations whose distance from source will be calculated (part of URL). Format for each geoposition is the same as for the source, and they are semi-colon “;” delimited. For example 77.983936,28.255904;77.05993,28.487555 OR mmi000.

Optional Parameters¶

rtype type of route (integer) required for navigation, where values mean:
- 0 optimal (default)
- 1 shortest (it will calculate route by excluding access penalties like private roads, etc.)
region(string): This parameter is optional for India; for other countries (such as Sri Lanka, Nepal, Bangladesh, Bhutan + many more) this parameter is mandatory. Possible values are listed in a table here.

Parameters for Many-to-Many Distance Matrix¶

Important Note¶

sources: (integers) To specify which of the coordinates supplied in the URL are to be treated as source position for many to many distance matrix calculation, indicate that coordinate pair's index. E.g. 0;1 means that 0^th and 1^st coordinate pairs are source points. Default value is 0. The indexes must be semi-colon separated. e.g: 0;1;2;...
destinations: (integers) To specify which of the coordinates supplied in the URL are to be treated as destination position for many to many distance matrix calculation, indicate that coordinate pair's index. E.g. 2;3 means that 0^th and 1^st coordinate pairs are destination points. Default value is all. The indexes must be semi-colon separated. e.g: 3;4;5;...

Response Type¶

JSON: response will served as JSON

Response Parameters¶

responseCode: See the service dependent and general status codes.
version: API’s version information.
results: array of results, each consisting of the following parameters:
- code: if the request was successful, code is ok.
- durations: Duration in seconds for source to source (default 0), 1st, 2nd, 3rd secondary locations... from source.
- distances: Distance in meters for source to source (default 0), 1st, 2nd, 3rd secondary locations... from source.

Response Codes¶

200: To denote a successful API call.
204: DB Connection error.
400: Bad Request, User made an error while creating a valid request.
401: Unauthorized, Developer’s key is not allowed to send a request.
403: Forbidden, Developer’s key has hit its daily/hourly limit or IP or domain not white-listed.
404: HTTP not found
412: Precondition Failed, i.e. Mandatory parameter is missing
500: Internal Server Error, the request caused an error in our systems.
503: Service Unavailable, during our maintenance break or server down-times.

Sample Input¶

For 1-to-Many Calculations:¶

https://apis.mappls.com/advancedmaps/v1/<lic_key>/distance_matrix/driving/77.983936,28.255904;77.05993,28.487555;77.15993,28.587555;17ZUL7?rtype=0&region=ind

For Many-to-Many Calculations:¶

https://apis.mappls.com/advancedmaps/v1/<lic_key>/distance_matrix/driving/77.983936,28.255904;77.05993,28.487555;77.15993,28.587555;17ZUL7?sources=0;1&destinations=2;3

Sample Response¶

For 1-to-Many Calculations:¶

{
    "responseCode": 200,
    "version": "191.17",
    "results": {
        "code": "Ok",
        "distances": [
            [
                0,
                6817.7,
                20475.7
            ]
        ],
        "durations": [
            [
                0,
                1844.4,
                5307.5
            ]
        ]
    }
}

For Many-to-Many Calculations:¶

{
    "responseCode": 200,
    "version": "191.17",
    "results": {
        "code": "Ok",
        "distances": [
            [
                128266.7,
                125884
            ],
            [
                18709.9,
                29030.3
            ]
        ],
        "durations": [
            [
                10306.6,
                10221.1
            ],
            [
                1213.3,
                2104.9
            ]
        ]
    }
}