Snap To Roads API
Introduction
NextBillion.ai’s Snap To Roads API takes a series of locations and snaps them to nearby roads representing the best-matched route where a trip took place connecting all the given locations. Users can choose to retrieve a geometry of the route connecting all the points while using several other configurations. They can also choose to receive the segment-wise speed limits of the route identified in the response.
GET Request
Users can build a basic GET request using the 2 required parameters, key
and path
, to obtain accurate road-snap data. They can further customize the request by including other optional parameters as listed in the table below.
It is recommended to use the GET method when the number of coordinate points in the path
parameter is less than 100.
Request Parameters
Loading...POST Request
Snap To Road API supports HTTPS POST method as well. The parameters and their properties for the POST method are the same as listed in the Request Parameters section. The key
is passed as a query parameter whereas other parameters need to be part of the Request Body. An example of a POST request is added in the Sample Queries section below.
Please note that the maximum number of path
coordinate points allowed in a POST request is 200.
Response Schema
Loading...Sample Queries
GET Request Example 1
Let’s create a simple snapToRoad request with:
-
4
path
coordinate points that need to be snapped to the nearest road -
radiuses
values configured for each of thepath
coordinate points -
timestamps
added for each of thepath
coordinate points
Request
curl --location 'https://api.nextbillion.io/snapToRoads/json?key=<your_api_key>&path=34.02632257,-118.31353281|33.99120320,-118.29522906|34.00024016,-118.26026685|33.99205579,-118.20885182&radiuses=20|25|15|30×tamps=1681834632|1681835232|1681835832|1681836632'
Response
1{
2 "status": "Ok",
3 "snappedPoints": [
4 {
5 "location": {
6 "latitude": 34.026045,
7 "longitude": -118.313533
8 },
9 "originalIndex": 0,
10 "distance": 30,
11 "name": "",
12 "bearing": 90
13 },
14 {
15 "location": {
16 "latitude": 33.991855,
17 "longitude": -118.29523
18 },
19 "originalIndex": 1,
20 "distance": 72,
21 "name": "",
22 "bearing": 85
23 },
24 {
25 "location": {
26 "latitude": 34.000239,
27 "longitude": -118.260267
28 },
29 "originalIndex": 2,
30 "distance": 0,
31 "name": "E 48th St",
32 "bearing": 89
33 },
34 {
35 "location": {
36 "latitude": 33.991909,
37 "longitude": -118.208509
38 },
39 "originalIndex": 3,
40 "distance": 35,
41 "name": "Alcoa Ave",
42 "bearing": 358
43 }
44 ],
45 "distance": 15925,
46 "geometry": [
47 "yutnEpbcqU@mHbBAFqhArhEIBcZnG??{BaBuq@qXB]kcDwUBAuBEwVhcAEZekH}OR"
48 ]
49}
Here is a visual representation of the above response

GET Request Example 2
Let’s take a step further and expand the request from Example 1 to add:
-
geometry
=geojson
to get the geoJSON details of the snapped path -
get a snapped route that a
truck
can take
Request
curl --location 'https://api.nextbillion.io/snapToRoads/json?key=<your_api_key>&path=34.02632257,-118.31353281|33.99120320,-118.29522906|34.00024016,-118.26026685|33.99205579,-118.20885182&radiuses=20|25|15|30×tamps=1681834632|1681835232|1681835832|1681836632&mode=truck&geometry=geojson'
Response
1{
2 "status": "Ok",
3 "snappedPoints": [
4 {
5 "location": {
6 "latitude": 34.026471,
7 "longitude": -118.313533
8 },
9 "originalIndex": 0,
10 "distance": 16,
11 "name": "W 31st St",
12 "bearing": 0
13 },
14 {
15 "location": {
16 "latitude": 33.991855,
17 "longitude": -118.29523
18 },
19 "originalIndex": 1,
20 "distance": 72,
21 "name": "",
22 "bearing": 0
23 },
24 {
25 "location": {
26 "latitude": 34.000239,
27 "longitude": -118.260267
28 },
29 "originalIndex": 2,
30 "distance": 0,
31 "name": "E 48th St",
32 "bearing": 0
33 },
34 {
35 "location": {
36 "latitude": 33.992148,
37 "longitude": -118.208515
38 },
39 "originalIndex": 3,
40 "distance": 32,
41 "name": "",
42 "bearing": 0
43 }
44 ],
45 "distance": 16236,
46 "geometry": [
47 "m}x{_Axbht`F?eaHbx@OvBc{O|~}@{Ad@wnGdtAAHme@a^ezN{v@M_BiePzw@?uCcrXw}HZm@{oGqdDZO_d@aAelFibF^d@mdw@~sAqbCp~C{UcH_zVpaFsE_ConGzrGiD"
48 ],
49 "geojson": {
50 "type": "Feature",
51 "geometry": {
52 "type": "MultiLineString",
53 "coordinates": [
54 [
55 [
56 -118.313533,
57 34.026471
58 ],
59 [
60 -118.30889,
61 34.026471
62 ],
63 [
64 -118.308882,
65 34.025557
66 ],
67 [
68 -118.30024,
69 34.025497
70 ],
71 [
72 -118.300194,
73 33.993242
74 ],
75 [
76 -118.295846,
77 33.993223
78 ],
79 [
80 -118.295845,
81 33.99186
82 ],
83 [
84 -118.29523,
85 33.991855
86 ],
87 [
88 -118.287115,
89 33.992352
90 ],
91 [
92 -118.287108,
93 33.993246
94 ],
95 [
96 -118.278303,
97 33.993294
98 ],
99 [
100 -118.278303,
101 33.992384
102 ],
103 [
104 -118.265197,
105 33.992459
106 ],
107 [
108 -118.265211,
109 33.997559
110 ],
111 [
112 -118.260845,
113 33.997582
114 ],
115 [
116 -118.260859,
117 34.000231
118 ],
119 [
120 -118.260267,
121 34.000239
122 ],
123 [
124 -118.256472,
125 34.000272
126 ],
127 [
128 -118.256488,
129 34.003909
130 ],
131 [
132 -118.227729,
133 34.00389
134 ],
135 [
136 -118.225624,
137 34.00253
138 ],
139 [
140 -118.225258,
141 33.999977
142 ],
143 [
144 -118.21305,
145 34.000123
146 ],
147 [
148 -118.212944,
149 33.996498
150 ],
151 [
152 -118.2086,
153 33.996562
154 ],
155 [
156 -118.208515,
157 33.992148
158 ]
159 ]
160 ]
161 },
162 "properties": null
163 }
164}
Below is a visual representation of the above response. Notice the slight differences in the route that is appropriate for a truck
instead of a car
from Example 1.

POST Request Example
Now, let’s see how the POST request for the same scenario from Example 2 above looks like
1curl --location --request POST 'https://api.nextbillion.io/snapToRoads/json?key=<your_api_key>'
2--header 'Content-Type: application/json'
3--data-raw '{
4"path":"34.02632257,-118.31353281|33.99120320,-118.29522906|34.00024016,-118.26026685|33.99205579,-118.20885182",
5 "radiuses":"20|25|15|30",
6 "timestamps":"1681834632|1681835232|1681835832|1681836632",
7 "mode":"truck",
8 "geometry":"geojson"
9}'
API Query Limits
-
The maximum number of coordinate points that can be added to the
path
parameter in a GET request is 100 and in a POST request is 200. -
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 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. | The points could not be snapped successfully for the given combination of location coordinates or the parameters. |
429 | Too many requests. | QPM 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. |