1. Three endpoints, one engine
TollTally has three API entry points. All price on the same toll data and the same rules as the dashboard. The difference is what you already have.
| You have | Use | What happens | Typical caller |
|---|---|---|---|
| A route from a mapping service (an encoded polyline or a list of coordinates) for a trip that will be driven or was planned | Complete polyline from a mapping service | The path is priced as given: every toll point it crosses, at the rate for the vehicle, direction and time | Ride pricing, trip quotes, TMS or dispatch route costing, navigation |
| A polyline you built from a vehicle's GPS points | Polyline map matching | The polyline is map-matched to the road network first, then the matched route is priced | Platforms that already hold GPS as a polyline |
| GPS points a vehicle actually produced, as a file | GPS tracks to toll | The points are map-matched to the road network first, then the matched route is priced | Driver reimbursement, post-trip billing, historical toll runs, telematics platforms |
The rule
If the points came from a vehicle, they need map matching: GPS tracks or polyline map matching. A GPS trace sent to the complete polyline endpoint is priced as drawn, and a trace with a reading every few minutes can pass beside a plaza without touching it. Map matching is what puts the vehicle on the road it was on.
2. Keys and authentication
TollTally uses its own API key. It is separate from a TollGuru key. Subscribe to TollTally Route Specific Tolls from the Subscriptions tab at platforms.mapup.ai, or send your sign-up address to tolltally@mapup.ai for an enterprise setup; the key is then in the TollTally API Keys section of the dashboard, click to view and copy. Up to 10 keys per account, so each project can carry its own. Usage and invoices are under Usage and Invoices.
Every request carries the key in the x-api-key header. Standard rate limits and plan caps apply to a new account; tell us the volumes you plan to run and we raise the caps.
POST <endpoint>
x-api-key: <your TollTally key>
Content-Type: application/jsonEndpoint URLs, the full request schema, the OpenAPI schema, client libraries and a Postman collection are on the API documentation page.
3. Route polyline to toll
Send the route and the vehicle; get back the tolls along it.
What goes in:
- The route, as the encoded polyline your mapping service returned, or as a path of coordinates. Any provider works: OSM, Google, HERE, TomTom, Mapbox, Bing, Apple, Esri and others. Some services return a polyline per step; decode, merge and re-encode into one polyline before sending (the GitHub examples do this).
- The vehicle: type and the attributes that change the rate (axles, weight, height, emission class where relevant). Section 5.
- Time: a departure time for the trip, or, for accurate time-of-day and dynamic pricing, a timestamp per point along the route so each crossing is priced at the time the vehicle reaches it. The time-aware form takes the path with a list of point index and Unix time pairs (
locTimes). The fallback order is fixed:locTimesif present, elsedeparture_time, else the current time. For a historical trip, send the times; a trip priced at today's clock is priced in the wrong rate window.
What comes back: the toll for each crossing along the route (facility, direction, the rate by payment method: tag, plate and cash where the facility has them), and a route summary. Exact field names are in the documentation and in the request and response examples (folder 02, Complete Polyline To Toll).
{
"mapProvider": "osm",
"path": "32.77945,-96.77997|32.77995,-96.78056|...",
"locTimes": [[0, "1689049610"], [48, "1689050100"], ...],
"vehicle": { ... }
}
Illustrative shape of a time-aware request. Field names and vehicle parameters: see the API documentation.4. GPS tracks to toll
Send the points a vehicle produced; TollTally map-matches them and prices the matched route.
- Format: CSV with
latitude,longitudeandtimestampcolumns. The first row holds the column names; each following row is one point, in time order. Coordinates are WGS84 degrees and the timestamp is ISO 8601,YYYY-MM-DDThh:mm:ssZ(for example2023-07-17T13:40:42Z); the timestamp is what places the crossing in the right rate window. Local times without an offset are the most common upload error. - Two modes. Synchronous, the default, returns the tolls in the response. Asynchronous (
isAsync=trueon/gps-tracks-csv-upload) returns a request ID; pass it to/gps-tracks-csv-downloadto collect the result. Async results are kept 30 days. Use asynchronous for long tracks and batch runs. - The response carries the matched route as well as the tolls, so you can show the driver or the auditor the road the vehicle was placed on.
Cover the whole trip. On a ticket system (entry plaza, exit plaza, fare by distance) the track has to include both the entry and the exit; a track that starts inside the system cannot be priced as driven. Section 7 has the error this produces.
Reference implementation: GPS tracks CSV upload on GitHub, with sample tracks for several countries and both modes; request and response bodies in folder 03 of the payload examples.
5. Vehicle parameters
The same road prices differently by vehicle, so the vehicle goes on every request. Send what changes the rate:
| Parameter | Why it matters |
|---|---|
| Vehicle type | Selects the class table: car, truck, bus, motorcycle and the sub-types the documentation lists |
| Axle count | Class on most US facilities and many closed systems |
| Weight and height | Class on facilities that price by weight or height band |
| Emission class | Rate on European distance-based truck tolls priced by Euro or CO2 class |
| Payment method | Which rate you want highlighted; the response carries tag and plate rates where the facility has both |
Supported vehicle types, parameter definitions and defaults are in the API documentation and the API FAQ. If a parameter is left out, the documented default applies; send the real value for a commercial vehicle.
6. How transactions are counted
Transactions are counted per endpoint and by route distance. Anything that map-matches counts twice: once for the matching, once for the pricing.
| Endpoint | Route up to 300 miles | 301 to 1,000 miles | Over 1,000 miles |
|---|---|---|---|
| Complete polyline from a mapping service | 1 transaction | 2 | 3 |
| Polyline map matching | 2 transactions | 4 | 6 |
| GPS tracks | 2 transactions | 4 | 6 |
Any input or routing error counts as one transaction, so validate before you send. Monthly volume sets the unit rate on a stair-stepped scale; plans and usage are on the dashboard under Usage and Invoices. Full detail: how transactions are counted for the TollTally API.
7. Common errors and what to do
| What you see | Cause | Fix |
|---|---|---|
| Tolls missing on a road you know is tolled (complete polyline endpoint) | The polyline was built from sparse GPS and passes beside the plaza rather than through it, or the route geometry is too coarse | Send vehicle-produced points to GPS tracks or polyline map matching so they are map-matched; for planned routes, send the full-resolution polyline from the mapping service |
| Key rejected | A TollGuru key sent to a TollTally endpoint, or a key from an account without a TollTally subscription | Use a key from the TollTally API Keys section of the dashboard |
| Timestamps rejected or crossings in the wrong rate window | Local times without an offset, or a format other than ISO 8601 | Send YYYY-MM-DDThh:mm:ssZ on GPS tracks; send locTimes or departure_time on polylines |
| Location not found, or Pair not found (GPS tracks endpoint) | On a ticket system the track starts after the entry plaza, ends before the exit plaza, or both | Extend the track so it covers both the entry and the exit; on a live feed, start capture before the vehicle enters the toll system |
| Input or routing error | Malformed polyline, points out of order, missing timestamps, a path that cannot be routed | Validate the encoding and the point order; each such request counts as one transaction, so validate before sending |
| A crossing you do not expect | A point placed on a toll road beside the road driven (urban canyon, parallel roads, interchange) | GPS tracks endpoint, higher ping rate at interchanges; check the matched route in the response |
| Rate different from the statement | Vehicle parameters on the request do not match the unit; or the crossing time fell in a different rate window than the timestamp sent | Send the unit's real class, axles and weight; send per-point times on the time-aware form |
Anything not covered: write to tolltally@mapup.ai with the request ID, the request body (without the key) and what you expected. Two articles walk through the two most common cases: debugging route polyline errors and debugging route upload errors.
8. Code examples
| Example | What it shows |
|---|---|
| Tolls for Google Maps routes | Directions API to TollTally polyline: decode, merge and re-encode step polylines, send with vehicle and departure time |
| Tolls for HERE routes | Same flow on a HERE route |
| Tolls for TomTom routes | Same flow on a TomTom route |
| GPS tracks CSV upload | Synchronous and asynchronous GPS tracks runs with sample tracks |
| Request and response examples | Request bodies and responses per endpoint: complete polyline (02) and GPS tracks (03) |
Further reading: any mapping service in, tolls out; time-aware polyline endpoints; polyline endpoint pitfalls; how the map matching works.
9. Running it inside your own cloud
For very high volumes or data-residency requirements the same engines ship as a customer-hosted SDK: signed container images deployed with Terraform inside your own cloud account, with toll data and map updates delivered as encrypted deltas. Trip inputs stay inside your boundary. Technical integration is measured in days; you run the supplied test cases and approve go-live. Setup and operations are documented in the SDK guides: API guide, deployment, testing, security, metrics and troubleshooting. Contact tolltally@mapup.ai to scope it.