Route Matrix API

Welcome to the Route Matrix API documentation! Our API generates time-distance matrices for the specified source and target locations, which can be used for route optimization and analytics tasks.

The Route Matrix API allows you to obtain up to 1000 travel distances and time values at once. You can also generate larger matrices by combining several result matrices from different calls. In addition, you can choose from a range of transportation or travel modes, including options for passenger cars, delivery trucks, small motor vehicles, and pedestrians.

To help you get started, we offer an API playground that provides more information on the API parameters and the ability to generate API requests and explore responses. Please refer to the API documentation below for more details on how to use our Route Matrix API.

Routing API Live Demo

Authentication and API key

To use the Route Matrix API, you'll first need an API key. Signing up for an API key is simple and won't cost you time. Moreover, it's free, and you don't even need to provide a credit card.

We've designed a free plan that's perfect for getting started with the Route Matrix API, and it's easy to upgrade to a paid plan as your needs grow. Check out our dedicated Pricing page for more information on our pricing and plans.

Getting the Geoapify API key

  1. Head over to the Geoapify MyProjects page and register for an account.
  2. Create a new project.
  3. Navigate to the API Keys section, where one API key is automatically generated for you. If you need multiple API keys for your project, you can generate them here as well.
  4. If you'd like to add an extra layer of security, you can protect your API key by specifying allowed IP addresses, HTTP referrers, origins, and CORS.
  5. Select the "Route Matrix API" and your desired API key, and you can generate a URL and programming code.
  6. Click the "Try" button to execute the API call and see an example of the result object.

API reference

Our Map Matching API operates through a simple POST request that lets you send up to 1000 location points directly in the request body.


To use the Route Matrix API provided by Geoapify, you will need to make a POST request to the following URL:

To ensure the request is handled correctly, you'll also need to include a Content-Type header. This header should be set to application/json.


HEADERS 'Content-Type: application/json'

Request parameters

When making a request to the Geoapify Route Matrix API, there's only one URL parameter that you need to provide: your API key. This key is essential for authenticating your request and ensuring the Geoapify server can process your API call.

Name Description
apiKey Your Geoapify API key

Other parameters you'll need to include are provided in the request body rather than the URL.

Request body parameters

You'll need to include API parameters in the request body. These parameters allow you to specify the source and target location and any additional route options you want to consider.

Name Format Description Example
mode See the Routing API Travel Modes table Travel or transportation mode. The Routing API Travel Modes table contains detailed information about possible travel modes and vehicle types. mode: "drive"
sources Array List of from-waypoints [{ "location": [ 11.757314, 48.291153]},{"location": [12.130849, 48.076897]}, {"location": [12.545583, 47.823032]}]
sources.location [number, number] Location represented as an array of coordinates: [longitude, latitude] [12.130849, 48.076897]
targets Array List of to-waypoints [{ "location": [ 11.757314, 48.291153]},{"location": [12.130849, 48.076897]}, {"location": [12.545583, 47.823032]}]
targets.location [number, number] Location represented as an array of coordinates: [longitude, latitude] [12.130849, 48.076897]
avoid Array List of road types or locations to be avoided by the router. Check the Routing API Avoid options for more details. "avoid": [{"type": "tolls"},{"type": "highways"},{"type": "locations", "values": [{"lon": 12.1830350,"lat": 47.981384}]}]
traffic Enum: free_flow, approximated The traffic model for route calculation, the default value is free_flow, meaning that the route is calculated optimistically with no traffic influence. The approximated traffic model decreases speed for potentially heavy-loaded roads. The traffic model is only used for motorized vehicles modes, such as drive, truck, etc. traffic: "approximated"
type Enum: balanced, short, less_maneuvers Route type, the default value is balanced. Check The Routing API Route Type for more information. type: "short"
max_speed number The maximum speed that a vehicle can travel. This applies to driving mode, all truck modes, and bus modes. The max_speed should be specified within the range of 10 to 252 KPH (6.5 - 155 MPH). For trucks, the standard setting is 90 kilometers per hour (KPH), while for automobiles and buses, it's set at 140 KPH by default. max_speed: 80
units Enum: metric, imperial Distance units for the calculated route, the default valie is metric. units: "imperial"

Here's an example request that includes the necessary parameters in the request body:

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] },

In this example, you'll need to replace YOUR_API_KEY with your actual Geoapify API key.

We've created an API Playground tool to make it easier to generate request examples with different API parameters. This tool allows you to experiment with different options and settings, generating code examples and response objects in real-time. With the API Playground, you can quickly and easily explore the full range of features and capabilities offered by the Geoapify Route Matrix API.

Response Object

The API response includes a time-distance matrix containing the travel distances and times between your specified source and destination locations. As well as additional information about the original and mapped locations:

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 }

This example response provides the time and distance values in meters and seconds, respectively. In addition, the "original_location" of sources and destinations indicates the provided location, and the "location" field shows the corresponding locations on the nearest road.


Geoapify's pricing plans are designed to be transparent and easy to understand. We have introduced a "credit" system that accumulates to daily usage to achieve this.

Our Pricing Plans include a free plan with 3000 credits per day. As your business grows, you can upgrade to one of our advanced paid plans anytime.

The number of credits counted per API call is determined by the number of source and target locations provided in the input parameters. To calculate the number of requests, we use the following formula:

Max(number_of_sources, number_of_targets) * Min(number_of_sources, number_of_targets, 10)

  • number_of_sources: the number of source locations provided in the input parameters.
  • number_of_targets: the number of target locations provided in the input parameters.
  • Max(number_of_sources, number_of_targets): this calculates the maximum number of locations provided. For example, if you provide 5 source locations and 8 target locations, the maximum number of locations is 8.
  • Min(number_of_sources, number_of_targets, 10): this calculates the minimum number of locations provided or a maximum of 10. For example, if you provide 50 source locations and 20 target locations, the minimum number of locations is 20. However, we calculate it as 10 to avoid high costs and offer the best pricing.

Here are some examples of how to calculate the number of credits for an API request based on the formula:

  • If you provide 3 source locations and 4 target locations, the formula will be Max(3, 4) * Min(3, 4, 10) = 12, so 12 credits will be counted for this API call.
  • If you provide 10 source locations and 5 target locations, the formula will be Max(10, 5) * Min(10, 5, 10) = 50, so 50 credits will be counted for this API call.
  • If you provide 15 source locations and 12 target locations, the formula will be Max(15, 12) * Min(15, 10, 10) = 120, so 120 credits will be counted for this API call.

Please note that the maximum number of source and target locations that can be provided in a single API call is 1000, and any values exceeding this limit will need to be split into multiple requests.