Skip to main content

Getting started

Getting an access key​

To work with the API of the service, you need to get an access key:

  1. Sign in to the Platform Manager.
  2. Create a demo key or purchase a subscription for using API. For details on service prices, see the Tariffs section.

To work with access keys, you can use the Platform Manager: for details, see the account documentation.

The next steps are determined by the selected Distance Matrix API mode.

Synchronous mode​

Use the synchronous mode for calculating requests that contain up to 25 starting or ending points.

Request example​

To get the information about a route, send a POST request to the /get_dist_matrix endpoint. Specify your API key as the key parameter in the query string and the required API version as the version parameter (2.0 by default):

https://routing.api.2gis.com/get_dist_matrix?key=API_KEY&version=2.0

Pass coordinates for the route and other parameters as a JSON string in the request body.

You can specify several starting and end points in the request body. For each specified starting point, a route is built to each specified end point.

For example, to build routes for two starting points and two end points, send the following request:

curl --request POST \
 --url 'https://routing.api.2gis.com/get_dist_matrix?key=API_KEY&version=2.0' \
 --header 'Content-Type: application/json' \
 --data '{
    "points": [
        {
            "lat": 54.99770587584445,
            "lon": 82.79502868652345
        },
        {
            "lat": 54.99928130973027,
            "lon": 82.92137145996095
        },
        {
            "lat": 55.04533538802211,
            "lon": 82.98179626464844
        },
        {
            "lat": 55.072470687600536,
            "lon": 83.04634094238281
        }
    ],
    "sources": [0, 1],
    "targets": [2, 3]
}'

The points parameter is an array of route points. The sources and targets parameters are arrays of indices that determine which points of the points array are starting and end points, respectively.

Important

This query works with the following restrictions:

  • The number of points in the sources array or in the targets array does not exceed 25.
  • The distance between points does not exceed 2000 km in a straight line.

If at least one of these restrictions is not satisfied, the request will return an error. To make requests with this input data, use the asynchronous method.

Response example​

For each pair of starting and ending points, the request will return route information including the route length in meters (distance) and travel time in seconds (duration). The point indices from the points array will be specified in the source_id and target_id fields. If a route could not be built for a particular pair of points, the status field will contain the string "FAIL".

More detailed information about response fields can be found in API Reference.

{
    "generation_time": 3349,
    "routes": [
        {
            "distance": 11287,
            "duration": 1319,
            "source_id": 0,
            "status": "OK",
            "target_id": 2
        },
        {
            "distance": 3839,
            "duration": 603,
            "source_id": 0,
            "status": "OK",
            "target_id": 3
        },
        {
            "distance": 12245,
            "duration": 1094,
            "source_id": 1,
            "status": "OK",
            "target_id": 2
        },
        {
            "distance": 11418,
            "duration": 931,
            "source_id": 1,
            "status": "OK",
            "target_id": 3
        }
    ]
}

Asynchronous mode​

If you need to use the asynchronous mode, write an email to info@urbi.ae.

When using more than 25 starting or ending points, use the asynchronous approach:

  1. Create a task to calculate the travel time and distance between points.
  2. Periodically check the status of the task until the calculation is complete.
  3. Get the calculation results once the task is complete.

Creating a task​

To create a task, send a POST request to the /async_matrix/create_task/get_dist_matrix endpoint. Specify your API key as the key parameter in the query string and the required API version as the version parameter (2.0 by default):

https://routing.api.2gis.com/async_matrix/create_task/get_dist_matrix?key=API_KEY&version=2.0

Request example​

Pass coordinates for the route and other parameters as a JSON string in the request body. For example, to build routes for two starting points and two end points, send the following request:

curl --request POST \
 --url 'https://routing.api.2gis.com/async_matrix/create_task/get_dist_matrix?key=API_KEY&version=2.0' \
 --header 'Content-Type: application/json' \
 --data '{
    "points": [
        {
            "lat": 54.99770587584445,
            "lon": 82.79502868652345
        },
        {
            "lat": 54.99928130973027,
            "lon": 82.92137145996095
        },
        {
            "lat": 55.04533538802211,
            "lon": 82.98179626464844
        },
        {
            "lat": 55.072470687600536,
            "lon": 83.04634094238281
        }
    ],
    "sources": [0, 1],
    "targets": [2, 3]
}'

The request will return information about the created task, including the task identifier (task_id), which is used to check the task status:

{
    "task_id": "TASK_ID",
    "status ": "TASK_CREATED"
}

Checking task status​

To check the status of the task, send a GET request to the /async_matrix/result/get_dist_matrix/{task_id}?key=API_KEY endpoint. Specify two parameters in the query string:

  • task_id - task ID
  • key - your API key

Request example​

curl --request GET \
  --url    'https://routing.api.2gis.com/async_matrix/result/get_dist_matrix/TASK_ID?key=API_KEY' \
  --header 'accept: application/json'

Getting task results​

The request will return the current status of the task and a link to the solution file if the task has been completed successfully. The structure of the solution file is identical to the structure of a response to a synchronous request:

Response example​

{
    // Task identifier.
    "task_id": "TASK_ID",
    // Task status.
    "status": "TASK_DONE",
    // Status code.
    "code": 200,
    // Additional information about the task status.
    "message": "start_time_ms=16516816106601123 calc_time_ms=14419 attract_time=4 build_time=28 points_count=3 source_count=1 target_count=2",
    // Link to the solution file.
    "result_link": "http://storage_host:port/dm/TASK_ID.response.json"
}

Tasks can have the following statuses:

  • TASK_CREATED - task has been created.
  • TASK_IN_QUEUE - task is in a queue, waiting to be processed.
  • TASK_IN_PROGRESS - task is being processed.
  • TASK_DONE - task was completed.
  • TASK_CANCELED - task was cancelled (see the message field for more details).

Response format​

By default, responses are in the JSON format. To get a response in the Protocol Buffers format:

  • When working in the synchronous mode, specify the response_format=protobuf parameter in the query string:

    https://routing.api.2gis.com/get_dist_matrix?key=API_KEY&version=2.0&response_format=protobuf

  • When working in the asynchronous mode, specify the response_format=protobuf parameter when creating a task:

    https://routing.api.2gis.com/async_matrix/create_task/get_dist_matrix?key=API_KEY&version=2.0&response_format=protobuf

A schema of the Protocol Buffers format is available at DistanceMatrix.proto.