Isochrone API

Introduction

An isochrone is a line that connects points of equal travel time or equal travel distance around a given location. NextBillion.ai’s Isochrone API computes areas that are reachable within a specified amount of time from a location and returns the reachable regions as contours of polygons or lines that you can display on a map. This API also supports contours based on distance. With the Isochrone API user’s can easily define serviceable areas or delivery zones based on travel times from a starting location.

The Isochrone API can be accessed through the HTTPS GET method. Let’s take a look at the features and properties of this service.

Request URL: https://api.nextbillion.io/isochrone/json?{key}

Request Parameters

Response Schema

Sample Queries

GET Request Example 1

Let’s build a basic Isochrone API request to determine the area that a car can cover within a driving time of 20 minutes when a given coordinates is the starting point.

Request

https://api.nextbillion.io/isochrone/json?key=<your_api_key>&coordinates=34.03849472,-118.24424250&mode=car&contours_minutes=20

Response

1{
2  "features": [
3    {
4      "properties": {
5        "fill": "#bf4040",
6        "fillOpacity": 0.33,
7        "fillColor": "#bf4040",
8        "color": "#bf4040",
9        "contour": 20.0,
10        "opacity": 0.33,
11        "metric": "time"
12      },
13      "geometry": {
14        "coordinates": [
15          [-118.218242, 34.084637],
16          [-118.221472, 34.084495],
17          [-118.226242, 34.081238],
18          [-118.228242, 34.082173],
19          [-118.229808, 34.07806],
20          [-118.233083, 34.077335],
21          [-118.234967, 34.07522],
22          [-118.235984, 34.072236],
23          [-118.238628, 34.070881],
24          [-118.242126, 34.070612],
25          [-118.245264, 34.071473],
26          [-118.249017, 34.07372],
27          [-118.250708, 34.07603],
28          [-118.258242, 34.077355],
29          [-118.260242, 34.079508],
30          [-118.263544, 34.078495],
31          [-118.266591, 34.074495],
32          [-118.276243, 34.074068],
33          [-118.280243, 34.072223],
34          [-118.283041, 34.072495],
35          [-118.282976, 34.070495],
36          [-118.281091, 34.068495],
37          [-118.27999, 34.064495],
38          [-118.281572, 34.058495],
39          [-118.284243, 34.056938],
40          [-118.283525, 34.052495],
41          [-118.284377, 34.050495],
42          [-118.286571, 34.050166],
43          [-118.288242, 34.052295],
44          [-118.292597, 34.048849],
45          [-118.294199, 34.046451],
46          [-118.300771, 34.045023],
47          [-118.302242, 34.041642],
48          [-118.304243, 34.041699],
49          [-118.314242, 34.037908],
50          [-118.318243, 34.038512],
51          [-118.320625, 34.036495],
52          [-118.318243, 34.035248],
53          [-118.306041, 34.034697],
54          [-118.302242, 34.032265],
55          [-118.300242, 34.032143],
56          [-118.296242, 34.029124],
57          [-118.294243, 34.029661],
58          [-118.292242, 34.026711],
59          [-118.290243, 34.027639],
60          [-118.286242, 34.024853],
61          [-118.281521, 34.025216],
62          [-118.280606, 34.024495],
63          [-118.281892, 34.014495],
64          [-118.27981, 34.006927],
65          [-118.276243, 34.005143],
66          [-118.275083, 34.002495],
67          [-118.272242, 34.000733],
68          [-118.270243, 34.000319],
69          [-118.267046, 34.002495],
70          [-118.264784, 34.002495],
71          [-118.260242, 33.99825],
72          [-118.258242, 34.000479],
73          [-118.256017, 33.996495],
74          [-118.252243, 33.992307],
75          [-118.250242, 33.994882],
76          [-118.248243, 33.992047],
77          [-118.246242, 33.994558],
78          [-118.244242, 33.991648],
79          [-118.242749, 33.993002],
80          [-118.242703, 33.996955],
81          [-118.240242, 33.997272],
82          [-118.239477, 33.996495],
83          [-118.239653, 33.993906],
84          [-118.241464, 33.992495],
85          [-118.238243, 33.989843],
86          [-118.230685, 33.994937],
87          [-118.226356, 33.996608],
88          [-118.221496, 34.000495],
89          [-118.222109, 34.002495],
90          [-118.2193, 34.004495],
91          [-118.219161, 34.006495],
92          [-118.218242, 34.007245],
93          [-118.216129, 34.006495],
94          [-118.214888, 34.004495],
95          [-118.205839, 34.000899],
96          [-118.204242, 33.999377],
97          [-118.202243, 33.999707],
98          [-118.19935, 34.001602],
99          [-118.198668, 34.002495],
100          [-118.199514, 34.004495],
101          [-118.198242, 34.00523],
102          [-118.197075, 34.003663],
103          [-118.190242, 34.001067],
104          [-118.184934, 34.002495],
105          [-118.190732, 34.006005],
106          [-118.191215, 34.006495],
107          [-118.190242, 34.006862],
108          [-118.183823, 34.006915],
109          [-118.180242, 34.003993],
110          [-118.174079, 34.004331],
111          [-118.17409, 34.006647],
112          [-118.178421, 34.008316],
113          [-118.183135, 34.012495],
114          [-118.171755, 34.016495],
115          [-118.170687, 34.018939],
116          [-118.165983, 34.022236],
117          [-118.167099, 34.026495],
118          [-118.165696, 34.027948],
119          [-118.164804, 34.031056],
120          [-118.160243, 34.033132],
121          [-118.158242, 34.03546],
122          [-118.156243, 34.034636],
123          [-118.154242, 34.035687],
124          [-118.152242, 34.034892],
125          [-118.150243, 34.036689],
126          [-118.148604, 34.036857],
127          [-118.14925, 34.040495],
128          [-118.148242, 34.041461],
129          [-118.146691, 34.040047],
130          [-118.144165, 34.040495],
131          [-118.146243, 34.044161],
132          [-118.148242, 34.044198],
133          [-118.150243, 34.046458],
134          [-118.152242, 34.045947],
135          [-118.157895, 34.048495],
136          [-118.154242, 34.050097],
137          [-118.152242, 34.051973],
138          [-118.150077, 34.052329],
139          [-118.150243, 34.053994],
140          [-118.157112, 34.053625],
141          [-118.157836, 34.054495],
142          [-118.157064, 34.056495],
143          [-118.160243, 34.057437],
144          [-118.16083, 34.058495],
145          [-118.158768, 34.06102],
146          [-118.156243, 34.061522],
147          [-118.154242, 34.060039],
148          [-118.146243, 34.059829],
149          [-118.145301, 34.060495],
150          [-118.147207, 34.06153],
151          [-118.148242, 34.063464],
152          [-118.15055, 34.064495],
153          [-118.148242, 34.066785],
154          [-118.147267, 34.069519],
155          [-118.143342, 34.070495],
156          [-118.148461, 34.070714],
157          [-118.149172, 34.069424],
158          [-118.152242, 34.069156],
159          [-118.153317, 34.067569],
160          [-118.156243, 34.067201],
161          [-118.157344, 34.065597],
162          [-118.160898, 34.06515],
163          [-118.162242, 34.063268],
164          [-118.16348, 34.064495],
165          [-118.161558, 34.06581],
166          [-118.161117, 34.069369],
167          [-118.15966, 34.070495],
168          [-118.160243, 34.074449],
169          [-118.161511, 34.071763],
170          [-118.162844, 34.071096],
171          [-118.163244, 34.068495],
172          [-118.165438, 34.066495],
173          [-118.166242, 34.063917],
174          [-118.168268, 34.064495],
175          [-118.170242, 34.066574],
176          [-118.175037, 34.066495],
177          [-118.176316, 34.068421],
178          [-118.179534, 34.066495],
179          [-118.180242, 34.063866],
180          [-118.184779, 34.063959],
181          [-118.186242, 34.066303],
182          [-118.188243, 34.065206],
183          [-118.190242, 34.066332],
184          [-118.194242, 34.065274],
185          [-118.195507, 34.066495],
186          [-118.195183, 34.067436],
187          [-118.191562, 34.068495],
188          [-118.193463, 34.071274],
189          [-118.194242, 34.075892],
190          [-118.198242, 34.074451],
191          [-118.200242, 34.071701],
192          [-118.202243, 34.074057],
193          [-118.206243, 34.07304],
194          [-118.216243, 34.077297],
195          [-118.218242, 34.075552],
196          [-118.220243, 34.075291],
197          [-118.226697, 34.07604],
198          [-118.22321, 34.081462],
199          [-118.220243, 34.082134],
200          [-118.219889, 34.084141],
201          [-118.216723, 34.084495],
202          [-118.218242, 34.084637]
203        ],
204        "type": "LineString"
205      },
206      "type": "Feature"
207    }
208  ],
209  "type": "FeatureCollection"
210}
211

