Batch Toll Calculation

Contents

Batch Toll Calculation Endpoint (`/toll/batch`)

This documentation details the advanced capabilities and usage of the /toll/batch endpoint. This endpoint allows you to perform calculations for multiple routes, and for each route, multiple vehicle types, within a single API call, offering maximum efficiency in API usage.

Core Purpose and Benefits

The Batch Toll Calculation endpoint is designed to significantly optimize your interactions with the Adastra Toll API, especially for applications requiring extensive toll cost analysis.

Reduced HTTP Calls: Instead of sending hundreds of individual requests, you can consolidate all your calculation needs into one single request. This dramatically decreases network overhead and client-side processing.
Enhanced Performance: Your batch requests are processed in parallel on the backend. This parallelization leads to a substantial reduction in total response time compared to making sequential individual requests, improving the responsiveness of your applications.
“What-If” Analysis and Optimization: Gain the ability to quickly compare toll costs for various vehicle types over the same route in one go. This feature is invaluable for performing “what-if” cost analyses, optimizing fleet routes, and making informed decisions about logistics and pricing strategies.

Endpoint Usage

URL: POST https://api.adastrai.com/toll/batch?key=YOUR_API_KEY

API Key (key): Your API key, which must be valid for batch processing, should be appended as a query string parameter to the endpoint URL for the entire batch operation.

Request Format (Body)

The request body is a JSON array, where each element represents a single route and specifies the vehicle types for which toll calculations should be performed for that route.

Each object within the array supports the following parameters:

steps (Required):
- Type: string
- Description: The route’s coordinates string (semicolon-separated latitude and longitude pairs). Each latitude and longitude value must be rounded to 5 decimal places.
- Example: "40.90878,29.31577;41.00305,28.96113"
- For detailed guidance on preparing this steps parameter, including obtaining coordinates from Google Maps Platform APIs, please refer to our dedicated documentation: Preparing the steps Parameter.
vehicleTypeIds (Required):
- Type: array of integer
- Description: A list of one or more vehicle type IDs for which tolls should be calculated for the given route.
- Possible values:
  - 1: Two-axle vehicles with an axle spacing less than 3.20m
  - 2: Two-axle vehicles with an axle spacing of 3.20m or more (subject to UKOME decision)
  - 3: Three-axle vehicles
  - 4: Four and five-axle vehicles
  - 5: Six or more axle vehicles
  - 6: Motorcycles
- Example: [1, 2]
formatSteps (Optional):
- Type: boolean
- Description: If set to true, the steps coordinates will be rounded to 5 decimal places on the server side before processing. This can be useful if your source coordinates have higher precision but you want the API to handle the rounding.
- Default value: false
- Note: The ability to use the formatSteps feature might require a specific entitlement or a higher tier API membership. Please contact Adastra support for details.
departureTime (Optional):
- Type: string
- Description: The departure time of the route in ISO 8601 format. This parameter is used to calculate toll costs based on the pricing at the given time. If not provided, the current time will be used.
- Example: "2025-09-01T12:00:00Z"
mapSource (Optional):
- Type: string
- Description: The source of the map data used for route calculation. This helps in understanding the context of the provided steps.
- Possible values: "google", "tomtomv1", "tomtomv2"
- Example: "google"
lang (Optional):
- Type: string
- Description: The language code for the response messages. (default “en”)
- Possible values: "en" (English), "tr" (Turkish)
- Example: "tr"
expandTollsData (Optional):
- Type: boolean
- Description: A flag to indicate whether the details of individual tolls (e.g., routeEntry, routeExit) should be expanded within the tolls array in the response.
- Possible values: true, false
- Default value: false

Request Body Example:

This example shows a batch request for two distinct routes. The first route will have tolls calculated for vehicle types 1 and 2, with server-side step formatting enabled. The second route will calculate tolls only for vehicle type 6.

[
  {
    "steps": "40.90878345,29.31577123;41.00305489,28.96112578",
    "vehicleTypeIds": [1, 2],
    "departureTime": "2025-09-01T12:00:00Z",
    "mapSource": "google",
    "lang": "en",
    "expandTollsData": true,
    "formatSteps": true
  },
  {
    "steps": "40.90878,29.31577;41.00305,28.96113;41.00312,28.96123",
    "vehicleTypeIds": [6],
    "departureTime": "2025-09-01T15:30:00Z",
    "mapSource": "google"
  }
]

Response Format

The response is a nested array structure, mirroring the order and structure of your request. For each route in your request array, an inner array of result objects is returned, corresponding to each vehicle type specified for that route.

Structure: List<List<TollResponseData>>
- The outer list represents the routes as they appeared in your request.
- The inner list contains the calculated results for each vehicle type requested for that specific route.

Successful Response Example:

Corresponding to the request example above:

