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.

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

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

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

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 the path coordinate points
timestamps added for each of the path 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&timestamps=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&timestamps=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.

Distance Matrix

Isochrone

Snap To Roads API

Introduction

GET Request

Request Parameters

POST Request

Response Schema

Sample Queries

GET Request Example 1

Request

Response

GET Request Example 2

Request

Response

POST Request Example

API Query Limits

API Error Codes

PLATFORM

SOLUTIONS

RESOURCES

COMPANY

UNITED STATES

SINGAPORE