Route Report API

Introduction

NextBillion.ai’s Route Report API is a useful service to get a comprehensive report of a trip. Users can provide the geometry of the desired route or trip and then get details like duration, distance covered during the trip - broken down by state, country, road class along with maximum speeds on the road segments forming the route. The service also informs if the route has any tolls, bridges, tunnels or roundabout maneuvers along it. The service is useful for comparing routes, computing drive mileage and estimating associated metrics as per your business needs.

A valid Route Report request can be submitted using an HTTPS POST method containing the desired route geometry and its encoding type through a request body.

POST

https://api.nextbillion.io/route_report?key={your_api_key}&option=flexible

Request Parameters

Request Body

Response Schema

Example

Let’s request a report and other stats for a trip made across multiple states by providing a sample route geometry.

Sample API Request

1
curl --location 'https://api.nextbillion.io/route_report?option=flexible&key=<your_api_key>' \
2
--header 'Content-Type: application/json' \
3
--data-raw '{
4
    "original_shape": "u`kbGjekhPa@R??\\dB?@j@jB?@~CoA~As@PIVINCPCMaAKeA?AIc@Ha@FSDKHEHCHEPGl@QB?XA??^???BAB?B???@?J@B?J@p@FdAJ??^BPBN@??n@Jr@HZD@S??@W?AFaA@Q??@OHwB??BiAI[??NaDFqAJsABk@Bu@Ba@??Be@?a@?i@?mEA_A?eAAeFGuIAq@CqFIwJEcIMwD?a@?sD?}A?}ACmIA}AAqCC_D?i@Ae@?[?U@]@[@WBYB_@Da@??BQDSDI@?He@?AXuABGJg@??NMHEBADAD?D@FD@BDFFJHRU`@eApBu@vAOV??a@c@?Ag@i@??KM?Ac@c@??MSAEGKEQQk@U{@??Oi@EQ_@sAkA{DAE?AeAcEAGO_@KSKMKO??s@i@a@_@QOGISWaAaBQ[KO]m@Qe@[eASq@EMQg@AAAGOWSWUU[SeB_Ai@_@GGSSY_@S_@CI??KWEMIUG[Ga@C[Cc@BeB?AXyEFcABm@?M?AEi@Eu@Ak@Ea@?IIm@??EMWcAU{@GOO_@MYuCyGwBoFy@gC?AKYg@}AWy@YeAeByIiBgKcA{CmAwB[[oAqAe@_@aEwCaAq@??_Aq@cCcB??qEeD}@}@A?m@w@g@y@a@w@c@mAOa@q@}BWaAY_BIiAAm@?i@FgB??BgBCy@C[??EY??a@oBW}@??m@{A_AkC[{@O[Uc@_@s@S[UWc@i@c@e@i@e@SQm@a@_@U]O_@Ma@Mg@M_@I[Eg@Ek@Ei@AaCHiCH@T",
5
    "original_shape_type": "polyline"
6
}'

Sample API Response

