Route Reconstruction API

Introduction

With NextBillion.ai’s Route Reconstruction API, you can recreate the actual route taken during a completed trip by providing the waypoints or locations tracked during the trip, as input. Total distance covered during the trip and the geometry of the route taken is returned in the response. Users also have the option to indicate if a trip was a round trip or not.

Let’s take a look at the parameters available for this API.

POST

https://api.nextbillion.io/route-reconstruction?key={your_api_key}

Request Parameters

POST Body Schema

Response Schema

Example-1

We will reconstruct the route taken during a completed trip with a set of 4 locations that we were able to track.

Sample Request

1
curl --location 'https://api.nextbillion.io/route-reconstruction?mode=car&key=<your_api_key>'
2
--header 'Content-Type: application/json' 
3
--data '{
4
    "waypoints":"34.04932289,-118.25573833|34.04711381,-118.24976846|34.04153727,-118.2310818|34.03881998,-118.20756901"
5
}'

Sample Response

1
{
2
  "status": "Ok",
3
  "route": {
4
    "geometry": "{dynEnuwpUf@`@hAoB`AiBLSt@uAR]d@{@JSdAiB^o@f@y@`@w@`@s@Zk@h@aA\\m@f@}@NWFMf@{@o@q@_@a@USkAiAUUYWa@p@j@b@NL\\XDFBD?FAHEHCBG?GC}@{@SU??EG@GLS`@q@u@u@cB_BoAmAi@c@aAw@JOHKx@eAZ_@Z_@NOT[FIFKFKBGDGJWJSz@yBFMXo@JUJ[Ni@Ha@l@eCJg@Vw@Xk@~@kB|AqC|A{C`BwCb@}@P_@DMFOj@}CD_@F[@O@O@S?SAGCe@C]KeBAIAKCc@Ck@OcCAKCk@?Q@Y?I@OBQ@KJ_@Te@h@aAd@_A~@oBnBuDv@aBHQHSDKBMDMBQDSDS@Q@W@[?ECyGAoAAsA?K?M?O?CAqA?KAsAAe@CQCSGe@GUCQgAiFSeAi@mCY}Aa@mBYwACMCGG[AKAMAYCcBCcBCq@A]Ag@?]Aq@?s@AM?OASAeAAs@Ck@A{@E{BA_A?YAK?G?o@@S?MDW@GFW@EBI@EBIFSHWPe@La@\\aA~@kCLa@L]Nc@JYr@wBv@{B^iATo@To@La@BGL_@Pc@Lc@X{@To@DKXw@FQHWZ_AXy@zAiE\\eAfAaD",
5
    "distance": 5277.3
6
  }
7
}

Following is a visual representation of the above response:

Example-2

In this example, we will generate a route for the same trip we used above, with following changes:

We will request the route to be generated for a round trip
We request the geometry of the route in polyline6 format.

Sample Request

1
curl --location 'https://api.nextbillion.io/route-reconstruction?mode=car&key=<your_api_key>'
2
--header 'Content-Type: application/json' \
3
--data '{
4
    "waypoints":"34.04932289,-118.25573833|34.04711381,-118.24976846|34.04153727,-118.2310818|34.03881998,-118.20756901",
5
    "round_trip": true,
6
    "geometry": "polyline6"
7
}'

Sample Response