Here is how the above response looks on a map. We can easily visualize the area reachable within 20 minutes. It is enclosed by a contour line or a polygon around the starting point provided in the coordinates parameter

GET Request Example 2

Taking the next step for the same coordinates point and same contour_minutes value, let’s expand the request to configure the following parameters:

set mode = truck to see what areas can a truck cover
set denoise to a low value to receive exact pockets of areas that can or cannot be covered within the given time

Request

https://api.nextbillion.io/isochrone/json?key=<your_api_key>&coordinates=34.03849472,-118.24424250&mode=truck&contours_minutes=20&denoise=0.001

Response

1{
2  "features": [
3    {
4      "properties": {
5        "fill": "#bf4040",
6        "fillOpacity": 0.33,
7        "fillColor": "#bf4040",
8        "color": "#bf4040",
9        "contour": 20.0,
10        "opacity": 0.33,
11        "metric": "time"
12      },
13      "geometry": {
14        "coordinates": [
15          [-118.218242, 34.084637],
16          [-118.221472, 34.084495],
17          [-118.226242, 34.081238],
18          [-118.228242, 34.082173],
19          [-118.229808, 34.07806],
20          [-118.233083, 34.077335],
21          [-118.234967, 34.07522],
22          [-118.235984, 34.072236],
23          [-118.238628, 34.070881],
24          [-118.242126, 34.070612],
25          [-118.245264, 34.071473],
26          [-118.249017, 34.07372],
27          [-118.250708, 34.07603],
28          [-118.258242, 34.077355],
29          [-118.260242, 34.079508],
30          [-118.263544, 34.078495],
31          [-118.266591, 34.074495],
32          [-118.276243, 34.074068],
33          [-118.280243, 34.072223],
34          [-118.283041, 34.072495],
35          [-118.282976, 34.070495],
36          [-118.281091, 34.068495],
37          [-118.27999, 34.064495],
38          [-118.281572, 34.058495],
39          [-118.284243, 34.056938],
40          [-118.283525, 34.052495],
41          [-118.284377, 34.050495],
42          [-118.286571, 34.050166],
43          [-118.288242, 34.052295],
44          [-118.292597, 34.048849],
45          [-118.294199, 34.046451],
46          [-118.300771, 34.045023],
47          [-118.302242, 34.041642],
48          [-118.304243, 34.041699],
49          [-118.314242, 34.037908],
50          [-118.318243, 34.038512],
51          [-118.320625, 34.036495],
52          [-118.318243, 34.035248],
53          [-118.306041, 34.034697],
54          [-118.302242, 34.032265],
55          [-118.300242, 34.032143],
56          [-118.296242, 34.029124],
57          [-118.294243, 34.029661],
58          [-118.292242, 34.026711],
59          [-118.290243, 34.027639],
60          [-118.286242, 34.024853],
61          [-118.281521, 34.025216],
62          [-118.280606, 34.024495],
63          [-118.281892, 34.014495],
64          [-118.27981, 34.006927],
65          [-118.276243, 34.005143],
66          [-118.275083, 34.002495],
67          [-118.272242, 34.000733],
68          [-118.270243, 34.000319],
69          [-118.267046, 34.002495],
70          [-118.264784, 34.002495],
71          [-118.260242, 33.99825],
72          [-118.258242, 34.000479],
73          [-118.256017, 33.996495],
74          [-118.252243, 33.992307],
75          [-118.250242, 33.994882],
76          [-118.248243, 33.992047],
77          [-118.246242, 33.994558],
78          [-118.244242, 33.991648],
79          [-118.242749, 33.993002],
80          [-118.242703, 33.996955],
81          [-118.240242, 33.997272],
82          [-118.239477, 33.996495],
83          [-118.239653, 33.993906],
84          [-118.241464, 33.992495],
85          [-118.238243, 33.989843],
86          [-118.230685, 33.994937],
87          [-118.226356, 33.996608],
88          [-118.221496, 34.000495],
89          [-118.222109, 34.002495],
90          [-118.2193, 34.004495],
91          [-118.219161, 34.006495],
92          [-118.218242, 34.007245],
93          [-118.216129, 34.006495],
94          [-118.214888, 34.004495],
95          [-118.205839, 34.000899],
96          [-118.204242, 33.999377],
97          [-118.202243, 33.999707],
98          [-118.19935, 34.001602],
99          [-118.198668, 34.002495],
100          [-118.199514, 34.004495],
101          [-118.198242, 34.00523],
102          [-118.197075, 34.003663],
103          [-118.190242, 34.001067],
104          [-118.184934, 34.002495],
105          [-118.190732, 34.006005],
106          [-118.191215, 34.006495],
107          [-118.190242, 34.006862],
108          [-118.183823, 34.006915],
109          [-118.180242, 34.003993],
110          [-118.174079, 34.004331],
111          [-118.17409, 34.006647],
112          [-118.178421, 34.008316],
113          [-118.183135, 34.012495],
114          [-118.171755, 34.016495],
115          [-118.170687, 34.018939],
116          [-118.165983, 34.022236],
117          [-118.167099, 34.026495],
118          [-118.165696, 34.027948],
119          [-118.164804, 34.031056],
120          [-118.160243, 34.033132],
121          [-118.158242, 34.03546],
122          [-118.156243, 34.034636],
123          [-118.154242, 34.035687],
124          [-118.152242, 34.034892],
125          [-118.150243, 34.036689],
126          [-118.148604, 34.036857],
127          [-118.14925, 34.040495],
128          [-118.148242, 34.041461],
129          [-118.146691, 34.040047],
130          [-118.144165, 34.040495],
131          [-118.146243, 34.044161],
132          [-118.148242, 34.044198],
133          [-118.150243, 34.046458],
134          [-118.152242, 34.045947],
135          [-118.157895, 34.048495],
136          [-118.154242, 34.050097],
137          [-118.152242, 34.051973],
138          [-118.150077, 34.052329],
139          [-118.150243, 34.053994],
140          [-118.157112, 34.053625],
141          [-118.157836, 34.054495],
142          [-118.157064, 34.056495],
143          [-118.160243, 34.057437],
144          [-118.16083, 34.058495],
145          [-118.158768, 34.06102],
146          [-118.156243, 34.061522],
147          [-118.154242, 34.060039],
148          [-118.146243, 34.059829],
149          [-118.145301, 34.060495],
150          [-118.147207, 34.06153],
151          [-118.148242, 34.063464],
152          [-118.15055, 34.064495],
153          [-118.148242, 34.066785],
154          [-118.147267, 34.069519],
155          [-118.143342, 34.070495],
156          [-118.148461, 34.070714],
157          [-118.149172, 34.069424],
158          [-118.152242, 34.069156],
159          [-118.153317, 34.067569],
160          [-118.156243, 34.067201],
161          [-118.157344, 34.065597],
162          [-118.160898, 34.06515],
163          [-118.162242, 34.063268],
164          [-118.16348, 34.064495],
165          [-118.161558, 34.06581],
166          [-118.161117, 34.069369],
167          [-118.15966, 34.070495],
168          [-118.160243, 34.074449],
169          [-118.161511, 34.071763],
170          [-118.162844, 34.071096],
171          [-118.163244, 34.068495],
172          [-118.165438, 34.066495],
173          [-118.166242, 34.063917],
174          [-118.168268, 34.064495],
175          [-118.170242, 34.066574],
176          [-118.175037, 34.066495],
177          [-118.176316, 34.068421],
178          [-118.179534, 34.066495],
179          [-118.180242, 34.063866],
180          [-118.184779, 34.063959],
181          [-118.186242, 34.066303],
182          [-118.188243, 34.065206],
183          [-118.190242, 34.066332],
184          [-118.194242, 34.065274],
185          [-118.195507, 34.066495],
186          [-118.195183, 34.067436],
187          [-118.191562, 34.068495],
188          [-118.193463, 34.071274],
189          [-118.194242, 34.075892],
190          [-118.198242, 34.074451],
191          [-118.200242, 34.071701],
192          [-118.202243, 34.074057],
193          [-118.206243, 34.07304],
194          [-118.216243, 34.077297],
195          [-118.218242, 34.075552],
196          [-118.220243, 34.075291],
197          [-118.226697, 34.07604],
198          [-118.22321, 34.081462],
199          [-118.220243, 34.082134],
200          [-118.219889, 34.084141],
201          [-118.216723, 34.084495],
202          [-118.218242, 34.084637]
203        ],
204        "type": "LineString"
205      },
206      "type": "Feature"
207    }
208  ],
209  "type": "FeatureCollection"
210}

Here is how the above response looks. Notice a smaller polygon appears within the large one when we set denoise to a low value. This smaller polygon encloses the area that can not be reached by a truck within 20 minutes from the starting point.

API Query Limits

Only one of contours_meters or contours_minutes should be provided in the input request. A 400 error is returned if none of them are provided. We do not recommend using both contours_meters or contours_minutes together in a request.
Up to 4 isochrones can be requested using the contours_minutes parameter with a maximum allowed value of 40 minutes.
Up to 4 isochrones can be requested using the contours_meters parameter with a maximum allowed value of value of 60000 meters.
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.	Such as missing parameter or parameter with invalid value type (for example value cannot be parsed into number).
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 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 reached or API request count 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.

Snap To Roads

Navigation

Isochrone API

Introduction

Request Parameters

Response Schema

Sample Queries

GET Request Example 1

Request

Response

GET Request Example 2

Request

Response

API Query Limits

API Error Codes

PLATFORM

SOLUTIONS

RESOURCES

COMPANY

UNITED STATES

SINGAPORE