1
{
2
    "status": "Ok",
3
    "geometry": [
4
        "u`kbGjekhPa@R\\fBj@lB~CoA~As@PIVINCPCMaAKgAIc@Ha@FSDKHEHCHEPGl@QB?XA^?BAB?B?@?J@B?J@p@FdAJ^BPBN@n@Jr@HZD@S@YFaA@Q@OHwBBiAI[NaDFqAJsABk@Bu@Ba@Be@?a@?i@?mEA_A?eAAeFGuIAq@CqFIwJEcIMwD?a@?sD?}A?}ACmIA}AAqCC_D?i@Ae@?[?U@]@[@WBYB_@Da@BQDSFIHg@XuABGJg@NMHEBADAD?D@FD@BDFFJHRU`@eApBu@vAOVa@e@g@i@KOc@c@MSAEGKEQQk@U{@U{@_@sAkA{DAGeAcEAGO_@KSKMKOs@i@a@_@QOGISWaAaBQ[KO]m@Qe@[eASq@EMSi@AGOWSWUU[SeB_Ai@_@GGSSY_@S_@CIKWEMIUG[Ga@C[Cc@BgBXyEFcABm@?OEi@Eu@Ak@Ea@?IIm@EMWcAU{@GOO_@MYuCyGwBoFy@iCKYg@}AWy@YeAeByIiBgKcA{CmAwB[[oAqAe@_@aEwCaAq@_Aq@cCcBqEeD_A}@m@w@g@y@a@w@c@mAOa@q@}BWaAY_BIiAAm@?i@FgBBgBCy@C[EYa@oBW}@m@{A_AkC[{@O[Uc@_@s@S[UWc@i@c@e@i@e@SQm@a@_@U]O_@Ma@Mg@M_@I[Eg@Ek@Ei@AaCHiCH@T"
5
    ],
6
    "mileage": [
7
        {
8
            "summary": {
9
                "state": {
10
                    "United States|Illinois": 4851,
11
                    "United States|Iowa": 1476,
12
                    "United States|Wisconsin": 721
13
                },
14
                "country": {
15
                    "United States": 7048
16
                }
17
            },
18
            "segment": {
19
                "state": [
20
                    {
21
                        "offset": 0,
22
                        "length": 60,
23
                        "distance": 1476,
24
                        "value": "United States|Iowa"
25
                    },
26
                    {
27
                        "offset": 60,
28
                        "length": 153,
29
                        "distance": 4851,
30
                        "value": "United States|Illinois"
31
                    },
32
                    {
33
                        "offset": 212,
34
                        "length": 26,
35
                        "distance": 721,
36
                        "value": "United States|Wisconsin"
37
                    }
38
                ],
39
                "country": [
40
                    {
41
                        "offset": 0,
42
                        "length": 239,
43
                        "distance": 7048,
44
                        "value": "United States"
45
                    }
46
                ]
47
            }
48
        }
49
    ],
50
    "road_summary": [
51
        {
52
            "summary": {
53
                "has_toll": false,
54
                "has_bridge": true,
55
                "has_tunnel": false,
56
                "has_roundabout": false,
57
                "duration": 596.614,
58
                "distance": 7048.941,
59
                "road_class": {
60
                    "residential": 9,
61
                    "secondary": 4387,
62
                    "tertiary": 97,
63
                    "trunk": 2143,
64
                    "unclassified": 412
65
                }
66
            },
67
            "segment": {
68
                "road_class": [
69
                    {
70
                        "offset": 0,
71
                        "length": 1,
72
                        "distance": 20,
73
                        "value": "unclassified"
74
                    },
75
                    {
76
                        "offset": 1,
77
                        "length": 2,
78
                        "distance": 97,
79
                        "value": "tertiary"
80
                    },
81
                    {
82
                        "offset": 2,
83
                        "length": 20,
84
                        "distance": 392,
85
                        "value": "unclassified"
86
                    },
87
                    {
88
                        "offset": 21,
89
                        "length": 67,
90
                        "distance": 2143,
91
                        "value": "trunk"
92
                    },
93
                    {
94
                        "offset": 85,
95
                        "length": 148,
96
                        "distance": 4387,
97
                        "value": "secondary"
98
                    },
99
                    {
100
                        "offset": 223,
101
                        "length": 1,
102
                        "distance": 9,
103
                        "value": "residential"
104
                    }
105
                ],
106
                "max_speed": [
107
                    {
108
                        "offset": 0,
109
                        "length": 3,
110
                        "distance": 117,
111
                        "value": 40
112
                    },
113
                    {
114
                        "offset": 3,
115
                        "length": 1,
116
                        "distance": 95,
117
                        "value": 0
118
                    },
119
                    {
120
                        "offset": 3,
121
                        "length": 11,
122
                        "distance": 207,
123
                        "value": 40
124
                    },
125
                    {
126
                        "offset": 13,
127
                        "length": 55,
128
                        "distance": 1843,
129
                        "value": 56
130
                    },
131
                    {
132
                        "offset": 65,
133
                        "length": 35,
134
                        "distance": 589,
135
                        "value": 48
136
                    },
137
                    {
138
                        "offset": 98,
139
                        "length": 24,
140
                        "distance": 532,
141
                        "value": 56
142
                    },
143
                    {
144
                        "offset": 121,
145
                        "length": 8,
146
                        "distance": 195,
147
                        "value": 48
148
                    },
149
                    {
150
                        "offset": 126,
151
                        "length": 27,
152
                        "distance": 528,
153
                        "value": 64
154
                    },
155
                    {
156
                        "offset": 151,
157
                        "length": 15,
158
                        "distance": 521,
159
                        "value": 72
160
                    },
161
                    {
162
                        "offset": 165,
163
                        "length": 46,
164
                        "distance": 2030,
165
                        "value": 80
166
                    },
167
                    {
168
                        "offset": 210,
169
                        "length": 13,
170
                        "distance": 382,
171
                        "value": 89
172
                    },
173
                    {
174
                        "offset": 210,
175
                        "length": 1,
176
                        "distance": 9,
177
                        "value": 0
178
                    }
179
                ]
180
            }
181
        }
182
    ]
183
}

API Query Limits

Route geometries generated from sources other than NextBillion.ai services, are not supported in this version.
Using geometries generated from “Fast” NextBillion.ai services might lead to discrepancies in distance and duration results in Route Report’s output. It is recommended to source route geometries from “Flexible” Nextbillion.ai services.
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 an 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.
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 [email protected] if the issue still persists.
422	Could not process the request.	Valid route could not be generated for the given 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.