Documentation Powered by ReDoc

TollGuru Toll API (2020-07-15T09_40_00Z)

Download OpenAPI specification:Download

Equipo de ingeniería de MapUp: eng@TollGuru.com URL: tollguru.com

You can download the TollGuru API spec using the download link above and import collections in Postman for testing. Here is how to import collections in Postman.

Introduction

Use TollGuru Toll API service to

  • calculate tolls for your route
  • calculate other costs for your route (such as fuel expenses)
  • calculate and travel on the cheapest, the fastest and other compromise routes

Why use TollGuru API

With the Toll API you can calculate tolls, fuel costs and optimal routes for:

Pre-trip planning

Post-trip toll cost reconciliation

TollGuru API is designed to show you cheaper routes not shown by other mapping services such as Google maps, Apple maps, Waze, HERE, Mapquest, OpenStreetMap, Scout GPS, Trimble Maps, etc. You will see the cheapest, the fastest and the compromise routes since we return routes optimized for two vectors - time and cost. Other mapping and navigation softwares optimize for time. TollGuru is built for real America where both costs and times factor in route decisions. Still not convinced, let us take an example:

Say you want to dispatch a 5-axle semi from Englewood, NJ to Scarsdale, NY in upstate New York. Open any online map and you will see three routes. Most likely all the routes will use George Washington Bridge (GWB) ($90 one-way toll with E-ZPass NY).

In contrast, TollGuru would show the cheapest route over Tappan Zee/ Cuomo Bridge, the fastest route over GWB and then some other logical routes. If you drive on the cheapest route over Tappan Zee, it will take you about 16 minutes more than driving over GWB. But you can save $69 if you pay with NY E-ZPass. That’s a saving of $69 in an hour-long trip! Pretty sweet savings if you ask us.

Who uses TollGuru API

Here are how some of the companies use TollGuru Toll API

  • Mapping companies: to extend mapping functionality to provide toll information for their routes
  • Smartphone based toll payment solutions: To know toll locations and deduct tolls
  • Rideshare, connected vehicles and carshare companies: calculate optimal routes, driver payments, post-trip reconciliation for customer billing
  • Trucking companies: How much did my truck drive through each of the states during one or multiple trips, I am sending a truck from Dallas to New York. Where should my drivers take rest? What time should I send my driver for pickup?
  • Truckers: What should I bid to cover my expenses and make money? How much should I travel?
  • Shippers: How much should I post as a bid so that truckers would be interested in my bid?
  • Transportation planners: Transportation modeling accounting for tolls and other costs, mode choice analysis. I am a city planner. I need to know the value of time for people.
  • Tax professionals: Estimate fuel and toll reimbursements for tax purposes
  • Others: How much should I reimburse freelancers, movers? I am moving to New York. Where should I buy/rent a home (transportation)?

Get started

Sign up for a free API key using your email and password or Google account. We suggest using Postman to test API before you integrate Toll API into your products. TollGuru Toll API is a REST API with predictable resource-oriented URLs. It uses standard HTTP response codes and authentication to accept form-encoded request bodies and return JSON-encoded response.

Authentication

authorizer

TollGuru uses developer specific API keys to authenticate requests. The authentication to the API is done through HTTP Basic Auth. Your API key serves as the basic auth username value and you do not need to provide a password. The TollGuru API key comes with privileges, thus avoid sharing it in publicly accessible areas such as GitHub or client-side code. You can get a TollGuru Toll API key by

  • Registering for a new TollGuru developer API key at our developer’s portal.
  • For a trial account you can also sign up via your Google account and get access to a daily limit of 50 requests. For a higher daily limit, please reach out to us at api@TollGuru.com, providing details about your company and your plans on how you intend using the API.

Adding the API key to your request

With an API key you get access to place requests on the API. The API key should be included in all API requests to the server in the header. In the following example, replace developer_key with your API key. It should look like
x-api-key- developer_key

Security Scheme Type API Key
Header parameter name: x-api-key

Our Client Libraries

You can use client libraries in Java, Python, Go, Node.js, PHP, Ruby, .NET to quickly integrate Toll API.

Tolls between Origin, destination, waypoints

Use this service to calculate toll and fuel cost for your origin, destination, and waypoints, if any. With this API endpoint, you can

  • Calculate tolls for various vehicle types including cars, pickups, SUV towing trailers, rideshares, taxis, trucks (up to 9-axles), RV, bus, motorcycles, etc.
  • Return tolls for all routes between origin, destination, and waypoints
  • Return fuel costs for all routes between origin, destination, and waypoints
  • Return the cheapest, the fastest and compromise routes between origin, destination, and waypoints
