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 Parameters
Loading...Response Schema
Loading...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
orcontours_minutes
should be provided in the input request. A 400 error is returned if none of them are provided. We do not recommend using bothcontours_meters
orcontours_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. |