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

GET

https://api.nextbillion.io/distancematrix/json?key={your_api_key}

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

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

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=car to get distance and duration values for a route that a car can take
avoid = highway to 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=highway

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
{
   "status": "Ok",
   "rows": [
       {
           "elements": [
               {
                   "duration": {
                       "value": 2129
                   },
                   "distance": {
                       "value": 20038
                   }
               },
               {
                   "duration": {
                       "value": 1653
                   },
                   "distance": {
                       "value": 18253
                   }
               },
               {
                   "duration": {
                       "value": 2270
                   },
                   "distance": {
                       "value": 32081
                   }
               }
           ]
       },
       {
           "elements": [
               {
                   "duration": {
                       "value": 638
                   },
                   "distance": {
                       "value": 4698
                   }
               },
               {
                   "duration": {
                       "value": 909
                   },
                   "distance": {
                       "value": 6710
                   }
               },
               {
                   "duration": {
                       "value": 1648
                   },
                   "distance": {
                       "value": 23745
                   }
               }
           ]
       },
       {
           "elements": [
               {
                   "duration": {
                       "value": 1822
                   },
                   "distance": {
                       "value": 13559
                   }
               },
               {
                   "duration": {
                       "value": 1487
                   },
                   "distance": {
                       "value": 15556
                   }
               },
               {
                   "duration": {
                       "value": 2103
                   },
                   "distance": {
                       "value": 29384
                   }
               }
           ]
       }
   ]
}

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:

approaches for each of the destinations
bearings for each of the origins and destinations

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,45

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
{
   "status": "Ok",
   "rows": [
       {
           "elements": [
               {
                   "duration": {
                       "value": 2203
                   },
                   "distance": {
                       "value": 19979
                   }
               },
               {
                   "duration": {
                       "value": 1659
                   },
                   "distance": {
                       "value": 18272
                   }
               },
               {
                   "duration": {
                       "value": 2355
                   },
                   "distance": {
                       "value": 31976
                   }
               },
               {
                   "duration": {
                       "value": 2697
                   },
                   "distance": {
                       "value": 34487
                   }
               },
               {
                   "duration": {
                       "value": 2190
                   },
                   "distance": {
                       "value": 26214
                   }
               }
           ]
       },
       {
           "elements": [
               {
                   "duration": {
                       "value": 802
                   },
                   "distance": {
                       "value": 5035
                   }
               },
               {
                   "duration": {
                       "value": 906
                   },
                   "distance": {
                       "value": 6710
                   }
               },
               {
                   "duration": {
                       "value": 1733
                   },
                   "distance": {
                       "value": 23745
                   }
               },
               {
                   "duration": {
                       "value": 2075
                   },
                   "distance": {
                       "value": 26256
                   }
               },
               {
                   "duration": {
                       "value": 1568
                   },
                   "distance": {
                       "value": 17984
                   }
               }
           ]
       },
       {
           "elements": [
               {
                   "duration": {
                       "value": 1953
                   },
                   "distance": {
                       "value": 13632
                   }
               },
               {
                   "duration": {
                       "value": 1425
                   },
                   "distance": {
                       "value": 15283
                   }
               },
               {
                   "duration": {
                       "value": 2121
                   },
                   "distance": {
                       "value": 28987
                   }
               },
               {
                   "duration": {
                       "value": 2463
                   },
                   "distance": {
                       "value": 31498
                   }
               },
               {
                   "duration": {
                       "value": 1956
                   },
                   "distance": {
                       "value": 23226
                   }
               }
           ]
       },
       {
           "elements": [
               {
                   "duration": {
                       "value": 1737
                   },
                   "distance": {
                       "value": 11646
                   }
               },
               {
                   "duration": {
                       "value": 1034
                   },
                   "distance": {
                       "value": 7101
                   }
               },
               {
                   "duration": {
                       "value": 1743
                   },
                   "distance": {
                       "value": 21564
                   }
               },
               {
                   "duration": {
                       "value": 2085
                   },
                   "distance": {
                       "value": 24075
                   }
               },
               {
                   "duration": {
                       "value": 1130
                   },
                   "distance": {
                       "value": 9211
                   }
               }
           ]
       }
   ]
}