Specifically, for trucks, you can
  • Return tolls by specifying zip codes (zip code followed by country name)
  • Return tolls for truck compliant routes (based on axle count, height, weight, truck length
  • Return Hours-of-service (HOS) compliant routes with information for suggested stop locations
  • Return distance traveled in each state (mileage per state)
To summarise, the endpoint adds toll and fuel cost information to routes provided by Google Map and HERE Map. It extends the mapping functionality of Google Maps and HERE maps by adding tolls and fuel estimates to the route direction information. The endpoint accepts various parameters such as your vehicle type, fuel efficiency, and fuel price. You can specify whether you want information for routes from Google or HERE maps.

Tolls for routes from HERE Map

If you are looking for toll information for routes that consider bridge height restrictions, axle count, weight restrictions, HAZMAT restrictions, we suggest that you use HERE maps (we use HERE maps by default). Specifically, with the HERE maps API service, you can

  • Specify origins, destinations, and waypoints as text strings (e.g. “Dallas, TX”, “Sydney, NSW, Australia”, “Paris, France” or “Jaipur, Rajasthan, India”), as place IDs, or as latitude/longitude coordinates
  • Specify origin, destination, and waypoints as zip codes (followed by country code or name)
  • Specify vehicle type. The route and tolls are returned for the specific vehicle. For example, you can get tolls for vehicles based on axle count (cars, SUV, pick-up, truck, motorcycle, bus, motorhome / RV, limousine.
  • Specify route restrictions such as HAZMAT material and tunnel types for trucks. The route and tolls will be returned for the route with the HAZMAT restriction.
  • Specify weight and height for semi and large commercial trucks. The route and tolls will be returned for the routes where trucks with specific weight and height are allowed. If tolls are based on vehicle weight, tolls will be returned for the weight specified.
  • Specify departure time (optional). You can use future departure time to receive tolls at the time when the vehicle is likely to hit each toll location on the variable toll facilities. If you query for departure time in the past, tolls are returned for the current time.
  • The response will include toll information, cost information and Hours-of-service (HOS) compliant routes with information for suggested stop locations and distance traveled in each state (mileage per state)

Authorizations:
authorizer
Request Body schema: application/json
One of
required
Address (object) or Place-Id (object) or Geo-Cordinates (object)
required
Address (object) or Place-Id (object) or Geo-Cordinates (object)
Array of Address (object) or Place-Id (object) or Geo-Cordinates (object) (Location)

Specify a range of intermediary locations, along your route between your origin and destination points

vehicleType
any
Default: "2AxlesAuto"

For more information of vehicle types read here

Responses

Request samples

Content type
application/json
Example
MinimalRequestBody
MinimalRequestBody
Trucks(withUnitsObject)
OtherVehicleTypes(withUnitsObject)
{
  • "from": {
    },
  • "to": {
    },
  • "waypoints": [
    ],
  • "vehicleType": "2AxlesAuto"
}

Response samples

Content type
application/json
{
  • "status": "OK",
  • "summary": {
    },
  • "routes": [
    ]
}

Tolls for routes using Google Map

If you are looking for toll and fuel information for rideshares, taxis and cars you may want to query using Google maps (we use HERE maps by default). Specifically, with the Google maps API endpoint, you can

  • Specify origins, destinations, and waypoints as text strings (e.g. “Dallas, TX”, “Sydney, NSW, Australia”, “Paris, France” or “Jaipur, Rajasthan, India”), as place IDs, or as latitude/longitude coordinates
  • Specify origin, destination, and waypoints as zip codes (followed by country code or name)
  • Search for tolls on a route using departure time (optional). You can use future departure time to receive tolls at the time when the vehicle is likely to hit each toll location on the variable toll facilities. If you query for departure time in the past, tolls are returned for the current time.


However, you
  • Cannot specify vehicle type. If you do, the route and tolls are still returned for cars.
  • Cannot specify route restrictions such as HAZMAT material and tunnel types.
  • Cannot specify weight and height for semi and large commercial trucks.
  • Since the routes are not truck compliant, response will not include stop information for Hours-of-service (HOS) compliant routes and distance traveled in each state (mileage per state)

Authorizations:
authorizer
Request Body schema: application/json
required
Address (object) or Place-Id (object) or Geo-Cordinates (object)
required
Address (object) or Place-Id (object) or Geo-Cordinates (object)
Array of Address (object) or Place-Id (object) or Geo-Cordinates (object) (Location)

Specify a range of intermediary locations, along your route between your origin and destination points

vehicleType
string
Default: "2AxlesAuto"
Enum: "2AxlesAuto" "3AxlesAuto" "4AxlesAuto" "2AxlesLGV" "2AxlesHGV" "3AxlesTruck" "4AxlesTruck" "5AxlesTruck" "6AxlesTruck" "7AxlesTruck" "2AxlesBus" "3AxlesBus" "4AxlesBus" "2AxlesCaravanVan" "3AxlesCaravanVan" "4AxlesCaravanVan" "2AxlesMoto"

For more information of vehicle types read here

DateTime (string) or Timestamp (number)
fuelPrice
number
Default: 3

Secify as numeric up to two decimal places

fuelPriceCurrency
string
Default: "USD"
Enum: "USD" "CAD" "MXN" "INR" "AUD" "GBP" "NOK" "SEK" "DKK" "PEN" "COP" "ARS" "CLF" "CLP" "SOL"
object

For further accuracy in estimation of fuel expenses, you can specify additional fuel efficiency parameters

object

Specify Driver wage or Value of Time. For example, if you are willing to spend £1.45 to save 15 minutes for a particular trip, your value of time is £1.45* (60/15) = £5.8 per hour.

object
enableDurationInTraffic
boolean

Specifies whether duration in traffic is required

Responses

Request samples

Content type
application/json
{
  • "from": {
    },
  • "to": {
    },
  • "waypoints": [
    ],
  • "vehicleType": "2AxlesHGV",
  • "departure_time": 1609507347,
  • "fuelPrice": 1.343,
  • "fuelPriceCurrency": "SEK",
  • "fuelEfficiency": {
    },
  • "driver": {
    },
  • "hos": {
    },
  • "enableDurationInTraffic": true
}

Response samples

Content type
application/json
{
  • "status": "OK",
  • "summary": {
    },
  • "routes": [
    ]
}

Tolls for Route polyline from any mapping service

Use this service to calculate tolls for routes from any mapping service. Specifically, with the Route Polyline API service you can

  • Specify whether you want to send route polyline (encoded using Google encoded polyline algorithm or shape (latitude and longitude pairs)
  • Specify vehicle type. For example, you can receive tolls for vehicles based on axle counts for cars, SUV, pick-up, trucks (up to 9-axles), motorcycle, bus, motorhome, RV, limousine.
  • Specify truck parameters such as weight, height, axle counts and receive tolls based on weight, height, etc.
  • Specify the source of route polyline such as Google, Bing, MapBox, Apple Map, HERE, TomTom, Waze, ESRI, MapQuest, JawgMaps, Trimble, PTV, MapmyIndia, Yandex, Michelin, Baidu, Gaode or your custom source (“custom”)
  • Since you specify the exact route, you will receive tolls for the route. You will not receive tolls for alternate routes between origin and destination.
For more details, visit TollGuru map independent algorithm and how see we deal with edge cases and common pitfalls

Route polyline

The response endpoint retrieves all tolls on the single route requested. Route polylines are map independent and thus any mapping provider or a custom source could be used.

Request Body schema: application/json
Any of
source
string
Default: "here"
Enum: "google" "bing" "mapbox" "apple map" "here" "tomtom" "waze" "esri" "mapquest" "jawgmaps" "trimble" "ptv" "mapmyindia" "yandex" "michelin" "baidu" "gaode"

Specify route source, either here for HERE maps routes based polyline or gmaps for Google Maps polylines

polyline
required
string

Specify route as Google Maps encoded polyline (see details)

path
string

Specify route as a set of comma-separated lat,lng coordinates delimited by a pipe character (|)

vehicleType
string (vehicleType)
Default: "2AxlesAuto"
Enum: "2AxlesAuto" "3AxlesAuto" "4AxlesAuto" "2AxlesLGV" "2AxlesHGV" "3AxlesTruck" "4AxlesTruck" "5AxlesTruck" "6AxlesTruck" "7AxlesTruck" "2AxlesBus" "3AxlesBus" "4AxlesBus" "2AxlesCaravanVan" "3AxlesCaravanVan" "4AxlesCaravanVan" "2AxlesMoto"

For more information of vehicle types read here

DateTime (string) or Timestamp (number)

Responses

Request samples

Content type
application/json
{
  • "source": "here",
  • "polyline": "qhhaIlm}KDEd@gAbAmCb@eAR_@z@}@Eq@VnLx@dETR?TDtANtHf@jD`@fALIh@ENw@|@OHQBkACQBOFSBKBUSEK?MHSHo@DiBBQAkAFqA`AyOJsA^_AfAaNR[VOX?nJbDhAP`Gl@fFVrJt@vAZxD`@xDPzGu@|IgArCW\\\\Al@@h@Lh@TvHdE\\\\NTDPFTFXBpAH|@A`B@tLPlVThBChA@|DLzFBd@BlDBvADhG@hZXtMFjSPvFJtFBpOJvFHpAFFu@L_ARqCb@sCVcDf@sDLyARuAPsBPiA\\\\wDToBh@qGlAmKHuARqALaBNuAVkANuAL{@zAsMfAwKViINwSTcIPuCNo@vEkFJ[RWt@kB\\\\i@TQPG`IkCpBy@r@a@b@c@f@s@Tk@XwAbCyKdAqFVcBDm@HwCViSLePBiJCe@[aBc@}@[c@e@c@iDsCqGcFs@e@s@m@_Aq@qC_Ca@g@]m@Sg@W}@G_@Co@?m@Do@d@iCtB}CvDeGxAwCzAcDf@oA|BkEf@}Af@kAbFcKnFuLx@uCJQjC{Fb@mAh@eCAQvAqWZaH\\\\sFp@kJX}En@_PVYDs@d@sILqDToDD}A`@uGhDcZPqAp@kGFcAB_AAiCQmCMeAMi@J}Dr@qLTwE^}Ev@{QHgATyEVsEPy@`@cAr@yA|BsDp@oApD}ItBuEbB}DJWzD}IPi@hA}B^}@r@sBrF_Ml@yA~D{IH]oCaJcA{CQm@gByFw@mCy@aCmB}GcBkFyBoH[oAs@aCOs@uAsECYe@}AqEiPmC{HGg@EaAHq@BOZq@^c@NK~@qAHWLy@A}@Kw@yBsCUq@?cABa@fCkNb@uBjBcKvAyGJKvBoL~@kGbA_KV}BDi@X}Cb@oCXiAxAuC`@cAvDsH`AcCjBcF~AgDRe@|@kA`@w@`A_D`AoDRk@p@sD^{A~CcGd@iAtAgEx@mBfCwEfH_JpEcFtDyDvB_BxDiDlCoC~HyFh@m@~@oAdAyA`BqCp@y@dIcGnBsApKuFpDuBvEaDX]zNyKMOk@`@`BoMkAYj@_EoCa@`@mCoE{@Zs@b@oA`@kB^sAb@qBf@Yd@OlDoBmDnBh@zC\\\\nASvApA^iAhEvAR|Bf@|@HtJfBm@j@qB`BkChC{@lAgApA_A`AmE~CkDzBuG`F[Pk@f@yCrBmAt@gH~DaJlFoFzDsAfA}BrCYf@}@pAyA`CUVo@h@cCzAoCvBgHpGuF|EoAzAqEbFuHhJ_E~H{ApE_@`A}CtFgBlI{AhFc@p@_@R_@AY]YcAuJor@O{A]sBI[QyAWgDc@aROgAq@_C_BiCiAkAmGmFuGkFeB}AgDsC{CeCeJyH_BoAsQqIaFyB{J{Egi@qV{DkBa^oPkPuHup@e[wEuB{FmCqQmImAu@o@]cNmGgAk@cCgAgEwB_EkCSQaAu@qDgC{VcR_SiO_LgIwGcF{EcD{GcFsImGmEyCgBgAeEaBeC{@kB}@}@k@eHiFaEqCo@a@gB{@uB{@{C}@{B]aAMyEu@wCi@yKsC}C_AyIcDoFwAyKaDgGgCeKyCa[{HaD}@mKkDWM{GyBcFqAsAYsK}CyC_AeFmAsK_DiAYwDa@wAWiN{DeQmFmDaAeLiDo@OuC_AeHqB}FmBq@Y}@s@}AuBi@c@s@g@u@]q@UaBUsACo@BkAR}At@ePxLePvM{O~Lq@n@cChAeB^gD@_IeAgBOgBMaIcAoDo@}Y}GwXaEkOmBeD[u@c@[Ec@B_@F[NU^I~@GfDIn@g@`CEt@Br@`@dDFz@AfAkAnWIdCAvBL`AdB`H~FxTn@fCtBvKv@lC`BrGl@nBpBhHFXvElQfIx[fd@deBxLpe@n@pBvGvW|k@nzBvCjLdPzm@b\\\\~nA`ExOdGhUrQtr@PtBDfAEhAMbA_@tAe@fAu@~@u@p@}@h@kAd@cOzEgQrFyLzDgCl@cCd@uEj@sQlAsB\\\\cKjCiARkAD}@?wAEmAMc@GQGyGwAqAW_BUeAIkDKqIAsRIuq@_@}^OqMIaaCiAwuAeAe\\\\S_o@LuCEeC?yLQgJGc@@{ALaCb@gA`@SJiAl@mAx@{FlEkIhGyFlEoAx@aBt@w@VaIdB}A`@cA\\\\}Av@mAt@}CbC{AxAiBvA}AvAoCpCqJhKaBrAs@d@[LoCbAuNvEgBr@iB|@aHfCmwA|g@mJvDaNpGWJ}Ap@iBr@uAXaAL}AHgC?gABwBPqB^qAd@iPhHgFvBmFdB{Bx@sHnCsDzAq@XsA~@aC~B}@x@qAdAuA|@qKhFmBv@sBt@uGlBcEvAs}JrxDyWbKwClAuCbA{BnA}GtCy@T}Bj@gA\\\\iHlCkDzAcB|@m@^uBhBuExEkAbAoBtA_Bx@eAd@g@RcBd@qAXgBXyCVuDRkCXaBXwA`@uAb@gDnAq^hNiK|D_UtIiqAzf@eb@bPcf@|Q{CpAy@b@}A`AwBfBy@z@qA~Am@~@cAlBw@jB_@hA]nAWnA[zBKhAMzBCpAG|^Ena@ChGKnCQpB]pBYpA_@pA_@dAw@hB_@r@wC|E{BlDkAnBscAt`ByBrDgApBmAbCYh@aAlBcAbBu@`A{@~@w@r@{BhBcUpPu\\\\bWsPnMqI~GmR|MkCtBoLnKiCtBmAz@wA|@{Az@kSdKyDxBwBxAy@l@kC~B_C`CeApAgd@nl@eo@fz@oBzBsHfIiHrIuE|Fy@`Ay[xa@wGbJ{@`Ba@nA[rAs@pEgCjQw@fEYjAg@`B{CbJc@|A]vAuCrQkCpQ_@xCYbDOtCGhC?zEBlARlEl@lKFjB?fDOdE}AjUGlB?`CBp@Z|CVzAf@bB\\\\`AtAjCpAjBlA|A`AtAvAbC`@x@R\\\\dCvE`CdE~@zBTr@RlADr@@z@E~@MbA_@nA]r@w@hAiDxCQ^oSpPs@p@wAfB}@rAe@~@]x@uDbLkBfGik@tkBk@bBq@bBWp@}@~AwApB{@dAsApAoZhWqE|DsBbBmWnTwe@ra@qBzBeLjN_BtBkAfB_AtBk@hBgCtLmMbn@o@jCk@nBgHlSe@dBa@pBe@nCo@lFqCpTgCrRu@fFc@tB_C|IwS~v@cBhFs@xAw@pA{@fAuAxAoCdC_v@|s@cErDuBbB{At@{Ah@aBZ}@HYD}BLuLj@iBLwBZ}Cp@kLnDyDlAs@ZqLnFwE`CgY`NcClAaBl@sA^gANqAHkCEaAOeB]iDi@gBQaBEuABwBXcAVoAd@sAp@w@h@wAlAgBnB]ViCvCiHtHyAbBkA~Aw@vAy@lBcHzQsA|CuAvCkAvBiU~b@_ArAeCnCez@tv@qAxAiAdB}@lB_AvCaAhC_A`B{@fAeA|@yAx@oBr@}GhBiBr@cB|@q\\\\dUmFjDyD|BeEvBeIvDoBhAaBxA{AlB}@lBm@jBc@fCeAdH_@zAc@jAqCpGsFpLsLbXaRla@}@|Bs@zB}@`Dc@rAy@jBw@vAqEjFuAbB_ApAq@pAm@vAo@|Ba@rBaDzTc@bBg@rAk@~@y@bAeA`AsB~AyBlB_HlFyBlBqAtAu@`A}EpJw@dA}BfBeE`BuAZaAZ_Bj@uAp@s@h@w@t@w@fAuB`FcAnCoAlCeHvMeAjB}@bAy@l@[TsAt@c@RkAZ{ATkCPsGPoCJsEZm@L[?yBp@kDpA{@b@cEtAsChAuBjAqC`Cs@x@sBdDu@rBYtAkCjO}C|PqKnn@sVhwAqGh_@SdAgO`|@_@r@GRqEdUa@hB[fA}@~B{DfIw@Z]H[@MAWI_@YOUKY[oBKmAAg@Jq@Vc@RQTKf@Ix@H\\\\JZNhDxDnAnAvD~C|BfBnBpAhCxAhCtAnE~B~F`DdNhHVLxBpAhCxBnArA`AnAb@p@lAzBf@jAXx@v@nCPx@jGl]n@~CfAvEn@~BzAtE`\\\\|~@\\\\dAz@nD`@~BR|BLhD@bCC`B{@tSIzBCbBDxALlBtB~NVnAV`Aj@rAp@hA~@jAn@r@vAdAvAp@dA`@nMvDnBv@rBfAx@f@zAdA`BnAvHvFbc@z[rBfBnBtBvAhBvAvBv@tAxIjQf@~@x@jBt@rB\\\\hAZjAh@dCVvBVtDDtBLb_@BjBRpFXpEd@tE`EpYVrB`@xERfDL~CDdE?lEMjL?zAQpICxCWlNmAn{@?|AB|ALjCZ`D`@zB\\\\zAv@hC~@|Bl@pAhAfBp@~@`LzN~@vAv@tAdA`CTj@j@bBn@tCf@rCN`BLbBBfB?vBCfBuCpl@I~H?fCBdCJ|DZzGvGphA`B~WZpI\\\\hNf@bVDhEFfN?rGGvGYlRSnJaBtg@OpCIf@]nBQp@i@|Aq@rAyAtB_AdAa@\\\\kBhBoB|Bm@bAk@hAq@hBa@|A[fBQ~AEr@E`BFjCPfCd@pFHvB?n@EzAWfCu@tDed@bpBwAtGId@_@fDQhCEpB?~AFlCPhCZdCf@jCn@`Cl@dBjMt\\\\rBbEbBrCjCrD`C`DhIfLbFxGtIpLnt@tbAt@lAr@rAp@tBd@zBV`DDvAErBKtAq@nGcE~^qAvLGz@OhF?jBDfCNlCZhDTdB`@tBhFpWv@pEN~@^nCb@jEb@`IB~BIj^K`[C~FKtIwEldBAzDBdCPdEv@|IzD``@T`BVvAx@|Cv@tBn@lAp@jAbBzBhx@`|@n@t@bAvAj@~@f@`A`@~@p@pB\\\\pAd@~BPrAJrAlD`p@VhHB|A?dBA`REfM[`P@dDPfD^dEXbC\\\\pB`@pBT|@~@zCbArCj@rAnBdEr@fBZdA^rBX`D@f@ApAg@vLIpAWtBKd@o@xBiDvHu@vBe@pBUxAI|@KlC?v@JdC`@xCx@vD^vAx@|B^x@R\\\\xAjB`BtA|A`An@Z~Aj@lBh@~Cp@vLpCzc@lKbK|BfDh@vANhDRxABrA?hCGpCQn@GdXeDhCWxD[tDQlCEfE?`BBzDP~E`@jBRnCb@bq@zKxAZjBj@tAh@pAj@bAh@tBtAlA`Ab@`@tAtAr@x@hAbBt@nAtHzNx@tA\\\\h@`BzB`AhA`A`A`DnCjBnAjMbHtBpA^XxCfC~AdBz@bAz@hA`QjXnBxCzAjBr@v@x@x@~AtAbBnAjAt@nCvAzBbAf]jN`CfAlBbAlBjAbEzCdErD~VbVbDvCn@b@rAn@lA^x@PhBRr@@v@ArAOtAWlAa@jAk@j@c@j@e@l@o@V]z@}A\\\\{@`@yApFuXz@qDv@iC`AiCrAcDdI{Pp@mAhA_BtAsArA_A|@c@lCy@l@B`BA\\\\@|@Hz@NnAXlAd@t@d@TRtAzA`B`BxBxAtB`A`F~A|@`@lBjAhBrAl@`@|B~CpFvIt@pA|AtDZx@\\\\hA^fB^|BP|AJ|ADlBAtFiAxs@UvG]hFUpCo@pFyM|nA[xCc@fFoClc@WbGMrDWnOGtEWrOKlC[zEWdCu@fF}@|DcDfN{B~JqA~GcAvGwDzYUzA}LpdA{B|QmAxIeBdJsLnl@iN|q@yDpRiAlFi@lCy@lDqCfKu\\\\jhAcC`IiAzDqKd^YlAY`B]fDEn@EnA@lBHvCj@vKDpABbCCrAEhAWfCa@dCwEfV_@vB]~Ba@fDc@zE]`FWdGK~F?|@HfED~@RbC\\\\hCjMpw@d@bEPnCHtDAvCIxGMrHInDGxKH|ELtDv@xOJhDRlD^zD`@lDxEt^LfBD`BBpBCrDKvCm@xF}Dv[eAvHqAlI}@~EeCjM[jB]~CaB~Y]bD[tBYbB_AhEiDjNiEnQa@rBSzAIdAC`@B|Bb@lEfAjINpB@h@AhAMvBE^OfAK\\\\[bA{@vB{CvGuPp_@yElLmDpLqAfEyEjPmFtQiNdf@gAhDi@tAw@pAm@x@}EvFeEfF_ApA]l@Yp@e@z@mBhGq@jCm@dBcAzD}CpHuAnCsDzGeArBi@pA]rAIh@I|ASdPe@fVMvFU|NkA`j@q@rh@CdEDtDnBve@R~CZlCd@pCf@fCxIp]f@vBBb@lDnM~DpO^bBJlAFrADvA]l]YnLAlLKvLYhREpLO~PGnIUzVSfB[`Bg@|Au@xA_AnAwDjD{BxB[b@u@pAm@vAe@bBWfBGlBDpBDz@PjBfOhlBx@dJNrBMpBKv@Ov@k@fB]p@eAvA_CnBqArAm@|@_@h@Sj@c@fBQpBUdE}Brh@yCfo@YpDWpB_AxEg@dBiRzm@w@xCy@jEY~CKjD@rBNhF^|Df@fCj@dBr@~AfNrWnAbCv@rBTt@b@lBVpBLrBDrBdCjyAVxHBtBEpBMv@a@hB{BbJ}Jb`@cJtZs@bD]lBe@jDe@lF_Bh^YbFUtBsC`OWlBSbFGbRAlMFvJG~TIvAm@jHqBlSaFha@_BhK{@rGkQ~wAeBvM_Gvf@oSdbB{Fjd@}@rGUtC[nC}@~FsD~OaBhGq@vCq@dDk@jD{DpXi@lF[rFA~BDzHCtC@~AArCKnCe@bDc@jBm@hBiEdLk@jBa@nBYjCGrAWxNKnHC`FCt@QjBQp@k@zAYj@eAnAyBhBsFzDiIdGsBdBo@fAi@lA_@vAStAKjCJlCxAnQvDjc@n@bIhB~RdAbMd@~E`@fFRrE?fAKtDYvCCt@UzD]vDo@fKuGzw@gB~TMvCQjHL|JtAff@FlCRzDZzCz@vEfAtE`F|RtFbU\\\\jBXjBRlB\\\\~E@tBAvBo@dQ_AxXGpF?vBBtBFtB\\\\`HxD|b@~@|KRzCH~CCjBKdB_@|C[dB{@vC}HbUc@fBo@zCc@`DQlBU~Es@lXUdKAnB@nBHrCFhAl@|E\\\\lBxJ~f@pBlKZnBRnBJ|GInBQlBe@~C{AvFmHzWo@`EWjBKzCAjBBt@JlBHt@TjB\\\\hB`WzcAd@`B|@nCzCtG~@`BnCdEtBvChN|Q~BhDbBxCxAdDxAtEj@lCdAbIvFpe@rEx`@pDhZ~CbWnKhy@`@~DZlFBzB?tBsCx~@YzHU|Dg@fGyBdSi@tDqEl_@wAnKy@xH]rEEvAGlD@zDNtE^nFlF`c@nFfa@xFnd@Hz@bDlWdF~_@`@rE\\\\|EPfFFjD?lDIrFSvFa@vGsAhZBhAu@~LSfHCpFDfEhAr\\\\lEfsABxBAtBCz@WtBMx@i@nBu@lB_AdB}B|C{MpPsCxDeAbBaAjB{@nBu@rBo@vBe@vB_@pBU`BqDx]s@lDi@zAg@dAgA~AsAvAyAjAeB~@eKjG{AbAqDvCqAlAiFxFaDfD}AxAm@d@yDhCgB|@qI|DuAl@uAt@g@^sAvAq@bA[j@o@zAQn@]hBIr@EjBBbBFr@XhBPp@\\\\bAl@vAn@dAfHlKlJtM|@vAx@vAn@zA^rA\\\\rBHx@DzBOlDw@dFsDzQWlBOjBEnBBpBDv@TnBr@`Dn@fBx@|AhA~AhApAbHpF|BnBf@h@fAzAb@n@x@bBl@lBb@nBTpBJrBCtBIpB}Cn`@i@pHqArP[|CGjAYxCqBlX_AhMQpBUlDItF?~BLdEZtFdDjb@~AlT|@vKnB~WRhEH|MQjG_Bhc@UrHQrIG|GFtKrAf}@R`i@@bLHrJXjv@HrGHlD^nJ~MzwCb@zHT|B`AxFT|@fBbGfAvBh@`A~G|NxAvCd\\\\dr@fC`FdElJxA`EnAlEtOrn@jGbV~DjPjB~Hf@`C`@dCVjCPjCBz@BbA?vCChAMhCUfCaApFa@`BaY|bAkFnR}DfNaBvGk@lCg@pCc@nCw@fHQrCOtC}Az]_Clg@e@jOUlViCteDNzs@W`BM^m@p@o@^YF]B[@]C[IW?qAaAi@o@e@{@Ki@CY?k@Di@Ne@Xi@Z]f@]f@Uf@Qd\\\\mFrP}Cp@G|Q{CrYeFnF{@rCg@bCUjAE~Sb@pT^dPP~ENn_@rAtENxDPfBLvFhAdRtFpC~@hHvBPA~BZt@@`CAlCMzMsBhBSbBYpEe@lBMbGIZElg@fBdFTdfAzD~K`@tBPhDf@fE`A~Af@vRtHlXpKzDpAdAX|Bf@|HtA|JbBvCj@pMtBjAPhN|BvDt@z@TjA`@rAn@hAr@`At@|@|@x@`At@hAj@`An@bBrHxTh@lBjAhFx@hFNdB~Dhg@b@`Cd@~AZt@|@lB|AtB~@bA~AlAfBbAh@T~SbIfDlA`Bp@bClA~@l@hA|@tApAr@x@nBpCd@|@p@xAtBbGr@fBxD`LlTbm@bHbS`_@hdAz@nBx@|A|@pA`AjAn@p@tAlAbAt@~A|@rClAjRhGfBr@jCnAnCdBpA~@|PjOpDlC|A`AbEvBzF|BrG~BjAj@~@f@|@l@~@r@fAfAbAdAtB|Cv@~Al@|Ad@xA|AbH|BhL`Jbd@x@tC^dAdAzBhAfB|ApBv@t@tBbBd@ZjDhBlHtD`Aj@`DdBv@\\\\~OhI~EhC`C|AvBfBpAtAn@x@dC`EjAnCn@jChAjDXbB@r@TbEnA`T@f@x@vORjGT`FVvBFrA`@dMd@bQHtDlApe@Ij@?lEBl@NnBRnBxAtH`AvBx@`B~BxDzDvFfCvDT`@`FlHfBnC~O|UjG~IrTj\\\\t@lA~AzBzC~Er@bAn@l@xB~CtAvBbB~CRf@vArDlNha@ZbATn@tBjGnBnFPn@tAhEFH^fAh@fBzAdExFxPtAvDlA~DvAnDRb@jExMl@tBlBfFv@|BLrKHx@?pFJzJI`N?tIAlDIhG",
  • "path": "19.43183-,99.13246|...|18.63085,-100.12845",
  • "vehicleType": "2AxlesHGV",
  • "departure_time": "2021-01-15T13:46:17"
}

Response samples

Content type
application/json
{
  • "summary": {
    },
  • "route": {
    }
}

Tolls after uploading GPS tracks

Use GPS tracks Toll API to calculate tolls after you make the trip. You can upload your GPS tracks (in csv, kml, gpx or nmea format) to receive tolls for the likely route matched using the GPS tracks. Specifically, with the GPS Tracks API endpoint you can

  • Specify vehicle type. For example, you can receive tolls for vehicles based on axle counts for cars, SUV, pick-up, trucks (up to 9-axles), motorcycle, bus, motorhome, RV, limousine.
  • Specify truck parameters such as weight, height, axle counts to receive tolls based on weight, height, etc.
  • Specify the timestamp of each GPS trace. If you do not specify the timestamp, tolls are likely to be inaccurate on time-based-toll facilities.
  • Specify whether you want to receive toll information immediately (isAsync=false) or can wait (isAsync=true). Use the asynchronous mode when uploading multiple or large GPS track files. Response in asynchronous mode comes with a requestId and a requestedTimestamp. These results would be available for download for up to 30 days.
  • Specify file type. While you can upload csv, kml, gpx or nmea files, we prefer CSV files.
Since you specify GPS track, you will receive tolls for the route matched using the track. However, the route matched may slightly change based on vehicle type specified. For example, let us consider express lanes that share route with general purpose lanes. If trucks are not allowed on the express lane, route matched for trucks will exclude express lanes and, therefore, is likely to be different compared to the route matched for a 2axle car. TollGuru matches GPS tracks to a route using Map Matching and calculate tolls for the matched route.Refer to this article to understand why we need to match GPS tracks to a route.

Upload GPS Tracks

By default, the API returns tolls in synchronous mode, where the response is immediate. You can receive tolls in the asynchronous mode by specifying the url parameter as isAsync=true. Response in this case comes with a requestId and a requestedTimestamp. These results would be available for download for up to 30 days. Use the asynchronous mode when uploading multiple or large GPS tracks files.

  • Upload CSV file- You can use the CSV format file as shown in the table below. Alternatively you can download the sample file from here.
  • Upload kml file
  • Upload gpx file
  • Upload nmea file

The first line in the CSV needs to contain the attribute names. The subsequent lines needs to contain the data in temporal order. The following parameters are available:

Parameter Description
latitude Latitude coordinate in WGS84 degree (mandatory)
longitude Longitude coordinate in WGS84 degree (mandatory)
timestamp indicates the time and date, for example 2018-05-21T17:05:06Z (mandatory since tolls may change based on time)
speed_mps speed in meters per second (optional)
speed_mph speed in miles per hour (optional)
speed_kmh speed in kilometers per hour (optional)
heading heading in degrees clockwise from North (optional)

You can use the CSV format file as shown in the table below:

latitude longitude timestamp
You can use the CSV format file as shown in the table below
latitude longitude timestamp
38.90479 -77.02607 2019-12-16T15:45:23Z
38.90479 -77.02606 2019-12-16T15:47:24Z
38.9048 -77.02608 2019-12-16T15:49:25Z
38.9044 -77.02604 2019-12-16T15:50:42Z
38.90424 -77.02646 2019-12-16T15:50:49Z
38.90422 -77.02686 2019-12-16T15:50:55Z

Points to be noted

GPX

Each trace point can have the following information:

  • Coordinates, for example <trkpt lat="38.90479" lon="-77.02607"> (always present), WGS84 degree
  • A timestamp, for example <time>2019-12-16T15:45:23Z</time> (optional), time zone UTC
  • Elevation, for example <ele>102.5999</ele> (optional), meter above the WGS84 ellipsoid
  • HDOP, for example <hdop>15.0</hdop> (optional)
  • Speed, for example <extensions><speed>21.9432334</speed></extensions> (optional), meter per second

NMEA

  • The information from the $GPRMC records is used
  • If an NMEA trace does not contain $GPRMC records, then the $GPGGA records are used.

KML

  • Either <Placemarks with <Points> or <Placemarks> with <LineStrings> can be submitted.
  • Note- Folders with multiple traces are not supported.
  • KML files may not work if user is looking for timebased tolls
query Parameters
vehicleType
required
string
Default: "2AxlesAuto"
Enum: "2AxlesAuto" "3AxlesAuto" "4AxlesAuto" "2AxlesLGV" "2AxlesHGV" "3AxlesTruck" "4AxlesTruck" "5AxlesTruck" "6AxlesTruck" "7AxlesTruck" "2AxlesBus" "3AxlesBus" "4AxlesBus" "2AxlesCaravanVan" "3AxlesCaravanVan" "4AxlesCaravanVan" "2AxlesMoto"
Example: vehicleType=2AxlesTruck

For more information of vehicle types read here

vehicleName
string

Specify name for your vehicle to identify the response json for particular vehicle

height
string

Specify the vehicle height to get accurate tolls for toll roads where tolls depend on axles and vehicle height

weight
string

Specify the vehicle weight to get accurate tolls for toll roads where tolls depend on axles and vehicle weight

isAsync
boolean
Default: false

The API will function in asynchronous mode is set to true

Request Body schema: text/csv
string <binary>

Responses

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_URL, "https://dev.tollguru.com/v1/calc/route/upload?vehicleType=2AxlesHGV&vehicleName=SOME_STRING_VALUE&height=SOME_STRING_VALUE&weight=SOME_STRING_VALUE&isAsync=SOME_BOOLEAN_VALUE");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "content-type: text/csv");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
Example
SyncResponse
SyncResponse
AsyncResponse
{
  • "status": "OK",
  • "summary": {
    },
  • "route": {
    }
}

Download Async Results

The results will be available for download for upto 30 days by calling the API.

Request Body schema: application/json
requestId
string
requestedTimestamp
string

Responses

Request samples

Content type
application/json
{
  • "requestId": "72ca5cba-b732-47ea-aec6-c7716bb37458",
  • "requestedTimestamp": "2020-06-15T04:27:08.838Z"
}

Response samples

Content type
application/json
{
  • "status": "OK",
  • "summary": {
    },
  • "route": {
    }
}

Errors and Troubleshooting

The TollGuru Toll API uses conventional HTTP status codes to indicate any errors that occur while processing requests. In general- Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., origin and destination is same, etc.). Codes in the 5xx range indicate an error with TollGuru server. The responses provided below can help in debugging the error.

  1. Input Error - (INPUT_ERROR)

    Errors caused as a result of bad csv file or malformed inputs

    Example

     { "status": "ERROR", "message": "Internal server error", "error": "Request Id(f4c828ce-9516-4b5e-8146-313dd1102414) does not have any results", "code": "INPUT_ERROR" }

  2. Routing Error - (ROUTING_ERROR)

    Errors arising out of routing issues like traces not making a valid route as detected by our algorithm.

    Example

     { "status": "ERROR", "requestId": "f4c828ce-9516-4b5e-8146-313dd1102414", "message": "Internal server error", "code": "ROUTING_ERROR", "value": "Provider routing error!", "backoff": 3600 }

  3. Tolling Error - (TOLLING_ERROR)

    Errors caused while finding the toll prices of a given route.

    Example

     { "status": "ERROR", "requestId": "f4c828ce-9516-4b5e-8146-313dd1102414", "message": "Internal server error", "error": "Tolling error", "code": "TOLLING_ERROR", "backoff": 3600 }

  4. Service Error - (SERVICE_ERROR)

    Errors due to service disruptions and a catch-all for server side issues.

    Example

     { "status": "ERROR", "requestId": "f4c828ce-9516-4b5e-8146-313dd1102414", "message": "Internal server error", "error": "Sorry, your subscription does not allow using this endpoint", "code": "SERVICE_ERROR", "backoff": 3600 }

