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

https://api.nextbillion.io/snapToRoads/json?key={your_api_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|34.05029825,-118.29896811|34.04873267,-118.24571761|34.02951637,-118.23833125&radiuses=20|25|15|30&timestamps=1681834632|1681835232|1681835832|1681836632'

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
{
    "status": "Ok",
    "snappedPoints": [
        {
            "location": {
                "latitude": 34.026471,
                "longitude": -118.313533
            },
            "originalIndex": 0,
            "distance": 16.0,
            "name": "W 31st St",
            "bearing": 89.0
        },
        {
            "location": {
                "latitude": 34.050298,
                "longitude": -118.298938
            },
            "originalIndex": 1,
            "distance": 2.0,
            "name": "S Mariposa Ave",
            "bearing": 0.0
        },
        {
            "location": {
                "latitude": 34.048518,
                "longitude": -118.245483
            },
            "originalIndex": 2,
            "distance": 32.0,
            "name": "",
            "bearing": 231.0
        },
        {
            "location": {
                "latitude": 34.030078,
                "longitude": -118.238943
            },
            "originalIndex": 3,
            "distance": 84.0,
            "name": "S Alameda St",
            "bearing": 182.0
        }
    ],
    "distance": 12870,
    "geometry": [
        "mxtnEpbcqU?mH?yN?wBoA@oA?U?q@@wB@iD@kD@uD@gC@Y?W?m@?W?Q@M?k@?a@?o@?kA@G?W?cA?Q?i@AM?kB@sC?S?O?A?M?I?KGA?CAE?Y?O?m@?SA_@?Co@GwAGeBKkCCa@E{AAaB?{BA}A?WAi@AK@c@?k@@o@F{ABOD]Bg@FmAFcAB_@Bs@@a@?q@?eA?gA?m@?UEE[EIA]?O@W?a@?O@YJE@e@AY?W@_@?U@g@?]?yA@g@?S?I?UA[@C?a@@K?K@G@K@SDMB]H_AVIBQDQDMBc@Fa@Bc@Bm@?}@AQ?K@a@?o@Cc@CIAMCKAOCSEa@KGCSGq@Qc@KGAIAMCKAA?EAI?M?WA[Ao@?M?a@AS?O?k@?}@?]?sA?W?SAKAOCEAGAu@WMEWIMCEAK?GAC?u@@C?mAA{D@?qEsD@eA?qB?cE?cA?S?aA??_A?g@?S?YA{@?aB?e@?gA?uA?g@?uAAeA?e@?aBAuA?g@?sA?mA?YAg@?i@?U@q@?_@?G?E?K@S@I@KBKBKFe@BKHe@Da@Dg@@O?I?I@U?Q?GAS?A?SAoB?K?k@?yA?mB?O@I?[?[?kA?_B?S?Q?K?w@?g@?_BAi@?wA?gA?i@?e@?S?aABm@Bq@@SF_BBq@HwBFeBDs@B}@Be@D[BWD]BG@IBKBGBG@GFMJYFKVo@La@L[HWJYFOHUHUVs@Z_ARk@HSTo@Pi@Z_ARk@Ng@^gA\\cAPg@HUFS`@mAL]Rk@FSL]\\cATq@Pe@Pm@HWFOHUNa@Tq@L_@DIJ]Vs@L[\\_AJYPg@DOL_@Vw@Ti@FOFQn@mBHSHWFQL_@BKHQVw@FORk@H]L]LYLWDKJSNc@Xy@L_@V}@Ne@DMRe@UOi@_@e@WYSKGgAq@s@g@IEi@]KGq@]sA{@YU[[SWWc@CCe@y@[e@KOOSWg@Wi@a@{@Wk@Uc@O[OWa@{@IMg@_AKQIOGKKOWc@g@}@Q[Wg@U]IM}@{AKOKQOUOY]g@QWOQ[e@OSSYU]OUGIOQSYUYIIAAGGOQEECAAAGCc@_@]a@w@m@][WS]]SYGMCICOAI?G?E@I@EDKDKBEFEHGHEJC\\KPINMFEFKJOHOd@u@Zk@jAmBrC_FLUHQrAmCFODGHS`@q@Va@r@oAZi@\\o@NWVc@~@}A`AgBT[HOp@gAd@{@`@s@Xg@f@}@JSd@y@R]Zi@h@aAJOHKx@eAZ_@Z_@NOT[_@m@g@aAMQAACEEGYWIKSSaA}@EGA?YWWj@O\\Ub@XHDDTPFHJPHDTJv@_BRRHJXVDFBD@@LPf@`A^l@FIFKFKBGDGJWJSz@yBFMXo@JUJ[Ni@Ha@l@eCJg@Vw@Xk@~@kB|AqC|A{C`BwCb@}@P_@DMFOj@}CD_@F[@O@Oj@Br@@pGNz@B^?zELbBFt@Bz@@t@@X@n@@d@@|DJ`ABZ@t@@d@@n@Bd@@v@BV@@?p@Bh@Bv@@f@@^@V@zABrAB~@B`@@pDP`ABhCFhCF"
    ]
}

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|34.05029825,-118.29896811|34.04873267,-118.24571761|34.02951637,-118.23833125&radiuses=20|25|15|30&timestamps=1681834632|1681835232|1681835832|1681836632&mode=truck&geometry=geojson'

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
{
    "status": "Ok",
    "snappedPoints": [
        {
            "location": {
                "latitude": 34.026471,
                "longitude": -118.313533
            },
            "originalIndex": 0,
            "distance": 16.0,
            "name": "W 31st St",
            "bearing": 89.0
        },
        {
            "location": {
                "latitude": 34.050298,
                "longitude": -118.298938
            },
            "originalIndex": 1,
            "distance": 2.0,
            "name": "S Mariposa Ave",
            "bearing": 0.0
        },
        {
            "location": {
                "latitude": 34.048518,
                "longitude": -118.245483
            },
            "originalIndex": 2,
            "distance": 32.0,
            "name": "",
            "bearing": 231.0
        },
        {
            "location": {
                "latitude": 34.030078,
                "longitude": -118.238943
            },
            "originalIndex": 3,
            "distance": 84.0,
            "name": "S Alameda St",
            "bearing": 182.0
        }
    ],
    "distance": 12870,
    "geometry": [
        "mxtnEpbcqU?mH?yN?wBoA@oA?U?q@@wB@iD@kD@uD@gC@Y?W?m@?W?Q@M?k@?a@?o@?kA@G?W?cA?Q?i@AM?kB@sC?S?O?A?M?I?KGA?CAE?Y?O?m@?SA_@?Co@GwAGeBKkCCa@E{AAaB?{BA}A?WAi@AK@c@?k@@o@F{ABOD]Bg@FmAFcAB_@Bs@@a@?q@?eA?gA?m@?UEE[EIA]?O@W?a@?O@YJE@e@AY?W@_@?U@g@?]?yA@g@?S?I?UA[@C?a@@K?K@G@K@SDMB]H_AVIBQDQDMBc@Fa@Bc@Bm@?}@AQ?K@a@?o@Cc@CIAMCKAOCSEa@KGCSGq@Qc@KGAIAMCKAA?EAI?M?WA[Ao@?M?a@AS?O?k@?}@?]?sA?W?SAKAOCEAGAu@WMEWIMCEAK?GAC?u@@C?mAA{D@?qEsD@eA?qB?cE?cA?S?aA??_A?g@?S?YA{@?aB?e@?gA?uA?g@?uAAeA?e@?aBAuA?g@?sA?mA?YAg@?i@?U@q@?_@?G?E?K@S@I@KBKBKFe@BKHe@Da@Dg@@O?I?I@U?Q?GAS?A?SAoB?K?k@?yA?mB?O@I?[?[?kA?_B?S?Q?K?w@?g@?_BAi@?wA?gA?i@?e@?S?aABm@Bq@@SF_BBq@HwBFeBDs@B}@Be@D[BWD]BG@IBKBGBG@GFMJYFKVo@La@L[HWJYFOHUHUVs@Z_ARk@HSTo@Pi@Z_ARk@Ng@^gA\\cAPg@HUFS`@mAL]Rk@FSL]\\cATq@Pe@Pm@HWFOHUNa@Tq@L_@DIJ]Vs@L[\\_AJYPg@DOL_@Vw@Ti@FOFQn@mBHSHWFQL_@BKHQVw@FORk@H]L]LYLWDKJSNc@Xy@L_@V}@Ne@DMRe@UOi@_@e@WYSKGgAq@s@g@IEi@]KGq@]sA{@YU[[SWWc@CCe@y@[e@KOOSWg@Wi@a@{@Wk@Uc@O[OWa@{@IMg@_AKQIOGKKOWc@g@}@Q[Wg@U]IM}@{AKOKQOUOY]g@QWOQ[e@OSSYU]OUGIOQSYUYIIAAGGOQEECAAAGCc@_@]a@w@m@][WS]]SYGMCICOAI?G?E@I@EDKDKBEFEHGHEJC\\KPINMFEFKJOHOd@u@Zk@jAmBrC_FLUHQrAmCFODGHS`@q@Va@r@oAZi@\\o@NWVc@~@}A`AgBT[HOp@gAd@{@`@s@Xg@f@}@JSd@y@R]Zi@h@aAJOHKx@eAZ_@Z_@NOT[_@m@g@aAMQAACEEGYWIKSSaA}@EGA?YWWj@O\\Ub@XHDDTPFHJPHDTJv@_BRRHJXVDFBD@@LPf@`A^l@FIFKFKBGDGJWJSz@yBFMXo@JUJ[Ni@Ha@l@eCJg@Vw@Xk@~@kB|AqC|A{C`BwCb@}@P_@DMFOj@}CD_@F[@O@Oj@Br@@pGNz@B^?zELbBFt@Bz@@t@@X@n@@d@@|DJ`ABZ@t@@d@@n@Bd@@v@BV@@?p@Bh@Bv@@f@@^@V@zABrAB~@B`@@pDP`ABhCFhCF"
    ]
}

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

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

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 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 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 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.

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

PRODUCTS

SOLUTIONS

COMPARE

DEVELOPERS

GUIDES

RESOURCES

COMPANY

UNITED STATES

SINGAPORE