POST Request Example

Let’s see how to build a Distance Matrix POST method request for the same scenario from Example 2 above

1
2
3
4
5
6
7
8
9
10
curl --location --request POST 'https://api.nextbillion.io/distancematrix/json?key=<your_api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
"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",
    "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,45"
}'

Distance Matrix Flexible API

GET

https://api.nextbillion.io/distancematrix/json?option=flexible&key={your_api_key}

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

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

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

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=truck to get distance and duration values 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=1685371968

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
{
   "status": "Ok",
   "rows": [
       {
           "elements": [
               {
                   "duration": {
                       "value": 1593
                   },
                   "distance": {
                       "value": 15261
                   }
               },
               {
                   "duration": {
                       "value": 1711
                   },
                   "distance": {
                       "value": 17487
                   }
               },
               {
                   "duration": {
                       "value": 2400
                   },
                   "distance": {
                       "value": 24945
                   }
               }
           ]
       },
       {
           "elements": [
               {
                   "duration": {
                       "value": 476
                   },
                   "distance": {
                       "value": 4575
                   }
               },
               {
                   "duration": {
                       "value": 641
                   },
                   "distance": {
                       "value": 7004
                   }
               },
               {
                   "duration": {
                       "value": 1290
                   },
                   "distance": {
                       "value": 14259
                   }
               }
           ]
       },
       {
           "elements": [
               {
                   "duration": {
                       "value": 1306
                   },
                   "distance": {
                       "value": 13381
                   }
               },
               {
                   "duration": {
                       "value": 1346
                   },
                   "distance": {
                       "value": 13951
                   }
               },
               {
                   "duration": {
                       "value": 2114
                   },
                   "distance": {
                       "value": 23065
                   }
               }
           ]
       },
       {
           "elements": [
               {
                   "duration": {
                       "value": 1080
                   },
                   "distance": {
                       "value": 11641
                   }
               },
               {
                   "duration": {
                       "value": 665
                   },
                   "distance": {
                       "value": 6887
                   }
               },
               {
                   "duration": {
                       "value": 1451
                   },
                   "distance": {
                       "value": 16897
                   }
               }
           ]
       }
   ]
}

POST Request Example

Let’s see how to build a Distance Matrix Flexible POST method request for the same scenario from the example above

1
2
3
4
5
6
7
8
9
curl --location --request POST 'https://api.nextbillion.io/distancematrix/json?key=<your_api_key>&option=flexible' \
--header 'Content-Type: application/json' \
--data-raw '{
"origins":"34.06837391,-118.34429779|34.05930480,-118.37538887|34.02229277,-118.37407516",
"destinations":"33.97219196,-118.25627941|33.90534494,-118.25452780|33.84717446,-118.24795926",
    "mode":"truck",
    "avoid":"highway",
    "departure_time":1684911995
    }'

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 support@nextbillion.ai
For the Distance Matrix Flexible version, NextBillion.ai allows a default limit of up to
1. 50x50 Origin x Destination set i.e. 2500 elements
2. 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 support@nextbillion.ai
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_size are 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 support@nextbillion.ai 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.
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 support@nextbillion.ai for an explanation.
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 support@nextbillion.ai if the issue still persists.

Distance Matrix API

Introduction

Distance Matrix Fast API

GET Request

Request Parameters

POST Request

Response Schema

Sample Queries-Distance Matrix Fast

GET Request Example 1

Request

Response

GET Request Example 2

Request

Response

POST Request Example

Distance Matrix Flexible API

GET Request

Request Parameters

POST Request

Response Schema

Sample Queries-Distance Matrix Flexible

GET Request Example

Request

Response

POST Request Example

API Query Limits

API Error Codes

PRODUCTS

SOLUTIONS

COMPARE

DEVELOPERS

GUIDES

RESOURCES

COMPANY

UNITED STATES

SINGAPORE