TollGuru Logo

Toll API FAQs

Last updated on Sep 12, 2023

Tolls between origin, destination, waypoints using a mapping service

How to make requests using addresses?

{
    "from": {
        "address": "Dallas, TX 75201 USA"
    },
    "to": {
        "address": "New York, NY 10007 USA"
    },
    "waypoints": []
}

How to make requests using geo-coordinates?

{
    "from": {
        "lat": 32.77822,
        "lng": -96.79512
    },
    "to": {
        "lat": 40.71453,
        "lng": -74.00712
    },
    "waypoints": []
 }

How to make requests using addresses?


{
    "from": {
        "lat": 32.77822,
        "lng": -96.79512
    },
    "to": {
        "lat": 40.71453,
        "lng": -74.00712
    },
    "waypoints": []
}

How to add waypoints?

Using address/ZIP code


{
    "from": {
        "address": "Dallas, TX 75201 USA"
    },
    "to": {
        "address": "NJ USA"
    },
    "waypoints": [
        {
            "address": "New York, NY 10007 USA"
        }
    ]
}

Using geo-coordinates

{
    "from": {
        "lat": 32.77822,
        "lng": -96.79512
    },
    "to": {
        "lat": 40.21789,
        "lng": -74.75942
    },
    "waypoints": [
        {
            "lat": 40.71453,
            "lng": -74.00712
        }
    ]
}

How to choose a mapping service provider?

By default, the Tolls API uses Here Maps as the mapping service provider if no provider is specified in the request. However, you can specify a different provider by setting the serviceProvider field in the request body.


{
    "from": {
        "address": "Dallas, TX 75201 USA"
    },
    "to": {
        "address": "New York, NY 10007 USA"
    },
    "waypoints": [],
    "serviceProvider": "gmaps"
}

How to customize a vehicle?

  1. The Tolls API supports customization of tolls based on the vehicle type and region of travel.
  2. Different vehicle types have different parameters that affect toll calculations, and these parameters can vary by region.
  3. In North America and Europe, tolls are particularly sensitive to vehicle customization.
  4. By default, the Tolls API uses “2AxlesAuto” as the vehicle type for calculating tolls, unless a different type is specified in the request.

How to add vehicle type in the request body?

{
    "from": {
        "address": "Dallas, TX 75201 USA"
    },
    "to": {
        "address": "New York, NY 10007 USA"
    },
    "waypoints": [],
    "vehicle": {
        "type": "4AxlesTruck"
    }
}

North America - Here, tolls are dependent on following vehicle parameters

height - For example, different rates may apply for vehicles with a height between 1-7 feet versus those that are 8 feet or taller.

{
    "from": {
        "lat": 40.69615,
        "lng": -75.18973
    },
    "to": {
        "lat": 40.69447,
        "lng": -75.21
    },
    "vehicle": {
        "type": "4AxlesAuto",
        "height": {
            "value": 10,
            "unit": "feet"
        }
    }
}

weight - For example, specifying a different weight in the request may result in a different toll rate being calculated.

{
    "from": {
        "lat": 39.33673,
        "lng": -74.51198
    },
    "to": {
        "lat": 39.33973,
        "lng": -74.52073
    },
    "vehicle": {
        "type": "2AxlesTruck",
        "weight": {
            "value": 20000,
            "unit": "pound"
        }
    }
}

When making a request to the Tolls API, users have the option to specify either the vehicle’s height or weight, or both. The tolls charged by the API will be calculated based on the provided vehicle parameters.

Europe - Here, tolls are dependent on following vehicle parameters

height - For example, different rates may apply for vehicles with different heights.

{
    "from": {
        "address": "525, 1839 Sofia, Bulgaria"
    },
    "to": {
        "address": "862, 4000 Tsentar, Plovdiv, Bulgaria"
    },
    "vehicle":{
        "type": "4AxlesTruck",
        "weight":{
            "value": 14,
            "unit": "ton"
        },
        "height":{
            "value": 20,
            "unit": "meter"
        },
        "axles": 4,
        "emissionClass": "euro_6"
    }
}

weight - For example, different rates may apply for vehicles with a weight between 4-11 tonnes versus those that are 12 tonnes or heavier.

{
    "from": {
        "address": "525, 1839 Sofia, Bulgaria"
    },
    "to": {
        "address": "862, 4000 Tsentar, Plovdiv, Bulgaria"
    },
    "vehicle":{
        "type": "4AxlesTruck",
        "weight":{
            "value": 14,
            "unit": "ton"
        },
        "height":{
            "value": 20,
            "unit": "meter"
        },
        "axles": 4,
        "emissionClass": "euro_6"
    }
}