[
  [
    {
      "status": "success",
      "code": 200,
      "message": "Toll calculation completed successfully",
      "data": {
        "totalPrice": 95.50,
        "currency": "TRY",
        "vehicle": { "type": "two_axle_small", "code": "1" },
        "companyPrices": { "KGM": { "totalPrice": 95.50, "tollCount": 2 } },
        "calculatedAt": "2025-09-01T12:00:01.123Z",
        "tolls": [
            { "highwayCode": "KGM_ANADOLU", "priceAmount": 50, "routeEntry": "X", "routeExit": "Y", "companyCode": "KGM", "priceType": "actual", "tollType": "directional_pricing", "tollStructure": "barrier", "found": true, "order": 1 },
            { "highwayCode": "KGM_BRIDGE", "priceAmount": 45.50, "routeEntry": "A", "routeExit": "B", "companyCode": "KGM", "priceType": "actual", "tollType": "sensor_pricing", "tollStructure": "bridge", "found": true, "order": 2 }
        ],
        "elapsedMilliseconds": 150,
        "tollingStartDate": 20240816,
        "cache": false
      }
    },
    {
      "status": "success",
      "code": 200,
      "message": "Toll calculation completed successfully",
      "data": {
        "totalPrice": 150.75,
        "currency": "TRY",
        "vehicle": { "type": "two_axle_large", "code": "2" },
        "companyPrices": { "KGM": { "totalPrice": 150.75, "tollCount": 2 } },
        "calculatedAt": "2025-09-01T12:00:01.200Z",
        "tolls": [
            { "highwayCode": "KGM_ANADOLU", "priceAmount": 80, "routeEntry": "X", "routeExit": "Y", "companyCode": "KGM", "priceType": "actual", "tollType": "directional_pricing", "tollStructure": "barrier", "found": true, "order": 1 },
            { "highwayCode": "KGM_BRIDGE", "priceAmount": 70.75, "routeEntry": "A", "routeExit": "B", "companyCode": "KGM", "priceType": "actual", "tollType": "sensor_pricing", "tollStructure": "bridge", "found": true, "order": 2 }
        ],
        "elapsedMilliseconds": 160,
        "tollingStartDate": 20240816,
        "cache": false
      }
    }
  ],
  [
    {
      "status": "success",
      "code": 200,
      "message": "Toll calculation completed successfully",
      "data": {
        "totalPrice": 45.00,
        "currency": "TRY",
        "vehicle": { "type": "motorcycle", "code": "6" },
        "companyPrices": { "KGM": { "totalPrice": 45.00, "tollCount": 1 } },
        "calculatedAt": "2025-09-01T15:30:00.800Z",
        "tolls": [
            { "highwayCode": "KGM_BRIDGE", "priceAmount": 45.00, "routeEntry": "C", "routeExit": "D", "companyCode": "KGM", "priceType": "actual", "tollType": "sensor_pricing", "tollStructure": "bridge", "found": true, "order": 1 }
        ],
        "elapsedMilliseconds": 100,
        "tollingStartDate": 20240816,
        "cache": false
      }
    }
  ]
]

Error Handling within Batch Responses

One of the key advantages of the batch endpoint is its robust error handling. If a calculation for a specific route and vehicle type fails (e.g., no toll gates found, invalid steps), an error object will be returned in place of the successful data object for that specific item within the nested array. This allows other calculations in the batch to proceed successfully without interruption.

The vehicle object within the error response helps you identify exactly which vehicle type’s calculation encountered an issue.

Error Response Example for a single item:

This example shows a scenario where the calculation for a specific route and vehicle type 1 failed because no toll gates were found.

[
  [
    {
      "status": "notollgates",
      "code": 404,
      "message": "No toll gates were found for the provided route.",
      "data": {
        "vehicle": { "type": "two_axle_small", "code": "1" }
      }
    }
  ],
  [
    {
      "status": "success",
      "code": 200,
      "message": "Toll calculation completed successfully",
      "data": { "vehicle": { "code": "6" }, "totalPrice": 45.00, "tolls": [] }
    }
  ]
]

For a comprehensive list of possible error codes and their descriptions, please refer to the Error Handling section below.

Request Examples

Here are some examples of how to send a batch request to the /toll/batch endpoint using different programming languages.

Curl

curl -X POST \
  'https://api.adastrai.com/toll/batch?key=YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "steps": "40.908783,29.315771;41.003054,28.961125",
      "vehicleTypeIds": [1, 2],
      "departureTime": "2025-09-01T12:00:00Z",
      "mapSource": "google",
      "lang": "en",
      "expandTollsData": true,
      "formatSteps": true
    },
    {
      "steps": "40.90878,29.31577;41.00305,28.96113",
      "vehicleTypeIds": [6],
      "departureTime": "2025-09-01T15:30:00Z",
      "mapSource": "google"
    }
  ]'

JavaScript (fetch)

const url = 'https://api.adastrai.com/toll/batch?key=YOUR_API_KEY';
const batchData = [
    {
      "steps": "40.908783,29.315771;41.003054,28.961125",
      "vehicleTypeIds": [1, 2],
      "departureTime": "2025-09-01T12:00:00Z",
      "mapSource": "google",
      "lang": "en",
      "expandTollsData": true,
      "formatSteps": true
    },
    {
      "steps": "40.90878,29.31577;41.00305,28.96113",
      "vehicleTypeIds": [6],
      "departureTime": "2025-09-01T15:30:00Z",
      "mapSource": "google"
    }
];