1
{
2
  "status": "Ok",
3
  "route": {
4
    "geometry": "wyd}_A~_vp`FnKrIbV_b@rSc`@jCgEzO{YfEkHzJwQvBgEzTc`@~H_NnKcQrIoPrIgOvGwLbLsSjHkMnKkR~CoFnAkCnKwQ_NsN_IsI{EgEwVcV{E{EcGoFsIrNvLfJ~CjCjHbGz@nAf@z@?nASbB{@bBg@f@oA?oAg@kRwQgE{E??{@oARoAjCgErIsN{O{Og^_]_XkWcLgJsSoPvB_DbBwBbQ{TvG_IvG_I~C_DzEwGnAcBnAwBnAwBf@oAz@oAvBoFvBgEvQce@nAkCbG_NvB{EvBwG~CcLbBsIjM{h@vBoKnFoPbGwL~Rw`@j\\sl@j\\wo@r]on@fJkRrD_Iz@kCnA_DvLkp@z@_InAwGR_DR_DRgE?gESoAg@{Jg@kHwB{^ScBSwBg@gJg@wL_Dgh@SwBg@wL?sDRcG?cBR_Df@sDRwBvB_IzE{JbLsSzJ_S~R_b@~a@{w@nPs]bBsDbBgEz@wBf@kCz@kCf@sDz@gEz@gERsDRoFRwG?{@g@cwAS_XSgY?wB?kC?_D?g@SsX?wBSgYS{Jg@sDg@gEoA{JoA{Eg@sDoUchAgE{TcLkk@cGk\\sIka@cGoZg@kCg@oAoAwGSwBSkCScGg@g^g@g^g@sNSkHSoK?kHSsN?gOSkC?_DSgES{TSgOg@wLSwQ{@we@S_S?cGSwB?oA?_NRgE?kCz@oFRoAnAoFR{@f@cBR{@f@cBnAgEbBoFrD{JjCsIjHsS~Rwj@jCsIjCkH~CgJvBcGfOod@nPwe@~HcVzE_NzE_NjCsIf@oAjC_IrDgJjCgJbGwQzE_Nz@wBbGoPnAsDbBoFvG_SbGcQv[c~@jH{TnUsq@????oUrq@kHzTsXoPkWsNgm@_]oi@k\\kRoK_b@oUc`@bmAcBfEgJbV_DfJ{@jCwBvGsIbVkMz^oAzEcBzEcBfEoAzEgEvLoAfEwBnFoA~C{@rD{@~CSbB?vB?RSnA?bB?vBRjCf@bVRrNR~CSjC?vB{@rDoAbG{JzYsNv`@cGjRsDnKkC~H_N~a@oF~MwBbGwBbGcBzEwV~u@{JrX{@jCkCjHcBrDgEjMcBrD{@jCwGrSsDbLcGnPsDnKg@nAg@jCSbBSf@{@fJSrI?fESvGg@rSSvGSfEoA~Cg@nKg@~HSjC?~CSnFoAnUSvBkCf@cBf@{EbBoFbB{EvBkk@nZgJfEgEjC_DzEc`@zOoFvBsDbB_DnAsDnAwBz@gObG_DbBgEvBcGjCoFvBkHjC_IrDcBf@kCnAkHjC_DbB_DbBkCnAg@RcBnAgE~C{ErD_DjCsDrD_DfEwBjCcG~HcGbLsDfJSf@kCvGwBnF{@vBSz@g@vBSz@Sz@g@jCSnAS~CSvBgEz^SjWg@rSg@vLcB~Rg@bG{@~Hg@rD{@zJoAbLoAzJ{@vGSjC{@nK{@fJg@zESbBSvBwBzYg@vG{@~MwBrX{@jMcBjR_DnZ{@jMcBfOSjCoA~Mg@vGg@vGg@jHg@bLg@rIoAnUoAfYoAbQcBzYcBbV?z@{@b[SzE?bBRrD?jHR~Hf@jMf@nKz@jM?fJSjHg@vGSfEg@nFg@nFoFzYoAnFSz@oAfEoAfEgEvLoAfEcBnFcBrDg@z@_D~HwBrDkCzEwGbLcGbL{ErIwBzEcBjCkCzE_DbGsDbGcBjCkCzEsIbQg@z@wQr]_IrNgE~HoA~CkCfEoAvBcVfc@g@z@{EzJg@z@gE~H{@bBg@nAoAvBwBfEoFzJ{EfJkH~MkMfTsIfOkHbL_IvLkCrDsN~RkMvLsIbL_D~C{JzJ{@bB{@z@_DrDoPrNgOjMcVvQsDfEwV~R{J~HwGnF{JbGkMrIwBvB_SfTgOfOgErDwBjCoAnAsDbGcBnF{@jCoAfEcBbGSf@?z@?nA?bB?f@RnARjC?fEf@vBRrDz@jCbBbGvBzEvB~CbBbBfJrIfE~CjRrNbBnArNzOr]z^jMjMf@f@v[vVjWf^fOjRrIbLjC~CjMfOfTvVbBbBbBbB~HjMfOzTnFvGRf@zOrSzEvGrDzEvB~Cz@z@z@nAjCjCfJjMjMfOfJ~Rz@nArNbQfJfOf@nAz@nAjHfJ~C~CfErDrInFvGrDnFvB~Cf@rDf@fESrD?jCg@nAg@fEoAzEkCvB{@z@SvB{@fEcBjC{@vBSnA{@~CkCbBoA~CkCnFoFzEcGfEkHrD_IfE_IbB_DzJ{OvGwLzTkW~C{Er]kk@fOsXvLjR~M~MnAz@z@z@f@Rz@Rf@Rz@SbBg@zE_InUka@zJcQzJ~HrD~CrI~HbLzJ~MvLv[b[jHjHbQbQfErDz@z@",
5
    "distance": 12598.2
6
  }
7
}

Following is a visual representation of the above response:

API Query Limits

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.
422	Could not process the request.	Unroutable coordinates provided in the request, please check API response for more details
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.