TollGuru Toll API (2020-07-15T09_40_00Z)

Download OpenAPI specification:Download

MapUp Engineering Team: 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.

How to test?

Using Postman(recommended):

  • 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

  • Copy any individual API code snippet of 'Shell+Curl' type and use import option on Postman for testing a specific API.

Using Shell:

  • Make sure you have cUrl install on your system by running 'curl' command your terminal.

  • Copy the 'Shell+Curl' command and replace placeholder with your API key in the command text.

  • Run the command on your terminal to get the results.

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:
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" "2AxlesDualTire" "3AxlesDualTire" "4AxlesDualTire" "2AxlesTruck" "3AxlesTruck" "4AxlesTruck" "5AxlesTruck" "6AxlesTruck" "7AxlesTruck" "8AxlesTruck" "9AxlesTruck" "2AxlesBus" "3AxlesBus" "2AxlesMotorcycle" "3AxlesMotorcycle" "2AxlesRv" "3AxlesRv" "4AxlesRv"

For more information on vehicle types read here

DateTime (string) or Timestamp (number)
Default: "current time"
fuelPrice
number
Default: 3

Specify numeric value up to two decimal places

fuelPriceCurrency
string
Default: "USD"
Enum: "USD" "CAD" "MXN" "INR"
object

If you want an accurate estimate of fuel expenses, you will need to specify parameters specific to fuel price and fuel efficiency as fuelEfficiency object.

object

Truck routing only

object

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

state_mileage
boolean

Specify state mileage as boolean value

object

Responses

Request samples

Content type
application/json
{
  • "from": {
    },
  • "to": {
    },
  • "waypoints": [
    ],
  • "vehicleType": "2AxlesAuto",
  • "departure_time": 1551541566,
  • "fuelPrice": 2.79,
  • "fuelPriceCurrency": "USD",
  • "fuelEfficiency": {
    },
  • "truck": {
    },
  • "driver": {
    },
  • "state_mileage": true,
  • "hos": {
    }
}

Response samples

Content type
application/json
{