Error response format

  • The general error response format is backward compatible
  • Adds new fields in the JSON
    • code
    • backoff
  • code contains one of the values from the list above.
  • backoff and requestId are shown for ROUTING_ERROR, TOLLING_ERROR, SERVICE_ERROR (all errors except INPUT_ERROR).
  • backoff field is a numerical value specified in seconds.
  • backoff field has a minimum value of 3600 (1 hour).
  • requestId field is useful to provide context for debugging issues when reported.

Vehicle types supported by TollGuru

Here's a country-wise list of supported vehicle type in TollGuru

Any of the following can be given as value to vehicleType argument. By default it's 2AxlesAuto.

North America - United States, Canada, Mexico
  • Car, SUV, Pickup truck
    Icon vehicleType Description
    2AxlesAutoCar, SUV or Pickup truck
    3AxlesAutoCar, SUV or Pickup truck towing 1-axle trailer
    4AxlesAutoCar, SUV or Pickup truck towing 2-axle trailer
    2AxlesDualTireSUV or Pickup, 4 tires on rear
    3AxlesDualTireSUV or Pickup, 4 tires on rear, 1-axle trailer
    4AxlesDualTireSUV or Pickup, 4 tires on rear, 2-axle trailer
  • Rideshare, Taxi, Carpool
    Icon vehicleType Description
    2AxlesTNCRideshare - Car, SUV or Pickup truck
    2AxlesTNCPoolRideshare Pool - Car, SUV or Pickup truck
    2AxlesTaxiTaxi - Car, SUV or Pickup truck
    2AxlesTaxiPoolTaxi Pool - Car, SUV or Pickup truck
    Hov2Carpool (2 occupants)
    Hov3Carpool (3+ occupants)
  • Truck
    Icon vehicleType Description
    2AxlesTruckTruck - 2 Axles
    3AxlesTruckTruck - 3 Axles
    4AxlesTruckTruck - 4 Axles
    5AxlesTruckTruck - 5 Axles
    6AxlesTruckTruck - 6 Axles
    7AxlesTruckTruck - 7 Axles
    8AxlesTruckTruck - 8 Axles
    9AxlesTruckTruck - 9 Axles
  • Bus
    Icon vehicleType Description
    2AxlesBusBus - 2 Axles
    3AxlesBusBus - 3 Axles
  • Motorcycle
    Icon vehicleType Description
    2AxlesMotorcycleMotorcycle
    3AxlesMotorcycleMotorcycle towing trailer
  • Recreational Vehicle
    Icon vehicleType Description
    2AxlesRvRV
    3AxlesRvRV towing 1-axle trailer
    4AxlesRvRV towing 2-axle trailer