fetch(url, {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
    },
    body: JSON.stringify(batchData),
})
.then(response => response.json())
.then(data => console.log("Batch Toll Response:", JSON.stringify(data, null, 2)))
.catch((error) => console.error('Error in batch toll calculation:', error));

Python (requests)

import requests
import json

url = 'https://api.adastrai.com/toll/batch?key=YOUR_API_KEY'
batch_data = [
    {
      "steps": "40.908783,29.315771;41.003054,28.961125",
      "vehicleTypeIds": [1, 2],
      "departureTime": "2025-09-01T12:00:00Z",
      "mapSource": "google",
      "lang": "en",
      "expandTollsData": True,
      "formatSteps": True
    },
    {
      "steps": "40.90878,29.31577;41.00305,28.96113",
      "vehicleTypeIds": [6],
      "departureTime": "2025-09-01T15:30:00Z",
      "mapSource": "google"
    }
]
headers = {'Content-Type': 'application/json'}

response = requests.post(url, headers=headers, data=json.dumps(batch_data))
print("Batch Toll Response:", json.dumps(response.json(), indent=2))

Important Considerations

API Key: Always ensure your API key is included in the URL as a query parameter.
steps Parameter: It is critical to adhere to the specified format for the steps parameter: semicolon-separated latitude and longitude pairs, with each coordinate rounded to 5 decimal places. Incorrect formatting is a common cause of errors.
vehicleTypeIds: Each item in the batch request vehicleTypeIds array must contain at least one valid vehicle type ID.
departureTime: This parameter should be provided in ISO 8601 format. If omitted for any route, the current time will be used for that specific calculation.
Accuracy: For the most accurate results, ensure that the vehicleTypeId and the steps data precisely match the real-world conditions of the route and vehicle being used.
Caching: The API employs a caching mechanism. If a request for a specific route and vehicle type has been processed recently with the same parameters, the response might be retrieved from the cache, resulting in faster response times (indicated by cache: true in the response data).
Rate Limiting: Please consult our rate limiting documentation or contact Adastra support for details on batch request limits and how they apply to your API usage. This is important for planning your application’s request frequency.
formatSteps Entitlement: As noted, the formatSteps: true option might require a specific API plan or entitlement. If you encounter issues, please verify your subscription details or contact support.

Error Handling

The Adastra Toll API uses standard HTTP status codes to indicate the overall result of a batch request. However, individual calculation failures within a batch are reported in the response body itself, as described in the Error Handling within Batch Responses section.

Here are the possible status codes and associated messages you might encounter at an individual item level within the batch response:

status: "success", code: 200:
- Description: The calculation for this specific route and vehicle type was successful.
- Response body includes the calculated toll information in the data field.

status: "invalidinput", code: 400:

Description: The request for this item was invalid due to incorrect parameters or malformed input data (e.g., improperly formatted steps, invalid vehicleTypeId).

Example:

{
    "status": "invalidinput",
    "code": 400,
    "message": "Invalid steps format provided for this route.",
    "data": { "vehicle": { "type": "unknown", "code": "1" } }
}

status: "notollgates", code: 404:
- Description: No toll gates were found for the provided route within the Adastra database. This could mean the route does not contain any toll segments, or the steps provided do not accurately represent a known toll road.
- Example:
```
{
    "status": "notollgates",
    "code": 404,
    "message": "No toll gates were found for the provided route.",
    "data": { "vehicle": { "type": "two_axle_small", "code": "1" } }
}
```

status: "pricecalculationfailed", code: 422:

Description: The request was syntactically valid, but the server encountered an issue processing the price calculation due to internal logic or data inconsistencies.

Example:

{
    "status": "pricecalculationfailed",
    "code": 422,
    "message": "Price calculation failed due to an internal error for this specific segment.",
    "data": { "vehicle": { "type": "three_axle", "code": "3" } }
}

status: "pricingdataunavailable", code: 503:

Description: The necessary pricing data for the requested route or toll segment is temporarily unavailable. This is usually a transient issue.

Example:

{
    "status": "pricingdataunavailable",
    "code": 503,
    "message": "Pricing data is currently unavailable. Please try again later.",
    "data": { "vehicle": { "type": "motorcycle", "code": "6" } }
}

status: "error", code: 500:

Description: An unexpected internal server error occurred during the processing of this specific item.

Example:

{
    "status": "error",
    "code": 500,
    "message": "An unexpected server error occurred during calculation for this item.",
    "data": { "vehicle": { "type": "two_axle_small", "code": "1" } }
}

Contents

Batch Toll Calculation

Batch Toll Calculation Endpoint (/toll/batch)

Core Purpose and Benefits

Endpoint Usage

Request Format (Body)

Request Body Example:

Response Format

Successful Response Example:

Error Handling within Batch Responses

Error Response Example for a single item:

Request Examples

Curl

JavaScript (fetch)

Python (requests)

Important Considerations

Error Handling

Batch Toll Calculation Endpoint (`/toll/batch`)