Distance Matrix API
Introduction
NextBillion.ai’s 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 a set has Origins {A,B} and Destinations {C,D,E} we can get the following matrix of results with distance (meters) 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 has 2 versions - Fast and Flexible. We will be talking about both these services below.
Distance Matrix Fast API
The Fast version returns the ETAs and distances in real time. The results returned take into account the typical traffic conditions at the time.
Distance Matrix Fast API supports both HTTPS GET and POST methods. The parameters, request URL and response schema are exactly the same for both methods. However, an important difference between these methods is the size of the origins and destinations sets that can be shared in the input. We cover both of them in the sections below.
GET Request
To utilize the Distance Matrix API and obtain estimated times of arrival (ETAs) and distances, users can make a GET request with the following required parameters: key, origins and destinations. Additionally, users can customize their request by including other optional parameters as listed in the table below.
It is recommended to use the GET method when the total number of locations including both origins and destinations is less than 100.
Request Parameters
Loading...POST Request
The parameters and their properties for the POST method of Distance Matrix Fast service are the same as listed in the Request Parameters section. The key is passed as query parameters and the rest of the parameters should be included in the Request Body. An example of a POST request is added in the Sample Queries - Distance Matrix Fast section below.
We recommend using the POST method, when the total number of locations including both origins and destinations is more than 100.
Response Schema
Loading...Sample Queries-Distance Matrix Fast
GET Request Example 1
Let’s create a simple Distance Matrix Fast request with 3 origins (O) and 3 destinations (D). We will get a 3 x 3 matrix with distance and duration values for all 9 combinations (or elements) of O x D pairs. We also set:
-
mode=carto get distance and duration values for a route that a car can take -
avoid=highwayto return results for routes without tolls
Request
https://api.nextbillion.io/distancematrix/json?origins=34.05456317,-118.31528428|33.99167000,-118.25687955|34.00792776,-118.33063151&destinations=33.96763110,-118.23215346|33.93969502,-118.26583210|33.90184293,-118.19634326&mode=car&key=<your_api_key>&avoid=highwayResponse
1{
2 "status": "Ok",
3 "rows": [
4 {
5 "elements": [
6 {
7 "duration": {
8 "value": 2129
9 },
10 "distance": {
11 "value": 20038
12 }
13 },
14 {
15 "duration": {
16 "value": 1653
17 },
18 "distance": {
19 "value": 18253
20 }
21 },
22 {
23 "duration": {
24 "value": 2270
25 },
26 "distance": {
27 "value": 32081
28 }
29 }
30 ]
31 },
32 {
33 "elements": [
34 {
35 "duration": {
36 "value": 638
37 },
38 "distance": {
39 "value": 4698
40 }
41 },
42 {
43 "duration": {
44 "value": 909
45 },
46 "distance": {
47 "value": 6710
48 }
49 },
50 {
51 "duration": {
52 "value": 1648
53 },
54 "distance": {
55 "value": 23745
56 }
57 }
58 ]
59 },
60 {
61 "elements": [
62 {
63 "duration": {
64 "value": 1822
65 },
66 "distance": {
67 "value": 13559
68 }
69 },
70 {
71 "duration": {
72 "value": 1487
73 },
74 "distance": {
75 "value": 15556
76 }
77 },
78 {
79 "duration": {
80 "value": 2103
81 },
82 "distance": {
83 "value": 29384
84 }
85 }
86 ]
87 }
88 ]
89}GET Request Example 2
Let’s modify the above request further by adding 1 more origins (O) and 2 more destinations (D). This time we will get a 4 x 5 matrix with result values for a total of 20 combinations (or elements) of O x D pairs. We will also customize our request and set:
-
approachesfor each of thedestinations -
bearingsfor each of theoriginsanddestinations
Request
https://api.nextbillion.io/distancematrix/json?origins=34.05456317,-118.31528428|33.99167000,-118.25687955|34.00792776,-118.33063151|33.94535370,-118.33148414&destinations=33.96763110,-118.23215346|33.93969502,-118.26583210|33.90184293,-118.19634326|33.93580446,-118.12173867|33.88308753,-118.32679471&mode=car&key=<your_api_key>&avoid=highway&approaches=curb;curb;;unrestricted;curb&bearings=0,45;0,45;0,45;0,45;0,45;0,45;0,45;0,45;0,45Response
1{
2 "status": "Ok",
3 "rows": [
4 {
5 "elements": [
6 {
7 "duration": {
8 "value": 2203
9 },
10 "distance": {
11 "value": 19979
12 }
13 },
14 {
15 "duration": {
16 "value": 1659
17 },
18 "distance": {
19 "value": 18272
20 }
21 },
22 {
23 "duration": {
24 "value": 2355
25 },
26 "distance": {
27 "value": 31976
28 }
29 },
30 {
31 "duration": {
32 "value": 2697
33 },
34 "distance": {
35 "value": 34487
36 }
37 },
38 {
39 "duration": {
40 "value": 2190
41 },
42 "distance": {
43 "value": 26214
44 }
45 }
46 ]
47 },
48 {
49 "elements": [
50 {
51 "duration": {
52 "value": 802
53 },
54 "distance": {
55 "value": 5035
56 }
57 },
58 {
59 "duration": {
60 "value": 906
61 },
62 "distance": {
63 "value": 6710
64 }
65 },
66 {
67 "duration": {
68 "value": 1733
69 },
70 "distance": {
71 "value": 23745
72 }
73 },
74 {
75 "duration": {
76 "value": 2075
77 },
78 "distance": {
79 "value": 26256
80 }
81 },
82 {
83 "duration": {
84 "value": 1568
85 },
86 "distance": {
87 "value": 17984
88 }
89 }
90 ]
91 },
92 {
93 "elements": [
94 {
95 "duration": {
96 "value": 1953
97 },
98 "distance": {
99 "value": 13632
100 }
101 },
102 {
103 "duration": {
104 "value": 1425
105 },
106 "distance": {
107 "value": 15283
108 }
109 },
110 {
111 "duration": {
112 "value": 2121
113 },
114 "distance": {
115 "value": 28987
116 }
117 },
118 {
119 "duration": {
120 "value": 2463
121 },
122 "distance": {
123 "value": 31498
124 }
125 },
126 {
127 "duration": {
128 "value": 1956
129 },
130 "distance": {
131 "value": 23226
132 }
133 }
134 ]
135 },
136 {
137 "elements": [
138 {
139 "duration": {
140 "value": 1737
141 },
142 "distance": {
143 "value": 11646
144 }
145 },
146 {
147 "duration": {
148 "value": 1034
149 },
150 "distance": {
151 "value": 7101
152 }
153 },
154 {
155 "duration": {
156 "value": 1743
157 },
158 "distance": {
159 "value": 21564
160 }
161 },
162 {
163 "duration": {
164 "value": 2085
165 },
166 "distance": {
167 "value": 24075
168 }
169 },
170 {
171 "duration": {
172 "value": 1130
173 },
174 "distance": {
175 "value": 9211
176 }
177 }
178 ]
179 }
180 ]
181}POST Request Example
Let’s see how to build a Distance Matrix POST method request for the same scenario from Example 2 above
1curl --location --request POST 'https://api.nextbillion.io/distancematrix/json?key=<your_api_key>' \
2--header 'Content-Type: application/json' \
3--data-raw '{
4"origins":"34.05456317,-118.31528428|33.99167000,-118.25687955|34.00792776,-118.33063151|33.94535370,-118.33148414",
5"destinations":"33.96763110,-118.23215346|33.93969502,-118.26583210|33.90184293,-118.19634326|33.93580446,-118.12173867|33.88308753,-118.32679471",
6 "mode":"car",
7 "avoid":"highway",
8 "approaches":"curb;curb;;unrestricted;curb",
9 "bearings":"0,45;0,45;0,45;0,45;0,45;0,45;0,45;0,45;0,45"
10}'Distance Matrix Flexible API
The Flexible version returns the ETAs and distances taking into consideration additional parameters like truck specific routes, specific departure time and the typical traffic conditions at the time, and a preference for the fastest or the shortest route type.
To use the Distance Matrix Flexible API service please set the option parameter to flexible. Please note some request parameters available in the Fast version are not available in the Flexible version and vice-versa.
Distance Matrix Flexible API supports both HTTPS GET and POST methods. The parameters, request URL and response schema are exactly the same for both methods. However, an important difference between these methods is the size of the origins and destinations sets that can be shared in the input. We cover both of them in the sections below.
GET Request
To utilize the Distance Matrix API and obtain estimated times of arrival (ETAs) and distances, users can make a GET request with the following required parameters: key, origins and destinations. Additionally, users can customize their request by including other optional parameters as listed in the table below.
It is recommended to use the GET method when the total number of locations including both origins and destinations is less than 50. Please check API Query Limits section to know more about the limits of Distance Matrix Flexible API.
Request Parameters
Loading...POST Request
The parameters and their properties for the POST method of Distance Matrix Flexible service are the same as listed in the Request Parameters section. The key and option are passed as query parameters and the rest of the parameters should be included in the Request Body. An example of a POST request is added in the Sample Queries - Distance Matrix Fast section below.
When the total number of locations including both origins and destinations is more than 50, we recommend using the POST method. Please check API Query Limits section to know more about the limits of Distance Matrix Flexible API.
Response Schema
Loading...Sample Queries-Distance Matrix Flexible
GET Request Example
For a Distance Matrix Flexible request with 4 origins (O) and 3 destinations (D) we will get a 4 x 3 matrix with distance and duration values for all 12 combinations (or elements) of O x D pairs. We set option as flexible along with:
-
setting
mode=truckto getdistanceanddurationvalues for a route that a truck can take -
setting a
departure_time -
avoiding highways
Request
https://api.nextbillion.io/distancematrix/json?origins=34.05456317,-118.31528428|33.99167000,-118.25687955|34.00792776,-118.33063151|33.94535370,-118.33148414&destinations=33.96763110,-118.23215346|33.93969502,-118.26583210|33.90184293,-118.19634326&mode=truck&key=<your_api_key>&avoid=highway&option=flexible&departure_time=1685371968Response
1{
2 "status": "Ok",
3 "rows": [
4 {
5 "elements": [
6 {
7 "duration": {
8 "value": 1593
9 },
10 "distance": {
11 "value": 15261
12 }
13 },
14 {
15 "duration": {
16 "value": 1711
17 },
18 "distance": {
19 "value": 17487
20 }
21 },
22 {
23 "duration": {
24 "value": 2400
25 },
26 "distance": {
27 "value": 24945
28 }
29 }
30 ]
31 },
32 {
33 "elements": [
34 {
35 "duration": {
36 "value": 476
37 },
38 "distance": {
39 "value": 4575
40 }
41 },
42 {
43 "duration": {
44 "value": 641
45 },
46 "distance": {
47 "value": 7004
48 }
49 },
50 {
51 "duration": {
52 "value": 1290
53 },
54 "distance": {
55 "value": 14259
56 }
57 }
58 ]
59 },
60 {
61 "elements": [
62 {
63 "duration": {
64 "value": 1306
65 },
66 "distance": {
67 "value": 13381
68 }
69 },
70 {
71 "duration": {
72 "value": 1346
73 },
74 "distance": {
75 "value": 13951
76 }
77 },
78 {
79 "duration": {
80 "value": 2114
81 },
82 "distance": {
83 "value": 23065
84 }
85 }
86 ]
87 },
88 {
89 "elements": [
90 {
91 "duration": {
92 "value": 1080
93 },
94 "distance": {
95 "value": 11641
96 }
97 },
98 {
99 "duration": {
100 "value": 665
101 },
102 "distance": {
103 "value": 6887
104 }
105 },
106 {
107 "duration": {
108 "value": 1451
109 },
110 "distance": {
111 "value": 16897
112 }
113 }
114 ]
115 }
116 ]
117}POST Request Example
Let’s see how to build a Distance Matrix Flexible POST method request for the same scenario from the example above
1curl --location --request POST 'https://api.nextbillion.io/distancematrix/json?key=<your_api_key>&option=flexible' \
2--header 'Content-Type: application/json' \
3--data-raw '{
4"origins":"34.06837391,-118.34429779|34.05930480,-118.37538887|34.02229277,-118.37407516",
5"destinations":"33.97219196,-118.25627941|33.90534494,-118.25452780|33.84717446,-118.24795926",
6 "mode":"truck",
7 "avoid":"highway",
8 "departure_time":1684911995
9 }'API Query Limits
-
For the Distance Matrix Fast version, NextBillion.ai allows a default limit of up to 1000x1000 Origin x Destination set. We can support up to a maximum size of 5000x5000 matrix. For higher limits please check with your NextBillion.ai account manager, sales representative or reach out at [email protected]
-
For the Distance Matrix Flexible version, NextBillion.ai allows a default limit of up to
-
50x50 Origin x Destination set i.e. 2500 elements
-
Total straight line distance of 8000km between all the points in a request.
For higher limits please check with your NextBillion.ai account manager, sales representative or reach out at [email protected]
-
-
The HTTPS GET method of the Fast version can handle up to a total of 100 locations and a total of 50 locations for the Flexible version, in a single request. In case of large matrix sizes where the total number of locations is more, using the HTTPS POST method is recommended.
-
Maximum dimensions allowed for
truck_sizeare 5000 cm for length, 5000 cm for width, 1000 cm for height. -
Maximum weight allowed for
truck_weight(including the trailer and shipped goods) is 100,000 kg -
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.
API Error Codes
| Response Code | Description | Additional Notes |
|---|---|---|
| 200 | Normal success case. | Normal success case. |
| 400 | Input validation failed. | There is a missing or an invalid parameter or a parameter with an invalid value type is added to the request. |
| 401 | APIKEY not supplied or invalid. | This error occurs when the wrong API key is passed in the request or the key is missing altogether |
| 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 a malformed hostname is used. |
| 413 | Request entity too large | This error is caused when the length of input request URI or the request body is too large. Please modify the request. Reach out to [email protected] if the issue still persists. |
| 422 | Could not process the request. | Unroutable coordinates provided in the request, please check API response for more details. |
| 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. |
