• Optimization
  • Navigation
  • Tracking
  • Maps
  • Places

Route Report API


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.



Request Parameters


Request Body


Response Schema


Sample Query

Let’s request a report and other stats for a trip in Indiana state by providing a sample route geometry.


1curl --location 'https://api.nextbillion.io/route_report?key=<your_api_key>&option=flexible' \
2--header 'Content-Type: application/json' \
3--data-raw '{
5 "original_shape": "_ujrFjvkeOiBhCKNUX??c@n@yBxCgE|F??_ErFg@t@??[b@U\\SXK@aBvB_@f@wBvCyApBC@k@n@A@g@f@UTEP??]XA?@b@?p@?X??A\\E`@E`@c@jCYfCM`A??gDdV??mBrNWtB]dDKhAM`BM|AIpAElAG~AElBClB?BClE?@@nCBbO@zSDzS@tE?^?h@?rB@tB@`D???l@@|QBpQ??Jj`@@hQ??D|I@xI???X?bK?pACrC?TEjAGbBEv@KtB?@Ep@GfAk@xG?@CRMjAQrAQfAQfAWtAAFYzA??YvA[xAc@~Am@lCi@xBw@jD_B|G_CxJcAjEu@dD]pA_AzDg@rBi@lBUz@Mh@y@pC?@uGdSM\\GPOf@Qp@??Mb@w@fDIb@i@dCa@xBu@jE}DxTeCfN?@cApF[zB[rB]tCObBGh@K~AW`EAj@GxG??A~@AnA?@GhI?fC?@?^?pD?nE?`@?zB?^?f@?xG?rB@`@?n@?bC?h@AN??GnACb@??MpBMzB??Q|B??Ir@In@ERCV?@EP{@jF?@{AnJ??Kj@yBlNu@nEsAhHoC`N}@hE??g@|BmArFq@zCy@xD[vA]`BOz@Y`BQvAKv@Gt@Gb@Ev@G`@KjBIvAY~HYxIQtE??KfCc@fL?@e@`M?@Ct@Cj@??AJ?@Q`FOtFSrIS~Ow@be@GtBCb@??Ev@GbAUhDk@~F??Q~A]rBk@dD_FvWs@`Eu@jE?@G^Kv@_@|Cc@rEMpBMvCEtBCbCCzD@`H?@?`CGvL??~I@~@B~@?pB?lBAtG@??`FFrHCtGDnDBzB?fD@rB@??|B@??xABlFBlA@??zI?xFDxFDrNBtNDP?@?dF@|BBJ?J?J?xAB|B@pC@|ABtAAtBAfCKxAG|ACvBKnBKbAEvAIzFQnBElAGhCOxBGzCIpBKjCIvGWp@C",
6 "original_shape_type": "polyline5"


2 "status": "Ok",
3 "geometry": [
4 "_ujrFjvkeOiBhCKNUXc@n@yBxCgE|F_ErFg@t@[b@U\\SXK@aBvB_@f@wBvCyApBC@k@n@A@g@f@UTEP_@X@b@?p@?XA\\E`@E`@c@jCYfCM`AgDdVmBrNWtB]dDKhAM`BM|AIpAElAG~AElBClB?BCnE@nCBbO@zSDzS@tE?^?h@?rB@tB@`D?l@@|QBpQJj`@@hQD|I@xI?X?bK?pACrC?TEjAGbBEv@KvBEp@GfAk@zGCRMjAQrAQfAQfAWtAAFYzAYvA[xAc@~Am@lCi@xBw@jD_B|G_CxJcAjEu@dD]pA_AzDg@rBi@lBUz@Mh@y@rCuGdSM\\GPOf@Qp@Mb@w@fDIb@i@dCa@xBu@jE}DxTeChNcApF[zB[rB]tCObBGh@K~AW`EAj@GxGA~@ApAGhI?hC?^?pD?nE?`@?zB?^?f@?xG?rB@`@?n@?bC?h@ANGnACb@MpBMzBQ|BIr@In@ERCXEP{@lF{AnJKj@yBlNu@nEsAhHoC`N}@hEg@|BmArFq@zCy@xD[vA]`BOz@Y`BQvAKv@Gt@Gb@Ev@G`@KjBIvAY~HYxIQtEKfCc@hLe@bMCt@Cj@ALQ`FOtFSrIS~Ow@be@GtBCb@Ev@GbAUhDk@~FQ~A]rBk@dD_FvWs@`Eu@lEG^Kv@_@|Cc@rEMpBMvCEtBCbCCzD@bH?`CGvL~I@~@B~@?pB?lBAtG@`FFrHCtGDnDBzB?fD@rB@|B@xABlFBlA@zI?xFDxFDrNBtNDR?dF@|BBJ?J?J?xAB|B@pC@|ABtAAtBAfCKxAG|ACvBKnBKbAEvAIzFQnBElAGhCOxBGzCIpBKjCIvGWp@C"
5 ],
6 "mileage": [
7 {
8 "summary": {
9 "state": {
10 "United States|Indiana": 20042
11 },
12 "country": {
13 "United States": 20042
14 }
15 },
16 "segment": {
17 "state": [
18 {

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 CodeDescriptionAdditional Notes
200Normal success case.
Normal success case.
400Input validation failed.
There is a missing or an 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.
Valid route could not be generated for the given 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.