About Route Matrix API
The Route Matrix API generates a time-distance matrix for the given source and target locations. The matrix can be used as input for route optimization and analytics tasks.
The API lets you get up to 1000 travel distances and time values at once. You can also do bigger time-distance matrices by combining several result matrices from different calls.
You can choose between different transportation or travel modes, including ones for passenger cars, delivery trucks, small motor vehicles, and pedestrians. Here is an API playground that helps to learn more about the API parameters, generate API requests, and explore the response:
Authentication and API key
To use the Route Matrix API, you'll need an API key. You can register and get a Route Matrix API Key for free without a credit card.
We offer a free plan, so there's no need to stress about cost. Start for free and upgrade to a paid plan when the needs of your project increase. For more information on our plans, visit the Pricing page.
How to get Geoapify API key
- Register on Geoapify MyProjects page
- Create a new project.
- Go to the API Keys section. One API key is generated automatically. You can generate multiple API keys per project if required.
- Optionally, you can protect the API key by listing allowed IP addresses, HTTP referrers, origins, and CORS.
- Choose "Route Matrix API" and an API key to generate a URL and programming code.
- Press the "Try" button to execute the API call and get the result object example.
API reference
The Route Matrix API works via HTTP POST requests. It takes a source and target destination as the request body.
API URL
POST https://api.geoapify.com/v1/routematrix
HEADERS 'Content-Type: application/json'
Request parameters
| Name | Description |
|---|---|
| apiKey | Your Geoapify API key |
Request body parameters
| Name | Description |
|---|---|
| mode | Transportation or travel mode. Possible values: "drive", "truck", "walk", "bicycle" |
| sources | List of from-waypoints |
| sources.location | Location represented as an array of coordinates: [longitude, latitude] |
| targets | List of to-waypoints |
| targets.location | Location represented as an array of coordinates: [longitude, latitude] |
Here is an example of the API call:
POST https://api.geoapify.com/v1/routematrix?apiKey=YOUR_API_KEY
Content-Type: application/json
{
"mode": "truck",
"sources": [
{ "location": [9.236501233317654, 47.79125886208948] },
{ "location": [9.29243400499115, 47.75443519732946] },
{ "location": [9.402016578066196, 47.719889328346085] },
{ "location": [9.69195380266035, 47.63303975785408] },
...
],
"targets": [
{ "location": [9.049297670979968, 47.572236047449366] },
{ "location": [9.204539649503204, 47.56068305549502] },
{ "location": [9.33923489557526, 47.51830028304724] },
...
]
}
Response Object
| Name | Description |
|---|---|
| sources | List of from-waypoints with original and matched to existing roads locations |
| sources.original_location | Original location represented as an array of coordinates: [longitude, latitude] |
| sources.location | Matched location represented as an array of coordinates: [longitude, latitude] |
| targets | List of to-waypoints with original and matched to existing roads locations |
| targets.original_location | Original location represented as an array of coordinates: [longitude, latitude] |
| targets.location | Matched location represented as an array of coordinates: [longitude, latitude] |
| sources_to_targets | The time-distance matrix |
| sources_to_targets.distance | Distance in meters between source waypoint and target waypoint |
| sources_to_targets.time | Travel time in seconds between source waypoint and target waypoint |
| sources_to_targets.source_index | Index of the source waypoint |
| sources_to_targets.target_index | Index of the target waypoint |
Here is an example of the response object:
{
"sources": [
{
"original_location": [-0.26638280549582305, 51.65957511654639], "location": [-0.266383, 51.659575]
},
{
"original_location": [0.21039127548920078, 51.59230741451023], "location": [0.210391, 51.592307]
},
{
"original_location": [0.42710676684589544, 51.25899230131458], "location": [0.427107, 51.258992]
}
],
"targets": [
{
"original_location": [-0.4830982968514945, 51.364354146777686], "location": [-0.483098, 51.364354]
},
{
"original_location": [-0.47105854733172237, 51.221304423124735], "location": [-0.471059, 51.221304]
},
{
"original_location": [-0.07133886327437722, 51.1669796234099], "location": [-0.071339, 51.16698]
}
],
"sources_to_targets": [
[
{ "distance": 67406, "time": 2366, "source_index": 0, "target_index": 0 },
{ "distance": 87230, "time": 3182, "source_index": 0, "target_index": 1 },
{ "distance": 111531, "time": 3921, "source_index": 0, "target_index": 2 }
], [ { "distance": 103070, "time": 3641, "source_index": 1, "target_index": 0},
{ "distance": 106858, "time": 3945, "source_index": 1, "target_index": 1},
{ "distance": 73479, "time": 2772, "source_index": 1, "target_index": 2}
], [ { "distance": 82952, "time": 3013, "source_index": 2, "target_index": 0 },
{ "distance": 86740, "time": 3317, "source_index": 2, "target_index": 1 },
{ "distance": 53361, "time": 2144, "source_index": 2, "target_index": 2 }
]
]
}
Pricing
To make Geoapify's pricing plans understandable, we've introduced a "credit" system, which accumulates to daily use.
Geoapify offers Pricing Plans, starting from a Free plan to advanced paid plans. 3000 credits/day is included with our Free plan. Upgrade at any time as your business grows.
| Rule | Cost in credits | Example |
|---|---|---|
| Number of locations <= 10 | SOURCE_LOCATIONS * TARGET_LOCATIONS credits |
9 start locations and 8 end locations are counted as 9 * 8 = 72 credits |
| Number of locations >= 10 | Max( SOURCE_LOCATIONS, TARGET_LOCATIONS ) * Min( SOURCE_LOCATIONS, TARGET_LOCATIONS, 10 ) credits |
30 start locations and 45 end locations are counted as Max(30, 45) * Min(30, 45, 10) = 45 * 10 = 450 credits |