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

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

Snap To Roads API example

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.

Snap To Roads API example 2

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 [email protected] for more details.

API Error Codes

Response CodeDescriptionAdditional Notes
200Normal success case.

Normal success case.

400Input validation failed.

There is a missing or invalid parameter or a parameter with an invalid value type is added to the request.

401APIKEY not supplied or invalid.

This error occurs when the wrong API key is passed in the request or the key is missing altogether

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

404Requested host/path not found.

This error occurs when a malformed hostname is used

413Request 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 [email protected] if the issue still persists.

422Could not process the request.

The points could not be snapped successfully for the given combination of location coordinates or the parameters.

429Too many requests.

QPM or API request count quota reached

500Internal Service error.

There was an internal issue with NextBillion.ai services. You can reach out to [email protected] for an explanation.

Have Questions ?

© 2024 NextBillion.ai all rights reserved.

Privacy Policy Terms of ServiceSLASupport Services Agreement