Europe - UK, France, Spain, Portugal, Ireland, Netherlands, Denmark, Norway, Sweden, Italy, Germany
  • Car and SUV
    Icon vehicleType Description
    2AxlesAutoCar, SUV
    3AxlesAutoCar, SUV towing 1-axle trailer
    4AxlesAutoCar, SUV towing 2-axle trailer
  • Truck
    Icon vehicleType Description
    2AxlesLGVLight goods vehicles 2-Axles
    2AxlesHGVHeavy goods vehicles 2-Axles
    3AxlesTruckTruck - 3 Axles
    4AxlesTruckTruck - 4 Axles
    5AxlesTruckTruck - 5 Axles
    6AxlesTruckTruck - 6 Axles
    7AxlesTruckTruck - 7 Axles
  • Bus
    Icon vehicleType Description
    2AxlesBusBus - 2 Axles
    3AxlesBusBus - 3 Axles
    4AxlesBusBus - 4 Axles
  • Motorhome
    Icon vehicleType Description
    2AxlesCaravanVanMotorhome
    3AxlesCaravanVanMotorhome towing 1-axle trailer
    4AxlesCaravanVanMotorhome towing 2-axle trailer
  • Motorcycle
    Icon vehicleType Description
    2AxlesMotoMotorcycle, Motorcycle with sidecar
