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:

Routing API Live Demo



Authenfication 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

  1. Register on Geoapify MyProjects page
  2. Create a new project.
  3. Go to the API Keys section. One API key is generated automatically. You can generate multiple API keys per project if required.
  4. Optionally, you can protect the API key by listing allowed IP addresses, HTTP referrers, origins, and CORS.
  5. Choose "Route Matrix API" and an API key to generate a URL and programming code.
  6. 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