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.

• Authentication and API key
• API reference
• Pricing

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.

API URL

To use the Route Matrix API provided by Geoapify, you will need to make a POST request to the following URL: https://api.geoapify.com/v1/routematrix.

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.

HTTP POST https://api.geoapify.com/v1/routematrix

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.

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.

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

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

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:

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.

Pricing

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.