axles -The toll rates in the Tolls API are subject to change based on the number of axles on the vehicle. Therefore, it is important to provide accurate axle information in the request to ensure reliable toll calculations.

{
    "from": {
        "address": "525, 1839 Sofia, Bulgaria"
    },
    "to": {
        "address": "862, 4000 Tsentar, Plovdiv, Bulgaria"
    },
    "vehicle":{
        "type": "4AxlesTruck",
        "weight":{
            "value": 14,
            "unit": "ton"
        },
        "height":{
            "value": 20,
            "unit": "meter"
        },
        "axles": 4,
        "emissionClass": "euro_6"
    }
}

emissionClass - For example, different rates may apply for vehicles with an emissionClass between euro_0-2 and those between euro_3-6. It is important to provide accurate vehicle emission information in the request to ensure reliable toll calculations.

{
    "from": {
        "address": "525, 1839 Sofia, Bulgaria"
    },
    "to": {
        "address": "862, 4000 Tsentar, Plovdiv, Bulgaria"
    },
    "vehicle":{
        "type": "4AxlesTruck",
        "weight":{
            "value": 14,
            "unit": "ton"
        },
        "height":{
            "value": 20,
            "unit": "meter"
        },
        "axles": 4,
        "emissionClass": "euro_6"
    }
}

Parameters related to calculate fuel expenses are:

  1. fuelCost
  2. fuelEfficiency
    {
        "from": {
            "address": "Dallas, TX 75201 USA"
        },
        "to": {
            "address": "New York, NY 10007 USA"
        },
        "vehicle":{
            "type": "2AxlesAuto"
        },
        "fuelOptions": {
            "fuelCost": {
                "value": 4,
                "currency": "USD",
                "units": "$/gallon"
            },
            "fuelEfficiency": {
                "city": 24,
                "hwy": 32,
                "units": "mpg"
            }
        }
     }

How to get turn by turn directions in response?

To retrieve turn-by-turn directions in the Tolls API response, include the parameter ‘directionsFlag’ and set it to ‘true’ in the request body.

{
    "from": {
        "address": "Dallas, TX 75201 USA"
    },
    "to": {
        "address": "New York, NY 10007 USA"
    },
    "directionsFlag": true
}

How to get tolls on your route based on departure time?

  1. The departure time parameter is an important component in time-based toll calculations in the Tolls API.
  2. There are two formats available for specifying the departure time: Epoch and UTC.
  3. The departure time parameter is an important component in time-based toll calculations in the Tolls API.

Example 1:

    {
        "from": {
            "lat": 33.71782,
            "lng": -117.72101
        },
        "to": {
            "lat": 33.70108,
            "lng":  -117.73188
        },
        "departure_time": "2023-05-10T05:00:00-07:00"
     }

Example 2

    {
        "from": {
            "lat": 33.71782,
            "lng": -117.72101
        },
        "to": {
            "lat": 33.70108,
            "lng":  -117.73188
        },
        "departure_time": "2023-05-10T08:00:00-07:00"
     }

How to get state mileage information for North America?

The Tolls API offers state mileage information for travel within the United States, providing details on the distance traveled and time taken to travel through each state. To retrieve this information, simply include the parameter ‘state_mileage’ and set it to ‘true’ in the request body.

{
    "from": {
        "address": "Dallas, TX 75201 USA"
    },
    "to": {
        "address": "New York, NY 10007 USA"
    },
    "state_mileage": true
}

How to get tolls for EV along with charging points for North America?

For EVs, along with tolls you might want to know charging points along the route.For this, you will have to use vehicle type as “2AxlesEV”

    {
        "from": {
            "address": "Dallas, TX 75201 USA"
        },
        "to": {
            "address": "New York, NY 10007 USA"
        },
        "vehicle":{
            "type": "2AxlesEV"
        }
    }

How to get vignette information for Europe?

If vignettes are applicable for your route, the Tolls API will include information about them in the response. You can use the following case to retrieve and utilize the vignette information for your application

{
    "from": {
        "address": "106 2700 Blagoevgrad Bulgaria"
    },
    "to": {
        "address": "Ivan Mihaylov 66, 2700 South-West University Neofit Rilski, Blagoevgrad, Bulgaria"
    },
    "waypoints": [],
    "vehicle":{
        "type": "2AxlesAuto"
    }
}