Distance Matrix API
Introduction
Nextbillion.ai Distance Matrix API computes distances and ETAs between a set of origins and destinations — could be for one-to-many or many-to-many scenarios. The API call returns a matrix of ETAs and distances for each origin and destination pair.
For example, if the set is Origins {A,B} and destinations {C,D,E} we can get the following set of results with Distance (metres) and Time (seconds) for each.
| C | D | E | |
|---|---|---|---|
A | A -> C | A -> D | A -> E |
B | B -> C | B -> D | B -> E |
The Distance Matrix API returns the most efficient route with distance in metres and time in seconds.
Parameters
Loading...Response Schema
Loading...Query Limits
Nextbillion.ai allows a maximum rate limit of 6000 queries per minute or 100 queries/second for continuous requests.
Note: We can increase the quota if needed on request. Contact [email protected] for more details.
Examples
GET API Request
https://api.nextbillion.io/distancematrix/json?origins=12.99135655,77.57688153|12.98868026,77.59782421|12.98165485,77.63181317&destinations=12.96258487,77.57001507|12.95907182,77.59799588|12.96107928,77.62220013&mode=4w&key=<Insert your Key here>POST API Request
1curl --location -g --request POST 'https://api.nextbillion.io/distancematrix/json?key={{api_key}}' \
2--data-raw '{
3 "departure_time": {{cur-time}},
4 "origins": "34.0451,-118.2346|34.1111,-118.2830|33.9502,-118.0776|34.0624,-118.1259|33.8606,-118.2828",
5 "destinations": "33.9655,-118.0171|33.9554,-118.0875|33.8642,-118.0225|34.1022,-118.0015|33.9366,-118.0993",
6 "mode": "car"
7}'Sample API Response
1{
2 "status": "Ok",
3 "rows": [
4 {
5 "elements": [
6 {
7 "duration": {
8 "value": 922
9 },
10 "distance": {
11 "value": 4415
12 }
13 },
14 {
15 "duration": {
16 "value": 1349
17 },
18 "distance": {
19 "value": 6127
20 }
21 },
22 {
23 "duration": {
24 "value": 1376
25 },
26 "distance": {
27 "value": 7380
28 }
29 }
30 ]
31 },
32 {
33 "elements": [
34 {
35 "duration": {
36 "value": 1232
37 },
38 "distance": {
39 "value": 6199
40 }
41 },
42 {
43 "duration": {
44 "value": 1067
45 },
46 "distance": {
47 "value": 4409
48 }
49 },
50 {
51 "duration": {
52 "value": 1025
53 },
54 "distance": {
55 "value": 5135
56 }
57 }
58 ]
59 },
60 {
61 "elements": [
62 {
63 "duration": {
64 "value": 1522
65 },
66 "distance": {
67 "value": 8366
68 }
69 },
70 {
71 "duration": {
72 "value": 1013
73 },
74 "distance": {
75 "value": 6033
76 }
77 },
78 {
79 "duration": {
80 "value": 642
81 },
82 "distance": {
83 "value": 3648
84 }
85 }
86 ]
87 }
88 ]
89}API Error Codes
| Response Code | Description | Additional Notes |
|---|---|---|
| 200 | Normal success case. | Normal success case. |
| 400 | Input validation failed. | Such as missing parameter or parameter with invalid value type (for example value cannot be parsed into number). |
| 401 | APIKEY not supplied or invalid. | - |
| 403 | APIKEY is valid but does not have access to requested resources. | You might be querying for a geographical region which is not valid for your account, or requesting a service which is not enabled for you. |
| 404 | Requested host/path not found. | This error occurs when there is a malformed host name used. |
| 422 | Could not process the request. | There is an underlying map issue which prevents the processing of the request. |
| 429 | Too many requests. | QPM limit or distance matrix size quota reached |
| 500 | Internal Service error. | There was an internal issue with Nextbillion.ai services. You can reach out to [email protected] for an explanation. |
Directions
Snap To Roads
