Request → Transaction¶
This page explains how Map API requests are counted as transactions in our billing/usage system. Use the examples and formulas below to estimate your transaction consumption.
Note: Routing transactions are calculated using integer division on the number of waypoints. Other APIs are typically 1 request = 1 transaction.
What is a "request" and what is a "transaction"?¶
Request:¶
- A request is an HTTP call from your application to a Vietmap API endpoint. Each request includes the endpoint path, HTTP method, parameters (query/body), and your API key. Examples of requests: calling
/geocodeto get coordinates for an address, or/routeto compute a route. - In short: a request = one API call made by your app.
Transaction:¶
- A transaction is the billing/usage unit Vietmap uses to measure how much API processing your requests consume. Transactions are how we count usage and used for quotas and billing.
- Important: a request does not always equal one transaction. For some APIs a single request may count as multiple transactions because the request requires extra processing or covers multiple units of work (for example, Routing or Matrix endpoints).
Examples:¶
- A simple geocoding request typically consumes 1 transaction.
- A routing request with many waypoints may consume multiple transactions according to the formula shown above.
Include these definitions when estimating usage so you convert expected request volumes into the correct transaction counts.
Summary table¶
| API | Description | Requests | Transactions |
|---|---|---|---|
| Tile map | Tile images for map rendering | 25 | 1 |
| Geocoding (Search) | Convert address/place to coordinates | 1 | 1 |
| Reverse | Convert coordinates to address/place | 1 | 1 |
| Autocomplete | Fast suggestions for address/place keywords | 1 | 1 |
| Routing | Route for multi-stop journeys and different vehicle types | 1 | 1 × (⌊points/5⌋ + 1) |
| Matrix | Travel time/distance matrix between n origins and m destinations | 1 | n × m |
| TSP (Traveling Salesperson Problem) | Route optimization for one vehicle across m stops | 1 | m |
| VRP (Vehicle Routing Problem) | Route optimization for n vehicles across m stops | 1 | n × m |
| Isochrone | Reachable area by mode and travel time | 1 | 1 |
Rules and formulas¶
Simple 1:1 APIs¶
These APIs consume 1 transaction per request. Examples include Geocoding, Reverse, Autocomplete, Place, Isochrone APIs.
Tile map formula¶
Tile map requests are counted as follows: 1 transaction = 25 tile requests. For example, if your application requests 100 map tiles, it will consume 4 transactions (100 / 25 = 4).
Our SDKs will automatically request tiles as needed based on the map view, zoom level, and user interactions. It needs more than 1 tile request to render a map view, so tile requests are grouped into transactions for billing efficiency.
The SDKs has built-in caching mechanisms to minimize redundant tile requests, which helps reduce transaction consumption. One tile request is counted only once per unique tile URL.
Routing formula¶
Routing transaction calculation uses the following formula:
transactions = 1 × (⌊points / 5⌋ + 1)
where points is the number of waypoints (stops) in the route. The formula assigns one base transaction, and then adds one extra transaction for each full group of 5 points.
Examples:
- 5 points → ⌊5/5⌋ + 1 = 1 + 1 = 2 transactions
- 10 points → ⌊10/5⌋ + 1 = 2 + 1 = 3 transactions
- 12 points → ⌊12/5⌋ + 1 = 2 + 1 = 3 transactions
Matrix formula¶
Matrix transactions = n × m where n = number of origins (vehicles) and m = number of destinations (points, like customers,...).
Examples:
- 2 vehicles × 5 points = 10 transactions
- 3 vehicles × 8 points = 24 transactions
TSP and VRP¶
- TSP: transactions = number of stops
m(for a single vehicle optimization) - VRP: transactions =
n × m(number of vehicles × number of stops)
Examples¶
- Single routing call with 8 points:
transactions = ⌊8/5⌋ + 1 = 1 + 1 = 2 transactions
- Matrix call for 4 origins and 10 destinations:
transactions = 4 × 10 = 40 transactions
Notes and recommendations¶
- We provide a Pricing Converter tool to help you convert between budget (VNĐ) and estimated transactions.
- Always review per-API documentation for any special-case rules that might affect transaction calculation.
- When estimating costs, aggregate expected daily or monthly requests and apply the formulas above to get transaction counts.
- For public or client-distributed keys, apply IP / domain restrictions in the Console to prevent unauthorized usage.