Australia - Australia
  • Car, SUV
    Icon vehicleType Description
    2AxlesAutoCar, SUV
    AutoTrailerCatACar towing trailer (length<12.5 meter & height <2 meter)
    AutoTrailerCatBCar towing trailer (length>12.5 meter & height >2 meter)
  • Taxi
    Icon vehicleType Description
    TaxisTaxi
  • Truck
    Icon vehicleType Description
    2AxlesLCVLight Commercial Vehicles
    2AxlesHCVTruck 2-Axles, Rigid
    3AxlesTruckTruck 3-Axles, Rigid, Articulated
    4AxlesTruckTruck 4-Axles, Rigid, Articulated
    5AxlesTruckTruck 5-Axles, Articulated
    6AxlesTruckTruck 6-Axles, Articulated, B-Double
    7AxlesTruckTruck 7-Axles, Articulated, B-Double
  • Bus
    Icon vehicleType Description
    BusBus
  • Recreational Vehicle
    Icon vehicleType Description
    RVCatARV (length < 12.5 meter & height < 2 meter)
    RVCatBRV (length > 12.5 meter or height > 2 meter)
  • Motorcycle
    Icon vehicleType Description
    2AxlesMotoMotorcycle; with or without trailer
Asia - India
  • Car, Jeep, Van, SUV
    Icon vehicleType Description
    2AxlesAutoCar, Jeep, Van, SUV
  • Bike
    Icon vehicleType Description
    2AxlesMotoBike
  • Pickup Truck, Light Commercial Vehicle
    Icon vehicleType Description
    2AxlesLCVPickup truck, Light Commercial Vehicles
  • Truck
    Icon vehicleType Description
    2AxlesTruckTruck - 2-Axles
    3AxlesTruck - 3 Axles
    4AxlesTruck - 4 Axles
    5AxlesTruck - 5 Axles
    6AxlesTruck - 6 Axles
    7AxlesTruck - 7 Axles
  • Bus
    Icon vehicleType Description
    2AxlesBusBus - 2-Axles
  • Heavy Construction Machinery and Earth Moving Equipment
    Icon vehicleType Description
    2AxlesHCMEMEHCM, EME
Latin America - Peru, Colombia, Argentina, Chile
  • Car, SUV, Pickup truck
    Icon vehicleType Description
    2AxlesAutoCar, SUV or Pickup truck
    3AxlesAutoCar, SUV or Pickup truck towing 1-axle trailer
    4AxlesAutoCar, SUV or Pickup truck towing 2-axle trailer
  • Truck
    Icon vehicleType Description
    2AxlesTruckTruck - 2 Axles
    3AxlesTruckTruck - 3 Axles
    4AxlesTruckTruck - 4 Axles
    5AxlesTruckTruck - 5 Axles
    6AxlesTruckTruck - 6 Axles
    7AxlesTruckTruck - 7 Axles
  • Bus
    Icon vehicleType Description
    2AxlesBusBus - 2 Axles
    3AxlesBusBus - 3 Axles
  • Recreational Vehicle
    Icon vehicleType Description
    2AxlesRvRV
    3AxlesRvRV towing 1-axle trailer
    4AxlesRvRV towing 2-axle trailer
  • Motorcycle
    Icon vehicleType Description
    2AxlesMotorcycleMotorcycle