TollGuru Toll SDK API Guide
Introduction and Guide
Welcome to the TollGuru SDK API endpoint guide.
The TollGuru SDK enables enterprises to calculate costs for vehicular journeys, find optimal routes, reimburse tolls, and integrate these services into applications. It considers vehicle details, route restrictions, payment methods, timestamps, and departure times. Enterprise developers can optimize for journeys in real-time or calculate accurate costs for past trips.
The TollGuru SDK API endpoint considers the following key parameters to perform toll and fuel cost calculations:
- Vehicle type: The SDK adjusts calculations based on the vehicle type. Click here for the list of supported vehicle types in various regions — North America, Europe, Australia, Latin America and Asia
- Vehicle attributes: Details include axle count, height, weight, length, emission category, occupancy, dual wheels, wheelbase, etc.
- Route specifics: Details include start location (origin), end location (destination), waypoints, GPS tracks, route shape, encoded polylines.
- Travel time: The time of travel can influence routing, toll costs, and fuel expenses. Input details include departure time or timestamps
- Fuel efficiency and fuel costs: The fuel efficiency of the vehicle (city, highway) and travel speeds are factored into fuel expense calculations.
- Payment methods: Toll costs incurred can vary on the method of payment used such as cash, RFID tag, license plate reads, etc.
The TollGuru SDK includes multiple endpoints, each with its unique functionality. However, this document is focused on the following:
- Toll cost calculation between origin, destination, and waypoints: Retrieves route details, toll info, and fuel expenses using geo coordinates.
- Toll cost for polyline routes: Calculates tolls for encoded polylines from an external mapping provider or TollGuru, eliminating the need for explicit start/endpoints.
- Toll cost for GPS tracks CSV upload: Allows users to upload GPS tracking data to determine toll and fuel costs for specific routes.
The following table can be used to pick an appropriate endpoint based on your use case:
Installation and Setup
TollGuru SDK simplifies the installation process by providing Terraform scripts, allowing you to seamlessly install and set up the SDK on your cloud infrastructure. Terraform, an open-source tool, translates APIs into declarative configuration files, streamlining the SDK setup on your chosen cloud service provider.
For a comprehensive and detailed guide on setting up the SDK, please refer to the official documentation at the following link: TollGuru-SDK-Infra-Setup-Guide.
Getting started: How to use the SDK
Before diving into the detailed information about each endpoint, it’s essential to understand the fundamentals of using the TollGuru SDK. The upcoming sections will provide an overview of each endpoint, highlighting its functionalities and the importance of its features. You’ll also find the links to relevant sections in TollGuru API documentation in the following sections.
API reference
Toll Cost Calculation between Origin, Destination, and Waypoints
Overview: Use this API endpoint to calculate tolls between origin, destination, and waypoints (if any). The endpoint calculates routes and provides toll and fuel expense information for each of the routes.
Specifically, the endpoint performs the following tasks:
- calculates tolls for the specific vehicle.
- provides toll information for all logical routes between the origin and destination.
- provides fuel expenses for all logical routes between the origin and destination.
- performs a trade-off analysis and provides the cheapest, the fastest, and other optimal routes.
For a detailed guide on this endpoint, please refer to TollGuru API documentation.
Note: This endpoint is designed to calculate future trips; however, drivers might choose to travel on a different route than the one suggested by this endpoint. For toll calculations based on specific routes, use the GPS Tracks to Toll endpoint
/gps-tracks-csv-upload. Refer to the following section for details on this endpoint.
Endpoint API Specifications
- API route:
/origin-destination-waypoints - Method:
POST - Headers:
-Content-Type: application/json
Example request body:
{
"from": {
"lat": 36.61596,
"lng": -121.93112
},
"to": {
"lat": 36.59951,
"lng": -121.96013
},
"waypoints": [
{
"lat": 36.59984,
"lng": -121.94456
},
{
"lat": 36.58961,
"lng": -121.94980
}
],
"vehicle": {
"type": "2AxlesAuto"
},
"departure_time": "2023-06-15T17:36:34",
"fuelOptions": {
"fuelCost": {
"value": 3.85,
"currency": "USD",
"units": "$/gallon"
},
"fuelEfficiency": {
"city": 23.4,
"hwy": 30,
"units": "MPG"
}
}
}Toll Cost for Complete Polyline from a Mapping Service (external / TollGuru)
Overview: Use this API when you have a complete route from a mapping service. You will need to get the complete route from the mapping service (and not just the origin, destination, and some stops on the route) to receive accurate toll information. You can specify either the departure time of timestamps (preferred) along the route. For a detailed guide on this endpoint, refer to TollGuru API documentation.
Endpoint API Specifications
- API route:
/complete-polyline-from-mapping-service - Method:
POST - Headers:
-Content-Type: application/json
Example request body:
{
"mapProvider": "osm",
"polyline": "er|eFxnpjVJFvAv@XPb@T??Sd@EJMXIRIPO^KLIJIFA@QHKDC@SDa@HOD[@???H?D?BAD?@AB?B?B?B@B?HBJBF@DV^p@fADFHTBDBF?@?@@B?B@B?D@B?D?B?B?BAD?BAHAJELGVKPABCBADEBCBA@A@C@A?C@C@C?A?C@A?C?A?CAC?GAAAC?AAECAAAAA??AAAAAAAEGEKEIQ[ACGIEGIIGKCCCACCCACAECICEAGAA?C?A?C?E?E?E@C?EBUFKDOFUJUNIHKFGHKNKNCDCBKPIJEFEFEDCBC@]VA?GHKJEDGHMNORMNKPILABGJINGLGLGNKPSZKNORMTGF]j@EHOXOZKPIPQ\\KVGHCHEFIREFADCFCBAD?@AB?D?B?B?B?B?@@DBFJJ@@HBXF??RuANi@?APi@BI@EPe@LU^q@T]@AJOJM@ABCNQDIBE@G?A?K@IAK??fACd@?R?P@L@F@HB\\Jb@Td@ZNNHJFHDHDHZn@DHDJ^z@N`@@B@BLR@@@@BDJNBDDDLNHDHBBBD@F@FBD?D@@?D@F?F?H?BALAFALCLEJEHEDEFEBCBEFG@CHMDGRc@FQNUDI\\k@n@_A??Zq@Ra@@CHOBIJWJSDKN_@HQFS@CPc@`@kAHQFQN]HQXi@@]p@_ANM\\]TQJIDADEDCHEFERKTKLGPGPGVGVE`@GFATAb@E`@ClBMJAPATAD?XCZAHAPAZCXAB?TADATA^CPA^CRA^CTCL?NApAIzBOVAVCVCL?VCNAB?^CTALAb@CF?nAIpAINAJ?XCZAXCXALAJAJ?LALAd@CXCJAf@CdBMh@CXCXAJAZA^CfCOf@Eb@CNALA|BMZCJAj@CB?b@Er@E~@E|@G@?TAXCXAZC`AGd@CLALAXAVCXAt@EXCJ?~@GxG_@`AGTALAn@EtCORAVCVAZCTAb@Cr@E|@GLAp@E|@EZAb@Cb@CJAlCOXCTCTCPE^Gb@O@?z@a@LIXSLI^[NMHG@ABEBAPONQLKDETWJKBELKBEBCf@i@Z]Zc@h@m@VY??j@n@PV??T\\VXDDFDHBF@H@J@@@D?D@JBJDD@PHZRZRRLB@FBFBH@F@J?L?BAFADEDAHEDC@A@ABADEBEDE@C@A@C@ABGBG@I@C?G?G?E?Q??@Q@K?I@E?C@E@C@EJ[To@DKRe@L]HOHQ@CRe@BCDMJSJUBEN_@Te@DIRg@??FQFKDE@A@?@?@?@?B?@?JB~@R@?H@H@J@J@J?L?LAHCHCBALGJETKPK??HyA@M?OC[E]OwAAIScB?AAGAEAEAECCCG??i@Re@H",
"locTimes": [
[
0,
1689813315
],
[
4,
1689813339
],
[
22,
1689813438
],
[
192,
1689813468
],
[
216,
1689813530
],
[
281,
1689813690
],
[
469,
1689813697
],
[
472,
1689813734
],
[
522,
1689813767
],
[
549,
1689813797
],
[
577,
1689813824
]
],
"vehicle": {
"type": "2AxlesAuto"
},
"fuelOptions": {
"fuelCost": {
"value": 3.85,
"currency": "USD",
"units": "$/gallon"
},
"fuelEfficiency": {
"city": 23.4,
"hwy": 30,
"units": "MPG"
}
}
}Toll Cost for Route Polyline using Map Matching
Overview
The polyline Map Matching endpoint creates a route from the polyline using the SDK’s map matching service capabilities. This endpoint request body is similar to /complete-polyline-from-mapping-service. However, internally, it first converts the input polyline and locTime into GPS tracks with timestamps. The GPS track is then map-matched to create a route.
The tolls are calculated for the map-matched routes. It takes care of issues such as straight lines, duplicate locTimes, incorrect locTimes, etc. If you have GPS tracks (and not a route from a mapping service), we recommend using the polyline map-matching API. Based on our experience, we see the following scenarios where the data is from GPS tracks but is passed to the polyline API resulting in wrong tolls:
- Data has a lot of clusters (a lot of points in the polyline near a rest area, hotel, or warehouse)
- Points are connected by straight lines. If the polyline is a route from the mapping service, it cannot be connected by straight lines
- Timestamps don’t make sense (incomplete/incorrect). Timestamps from mapping services are logical.
You should specify timestamps along the route.
Endpoint API Specifications
- API route:
polyline-map-matching - Method:
POST
Example request body:
{
"mapProvider": "osm",
"polyline": "d{xeF_wkuZM]_@gAKa@GU?AKi@Ms@c@qBOw@G_@CQMi@Km@Kc@EU??I?GCECEGCGEECECEECGEGE??KBQBi@BUB]?qDN]@aBDY@W?a@?y@?Q?[?_@@K@??CBCDA@A@ABC@ABE@OHA?EDEFEH?r@AdC?XCbAChA?ZAb@E~AEzACx@O|E?HGjBEfAO~CGrBErB@fB?^@|@FbAF~@XbCVrANp@ZfALb@Rd@??JLBBFFj@jAZ`@RTLLf@h@^^DBHFHFFF@D@B@B@BlBjB\\X@@JHLJPJPHRJRHz@PH@TDRBN@R?LAN?VCzAKJA`BSz@I@AD?ZCH?DA|AEf@Cj@@T@l@KvAG~BOxBMb@?f@Fl@CVAdAItAK~AKn@ENClAGtDOzFGhFCtCAr@AN?vICX?lCAbKC\\?zGEJ?bA?hDC~A@jE?x@AxA?pBAhKEZ?\\Ap@AN?L?d@C\\?J?L?\\?@?`@?D?hFAtAB`A@f@@r@Bl@Bh@@dAD~@HfCLX@t@Ft@Fh@DlALrDf@\\DJBXBRDdAN|B\\nBZ~InBx@Rt@RlA^rHzB`@LdBh@dAZ`@LTF@@`ElAfLjDPDLFD@dAX~@\\d@NVHt@Rt@R@?|A^hDh@~B`@fBVLBH@P@z@JRBpD\\v@FnCZvBPjCLhABtA?|A@|@@lA?rBAtBC|@EtACv@AH?tACf@?j@AtACtCKbBIn@El@Ch@GdBQrAGp@GrBUbC[jBWbCa@pBa@`ASp@MFAfAWtHgBb@KdFkApBe@BAjAYdAWTGVGb@KhEo@NETCJAHARC~AOf@EtAGh@ChACl@AJ?vB?|@@z@@pNFV@`EBxB@D?l@?zDB|CBpGB|D@|NC`EKZ@`DMx@EdCKbBIrEUpAIv@In@EdAKv@IbAIjNoAdAGfCOfBInAEpAEhAEzBE`CCfCC~@@b@@`@A~@@fA@~ABv@@vCJnCLfBHvFb@|AJxCXhGr@fHjAtCf@`@HzBd@f@LhB`@pA\\dCp@pBj@FB~Af@fA\\`EnAvAh@nC`AdBp@dChAtCnAp@Xv@\\lCpA`EpBjCnAnB~@rAj@NF@?HDJDRFXLb@LTFXJTHz@TJBv@RtA\\dDv@FBhHrAtAXp@N??h@LfAVLBj@N`AVxAXzAZ|@Nl@JbANh@HrB`@|Cn@bCb@nB`@pATj@LxATdCb@`AND@t@LNBxAVp@Jb@FdANvB^~AVn@JrCb@dAPH@h@FlDl@`C`@hBXvC`@z@Nb@Fr@Jz@Lj@Jb@HfCf@B@n@Pp@Rf@PnAd@RHbA^pBt@tAn@j@Xz@h@tA|@~@n@hD`Cr@l@fBvApCxBdGxEl@j@jBzADD@@tBxADD~@l@PJnAr@lBz@tAf@XJZJlA\\rA\\d@HdBTpDb@TBpD^TBpD\\`Ff@jJ`AvANzHz@TBPB|Fn@`DZd@DfAF@?b@B`@@bAFRAjEDf@?d@AD?X?jAE@@^C^A`ACzDYh@EzAIfAIx@Ed@Cv@?~@ArBD\\@bBHr@HtBRvBVXBt@L|ARvKxAhANlBRlD`@f@Bf@D`AH`BF`ADR@fABx@@jEAdDEb@An@?bBABAtBEvCB@?D@vEN`ABl@FnBLR@f@FtAPtEv@zDx@fDt@lAZ`Cf@~A\\dCl@fBXzA^`PxCD@rC`@^FhIlAjARxCb@dAJz@Jl@HpAP~@Hv@Fj@BbBH`A@r@Dd@?|B@vACbAG^E\\CDArDYbBWbBW`BYvBi@pDaA`Cs@`B_@jCi@XGxEy@hCWfCSDAzCQnBI|@Ab@Ar@AxB?vB@`EJbCPvBNbDZnCb@nCb@lE~@XDXFH@`@JpDt@fJlB|F|@bBTrC^dALnEh@pEh@b@Db@F@?fBTzPpB\\DxOhBZDjPlB^DvBVb@F`@DbALL@dHz@|QvBJ@hFl@nH~@fE^`DZlBPr@FnALfAH@@rBNzFb@|AHZ@nBT|Dd@h@Fj@Ht@HlC`@\\HzMzBpATfBZpAT|@NrAVp@LhB^VJTFPDFBl@P`@NtAd@n@Vz@\\bBt@b@X^PbB~@rAz@tCvB~AvA\\ZzB|BdBrBj@z@xAvBV\\@@P\\pBnDZt@d@~@bAhC~@hCjAxDvA|Fn@rCr@lD`@jBt@`DNt@nFvVLf@HV?@@FnDhPZpATdAVfA\\vAv@|C~AzFFTJXNd@Vv@HRFRRn@zAdEnAbDDJ`@~@FJNXjAdCN\\\\p@~@hBv@vAt@vAb@v@x@tAb@r@zBnD~BrDV`@HLd@t@xArBhDfEx@~@bAhA\\^rArApAlAt@p@dAz@hAz@j@`@~@l@LJlBnAbC~A|At@~CvAhA\\t@Pz@Rr@HzAPrBRjAJjALj@Fz@FhBRh@Hz@LdCh@ZJv@PnFnArDv@vG|ApAVv@L@?^Ft@JXD|@Hx@D|FTf@@vEJ|@B|CXx@PhB^VFnGlB`@LVH|@ZJFHD^JZLh@PtAb@|CdArAb@fBl@~Ah@PFZJxBr@z@XTHVJHB^Lj@PfCz@l@P~@P|@Jh@DX@h@?^A`@Cr@IVETETELCl@O|@]n@]bDsBhA{@ROHG@?bBgA`EiCx@g@TM`@Qn@S^KVGZGLCZEPATC`@CTAbC?zA@bNBbE@vD?nB@bA?dB?fHNb@B`A@rBD@?b@?x@BD@hBPn@LTFRH`AZb@Nr@PfA\\??b@J?`@EdA?BSdDK`CIzACROdBOlCOxBMpBU`DI|@?BEt@Gx@Eh@Ch@InAAVGr@K|AALC|@AZ@FBp@D^DZJ\\FLLX`@~@??DPLf@@D?J@J?F?F?DADADEJQZGHEJEHq@pBYx@Wz@M^KZ@@?@?@?@?@?@?@?@?@A@?@A@?@A@?@A??@A?A??@A?A?A@CPCDGPGJ?@CHIH_@fAQn@GX?BABEN?@?@@@?@A??@?@?@?@A??@?@A??@A??@A?e@tA[dAM`@??Mb@YKsA]iBa@q@OsAa@cBg@[Ki@O}Ak@",
"locTimes": [
[
0,
1690457759
],
[
15,
1690457768
],
[
27,
1690457831
],
[
44,
1690457913
],
[
86,
1690458471
],
[
393,
1690459473
],
[
880,
1690459572
],
[
915,
1690459685
]
],
"vehicle": {
"type": "2AxlesAuto"
},
"fuelOptions": {
"fuelCost": {
"value": 1.62,
"currency": "AUD",
"units": "$/liter"
},
"fuelEfficiency": {
"city": 13,
"hwy": 9.7,
"units": "L/100km"
}
}
}Toll Cost for GPS Tracks CSV Upload
Overview: Use GPS tracks to Toll API to calculate tolls after the trip. You can upload your GPS tracks in CSV format to receive tolls for the likely route matched (using something like snap to roads) using the GPS tracks. This can be a preferred option to know the exact tolls incurred in a trip after a trip. For a detailed guide on this endpoint, please refer to TollGuru API documentation.
Endpoint API Specifications
- API route:
/gps-tracks-csv-upload - Method:
POST
Example request using cURL:
curl --location 'https://<base-url>/gps-tracks-csv-upload?vehicle=%7Btype:2AxlesAuto,weight:%7Bvalue:20000,unit:pound%7D,height:%7Bvalue:7.5,unit:meter%7D,length:%7Bvalue:7.5,unit:meter%7D,axles:4%7D' \
--header 'Content-Type: text/csv' \
--data '@/path/to/csv'Test Cases and Testing
The SDK comes with a testing suite. Details of some of the items included in the suite are listed below
- “test-SDK”: A Go-based stress test tool designed to perform comprehensive performance testing on API endpoints by making multiple concurrent requests.
- Stress Testing: It’s vital for ensuring server reliability under high-load scenarios, preventing crashes, and promoting better user experience.
- Customizable Parameters: “test-SDK” allows adjustments to parameters like connections, requests, message file path, and request interval to simulate real-world server challenges.
- Region-Specific Test Cases: The tool enables tailored stress testing for different regions using customizable JSON files. This ensures the accuracy of tests based on region-specific network conditions, user behavior, and peak usage times.
- Logging Functionality: The tool logs vital metrics and information during the stress test execution, providing insights into the server’s performance and resource utilization. This data helps in identifying potential bottlenecks and making informed decisions for server optimization.
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 for the input information (e.g., origin and destination are the same, etc.). Codes in the 5xx range indicate an error with the TollGuru server. For details about the error responses from API, please refer to TollGuru API documentation.
Error Codes
Status code: 400
{
"status": "INPUT_ERROR",
"message": "Polyline for unsupported country"
}{
"status": "INPUT_ERROR",
"message": "Unknown Height Unit. Available units are - meter, feet, meters, feets"
}{
"status": "INPUT_ERROR",
"message": "Height cannot be less than zero"
}{
"status": "INPUT_ERROR",
"message": "Unknown Weight Unit. Available units are - ton, pound, tonnes, pounds"
}{
"status": "INPUT_ERROR",
"message": "Weight cannot be less than zero"
}Status code: 500
{
"status": "SERVER_ERROR",
"message": "Internal Server Error"
}{
"status": "ROUTING_ERROR",
"message": "Error while fetching route from our routing service"
}FAQ
Why do we use POST requests instead of GET requests (unlike most mapping services)?
- Data sensitivity: POST requests provide better security for sensitive data as it is not exposed in the URL or browser history.
- Data size and complexity: Unlike GET requests that have size limitations, POST requests are suitable for transmitting large data payloads. We allow a lot more options that are suitable for POST requests.
- Security considerations: POST requests offer better protection against CSRF attacks compared to GET requests.
How to use SDK-API using different programming languages?
- The TollGuru SDK API can be used with Python, Java, Golang, Javascript, Ruby, .NET, PHP, and NodeJs. For the complete guide on using SDK API with different languages, please refer to TollGuru API Documentation.
Support and Contact Information
For any questions about SDK, email api@tollguru.com with a detailed description of the issue you encountered.
Licensing and Terms of Use
Conclusion
In summary, TollGuru SDK offers a seamless solution to enterprises for toll and fuel estimates and enhancing applications with advanced features. Designed for simplicity and efficiency, it accelerates development and elevates user experiences. Your feedback is invaluable, guiding our continuous improvement efforts. Thank you for choosing MapUp. Happy coding!
