Skip to main content

Overview

Important

Directions API is only available in particular deployment options.

Directions API allows you to build a route from point A to point B.

Directions API supports the following types of routes:

  • a fastest car route considering current or statistical traffic data
  • a shortest car route in distance
  • a car route avoiding certain types of roads, like toll roads or dirt roads
  • a car route that includes public transport lanes (a taxi route)
  • a pedestrian route including crosswalks and avoiding obstacles
  • a pedestrian route inside buildings with floor plans
  • a bicycle route including pedestrian crossings and optionally avoiding stairways, overpasses, underpasses, and highways
  • a route with intermediate points (up to 10, including start and end point)

For each route, Directions API can additionally return the following information:

Request example​

Note

Examples below are for the deprecated Directions API. If you have switched to Routing API, refer to the corresponding documentation.

To calculate a route, send a POST request to the /carrouting/6.0.0/global endpoint. Specify your API key as the key parameter in the query string.

https://routing.api.2gis.com/carrouting/6.0.0/global?key=API_KEY

Coordinates for the route and other parameters must be sent as a JSON string in the request body.

For example, to build a car route from point A to point B considering the current traffic condition, you can send a request similar to the following:

curl --request POST \
 --url 'https://routing.api.2gis.com/carrouting/6.0.0/global?key=API_KEY' \
 --header 'Content-Type: application/json' \
 --data '{
   "locale": "en",
   "points": [
       {
           "type": "walking",
           "x": 82.93057,
           "y": 54.943207
       },
       {
           "type": "walking",
           "x": 82.945039,
           "y": 55.033879
       }
   ]
}'

The points parameter is an array of route points (x is the longitude of a point; y is the latitude of a point). The first element of the array is the starting point.

Response example​

The response will return an object containing the information about the calculated route: route length in meters (total_distance), travel time in seconds (total_duration), a list of maneuvers (maneuvers), and other fields. You can find information about each field in API Reference.

{
    "query": {
        "points": [
            {
                "type": "walking",
                "x": 82.93057,
                "y": 54.943207
            },
            {
                "type": "walking",
                "x": 82.945039,
                "y": 55.033879
            }
        ]
    },
    "result": [
        {
            "algorithm": "with traffic jams",
            "begin_pedestrian_path": {...},
            "end_pedestrian_path": {...},
            "filter_road_types": [...],
            "id": "1805336109018823561",
            "maneuvers": [...],
            "route_id": "...",
            "total_distance": 15153,
            "total_duration": 2204,
            "type": "carrouting",
            "ui_total_distance": {},
            "ui_total_duration": "36 min",
            "waypoints": [...]
        }
    ],
    "type": "result"
}

Deployment options​

  • Cloud-based: Directions API methods are not available. To send routing requests to 2GIS public endpoints, use Routing API.

    For building routes through mobile SDK, special Directions API methods are used. Access to these methods is provided when you obtain an access key for mobile SDK.

  • On-Premise: all current Directions API methods are available when the 2GIS API platform is installed in a private network. For more information, see the API platform for server.

Methods labeled as deprecated are not supported in any deployment options.