Toll Calculation Endpoint
The Adastra Toll API’s toll calculation endpoint allows you to calculate the estimated toll costs for routes within Turkey. This endpoint considers various factors, such as vehicle type, road type, and toll structure, to provide accurate pricing.
Endpoint URL
The toll calculation endpoint can be accessed via a POST request to the following URL:
https://api.adastrai.com/toll?key=YOUR_API_KEY
Request Parameters
The toll calculation endpoint requires the following parameters to be sent in the body as a JSON object:
vehicleTypeId (Required):
- Type:
string
- Description: The ID of the vehicle type.
- 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"
lang (Optional):
- Type:
string
- Description: The language code for the response. (default “en”)
- Possible values:
"en": English"tr": Turkish
- Example:
"en"
mapsource (Required):
- Type:
string
- Description: The source of the map data used for route calculation.
- Possible values:
"google": Google Maps"tomtomv1": TomTom Maps"tomtomv2": TomTom Orbis Maps
- Example:
"google"
expandTollsData (Optional):
- Type:
boolean
- Description: A flag to indicate whether the details of tolls (routeEntry, routeExit etc..) should be expanded on the tolls array on the response.
- Possible values:
true: Tolls data will be expanded on the response.false: Tolls data will not be expanded on the response.
- Default value:
false
departureTime (Optional):
- Type:
string
- Description: The departure time of the route in ISO 8601 format. This parameter is used to calculate the toll costs based on the price at the given time. If this parameter is not provided, the current time will be used for the calculation.
- Example:
"2024-12-18T20:11:08.726Z"
steps (Required):
- Type:
string
- Description: The route’s coordinates string (semicolon-separated latitude and longitude pairs).
- Important Note: The
steps parameter should be a string of semicolon-separated latitude and longitude pairs, where latitude and longitude values are floating-point numbers with 5 decimal places. It is necessary to format the coordinates before sending them to the server. See the Preparing the steps Parameter section for details.
- Example:
"40.90855,29.31515;40.90878,29.31577;40.90878,29.31578;40.90922,29.31678;..."
Preparing the steps Parameter
The steps parameter requires a specific format: a string of semicolon-separated latitude and longitude pairs, with each value rounded to 5 decimal places. Here’s how to format your route coordinates before sending them to the API:
Example with JavaScript
const routePoints = [
{ latitude: 40.908783, longitude: 29.315771 },
{ latitude: 41.003054, longitude: 28.961125 },
];
// Format the data
const formattedRoutePoints = routePoints.map(point => ({
latitude: parseFloat(point.latitude.toFixed(5)),
longitude: parseFloat(point.longitude.toFixed(5)),
}));
const stepsString = formattedRoutePoints.map(point => `${point.latitude},${point.longitude}`).join(';');
// Send to server
console.log(stepsString);
// Expected output "40.90878,29.31577;41.00305,28.96113"
Explanation:
- The code takes an array of route points. Each point is an object containing the latitude and longitude as floating point number.
- The
map method iterates through each point and creates a new object where latitude and longitude are converted to 5 decimal places.
- The
map method is used to convert each point to a string of latitude,longitude format.
- The
join(';') method combines all the points into a single string separated by semicolons.
Response Structure
The toll calculation endpoint returns a JSON response with the following structure:
{
"status": "success",
"code": 200,
"message": "Toll calculation completed successfully",
"data": {
"totalPrice": 60,
"currency": "TRY",
"vehicle": {
"type": "two_axle_small",
"code": "1"
},
"companyPrices": {
"KGM": {
"totalPrice": 60,
"tollCount": 2
}
},
"calculatedAt": "2024-12-20T08:49:45.4146910Z",
"tolls": [
{
"highwayCode": "KGM_ANADOLU",
"companyCode": "KGM",
"routeEntry": "ORHANLI",
"routeExit": "SAMANDIRA",
"priceAmount": 27,
"priceType": "actual",
"tollType": "directional_pricing",
"tollStructure": "barrier",
"found": true,
"order": 463
},
{
"highwayCode": "KGM_BRIDGES_ISTANBUL",
"companyCode": "KGM",
"routeEntry": "15TemmuzKöp",
"routeExit": "15TemmuzKöp",
"priceAmount": 33,
"priceType": "actual",
"tollType": "sensor_pricing",
"tollStructure": "bridge",
"found": true,
"order": 954
}
],
"elapsedMilliseconds": 512,
"tollingStartDate": 20240816,
"cache": false
}
}
Response Fields
status:
- Type:
string
- Description: The status of the API request. Possible values:
"success", "error".
code:
- Type:
integer
- Description: The HTTP status code of the response.
message:
- Type:
string
- Description: A message indicating the result of the operation.
data:
- Type:
object
- Description: An object containing the toll calculation results.
totalPrice:
- Type:
number
- Description: The total toll price for the route.
currency:
- Type:
string
- Description: The currency of the toll price. (e.g:
"TRY")
vehicle:
- Type:
object
- Description: Information about the vehicle used for calculation.
type:
- Type:
string
- Description: The type of vehicle (e.g:
"two_axle_small").
code:
- Type:
string
- Description: The vehicle type ID. (e.g:
"1")
companyPrices:
- Type:
object
- Description: An object containing the toll prices for each company.
KGM:
- Type:
object
- Description: Toll prices for KGM (Karayolları Genel Müdürlüğü).
*
totalPrice:
- Type:
number
- Description: Total toll price for KGM.
*
tollCount:
- Type:
integer
- Description: Total count for KGM tolls.
calculatedAt:
- Type:
string
- Description: The timestamp of when the calculation was performed.
tolls:
- Type:
array
- Description: An array of objects, each representing a toll on the route.
highwayCode:
- Type:
string
- Description: The code of the highway on which the toll is located (e.g:
"KGM_ANADOLU").
companyCode:
- Type:
string
- Description: The code of the company operating the toll (e.g:
"KGM").
routeEntry:
- Type:
string
- Description: The entry point of the toll.
routeExit:
- Type:
string
- Description: The exit point of the toll.
priceAmount:
- Type:
number
- Description: The price of the toll.
priceType:
- Type:
string
- Description: The type of price, typically
"actual".
tollType:
* Type: string
* Description: The type of toll (e.g: "directional_pricing", "sensor_pricing").tollStructure:
- Type:
string
- Description: The structure of the toll (e.g:
"barrier", "bridge").
found:
- Type:
boolean
* Description: Boolean field that indicates if the toll was found on the route.
order:
* Type: integer
* Description: The order of toll on the route.
elapsedMilliseconds:
- Type:
integer
- Description: The time taken to calculate tolls in milliseconds.
tollingStartDate:
* Type: integer
* Description: The start date for the tolling period in the format YYYYMMDD.cache:
- Type:
boolean
- Description: A flag to indicate whether the response was retrieved from the cache.
Request Examples
Here are some examples of how to send a request to the Toll Calculation endpoint using different platforms.
Curl
curl -X POST \
'https://api.adastrai.com/toll?key=YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"vehicleTypeId": "1",
"lang": "en",
"mapsource": "google",
"expandTollsData": true,
"departureTime": "2024-12-18T20:11:08.726Z",
"steps": "40.90855,29.31515;40.90878,29.31577;40.90878,29.31578;40.90922,29.31678;..."
}'
JavaScript (fetch)
const url = 'https://api.adastrai.com/toll?key=YOUR_API_KEY';
const data = {
"vehicleTypeId": "1",
"lang": "en",
"mapsource": "google",
"expandTollsData": true,
"departureTime": "2024-12-18T20:11:08.726Z",
"steps": "40.90855,29.31515;40.90878,29.31577;40.90878,29.31578;40.90922,29.31678;..."
};
fetch(url, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify(data),
})
.then(response => response.json())
.then(data => console.log(data))
.catch((error) => console.error('Error:', error));
Python (requests)
import requests
import json
url = 'https://api.adastrai.com/toll?key=YOUR_API_KEY'
data = {
"vehicleTypeId": "1",
"lang": "en",
"mapsource": "google",
"expandTollsData": True,
"departureTime": "2024-12-18T20:11:08.726Z",
"steps": "40.90855,29.31515;40.90878,29.31577;40.90878,29.31578;40.90922,29.31678;..."
}
headers = {'Content-Type': 'application/json'}
response = requests.post(url, headers=headers, data=json.dumps(data))
print(response.json())
Important Considerations
- Ensure your API key is included in the URL as a query parameter.
- All parameters except
expandTollsData are required.
- The
steps parameter should be a string of semicolon-separated latitude and longitude pairs.
- The
departureTime parameter should be in ISO 8601 format.
- For accurate results, make sure that the vehicle type matches the vehicle that will be using the route.
- The API uses a caching mechanism. If the results are the same as before, response will be sent from the cache.
- Please refer to our rate limiting documentation or contact us for assistance if you are experiencing issues.
Error Handling
- In case of an error, the
status field in the response will be "error".
- The
code field will contain the corresponding HTTP status code.
- The
message field will provide a detailed error description.
Error Handling
The Adastra Toll API uses standard HTTP status codes to indicate the result of a request. Here are the possible error codes you may encounter with the Toll Calculation endpoint:
- 200 OK:
- Description: The request was successful, and the toll calculation was completed.
- Response body includes the calculated toll information, as described in the Response Structure section.
- 400 Bad Request:
- Description: The request was invalid due to incorrect parameters or input data.
- Response body includes:
status: "invalidinput"code: 400message: A detailed message describing the input error.
- Example:
{
"status": "invalidinput",
"code": 400,
"message": "Invalid vehicleTypeId provided."
}
- 404 Not Found:
- Description: No toll gates were found for the given route.
- Response body includes:
status: "notollgates"code: 404message: A message indicating no toll gates were found.
- Example:
{
"status": "notollgates",
"code": 404,
"message": "No toll gates were found for the provided route."
}
- 422 Unprocessable Entity:
- Description: The request was valid, but the server could not process it due to a problem with price calculation.
- Response body includes:
status: "pricecalculationfailed"code: 422message: A detailed message describing why price calculation failed.
- Example:
{
"status": "pricecalculationfailed",
"code": 422,
"message": "Price calculation failed due to internal error."
}
- 503 Service Unavailable:
- Description: Pricing data is currently unavailable.
- Response body includes:
status: "pricingdataunavailable"code: 503message: A message indicating the pricing data is unavailable.
- Example:
{
"status": "pricingdataunavailable",
"code": 503,
"message": "Pricing data is currently unavailable. Please try again later."
}
- 500 Internal Server Error:
- Description: An unexpected server error occurred.
- Response body includes:
status: "error"code: 500message: "An unexpected error occurred."
- Example:
{
"status": "error",
"code": 500,
"message": "An unexpected error occurred."
}
Important Considerations
- Ensure your API key is included in the URL as a query parameter.
- All parameters except
expandTollsData are required.
- The
steps parameter should be a string of semicolon-separated latitude and longitude pairs.
- The
departureTime parameter should be in ISO 8601 format.
- For accurate results, make sure that the vehicle type matches the vehicle that will be using the route.
- The API uses a caching mechanism. If the results are the same as before, response will be sent from the cache.
- Please refer to our rate limiting documentation or contact us for assistance if you are experiencing issues.