Endpoints

Routing

Calculate the fastest route between two points, with distance, estimated travel time and a GeoJSON line.

Request

GET/v1/route

Requires an API key in the Authorization header.

Parameters

Parameters
Name	Type	Description
`origin`required	`string`	Start point as `longitude,latitude` (GeoJSON order), for example `106.9177,47.9184`.
`destination`required	`string`	End point as `longitude,latitude`, for example `106.9057,47.9220`.
`mode`optional	`string`	`driving` (default) or `walking`.

Longitude first

origin and destination put longitude before latitude, like GeoJSON. Swapping them usually gives a 400 error (latitude out of range) or a point in the wrong place.

Example

curl -G "https://developers.ubhub.mn/v1/route" \
  -d origin=106.9177,47.9184 \
  -d destination=106.9057,47.9220 \
  -d mode=driving \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK

{
  "route": {
    "distance_meters": 4200,
    "duration_seconds": 620,
    "geometry": {
      "type": "LineString",
      "coordinates": [
        [
          106.9177,
          47.9184
        ],
        [
          106.9176,
          47.918
        ],
        [
          106.911,
          47.918
        ],
        [
          106.9057,
          47.918
        ],
        [
          106.9057,
          47.922
        ]
      ]
    }
  },
  "mode": "driving",
  "waypoints": [
    {
      "input": {
        "latitude": 47.9184,
        "longitude": 106.9177
      },
      "location": {
        "latitude": 47.9184,
        "longitude": 106.9176
      },
      "snap_distance_meters": 7.6,
      "name": "Chingis Avenue"
    },
    {
      "input": {
        "latitude": 47.922,
        "longitude": 106.9057
      },
      "location": {
        "latitude": 47.922,
        "longitude": 106.9057
      },
      "snap_distance_meters": 0.4,
      "name": "Seoul Street"
    }
  ]
}

Response fields
Field	Type	Description
`route.distance_meters`	`number`	Length of the route in meters.
`route.duration_seconds`	`number`	Estimated travel time in seconds.
`route.geometry`	`LineString`	GeoJSON LineString. `coordinates` are `[longitude, latitude]` pairs from origin to destination.
`mode`	`string`	The travel mode used.
`waypoints`	`array`	Two entries, origin then destination, describing where each point joined the road network.
`waypoints[].input`	`object`	The coordinate you sent.
`waypoints[].location`	`object`	The point on the road network used instead.
`waypoints[].snap_distance_meters`	`number`	Distance between input and location.
`waypoints[].name`	`string \| null`	Name of the road at the snapped point.

Travel modes

Travel modes
Mode	Behavior
`driving`	Uses roads open to cars, respects one-way streets, and estimates time from road speeds.
`walking`	Uses streets and footpaths, ignores one-way rules, avoids motorways, at about 5 km/h.

More modes may be added to /v1 later; adding a mode is not a breaking change.

Snapping to roads

Origin and destination are moved to the nearest road the chosen mode can use. waypoints shows where.
If no usable road is close enough to a point, the API answers 404 NOT_FOUND with details.reason set to origin_not_on_network or destination_not_on_network.
Origin and destination must be within the maximum route distance for this deployment (100 km by default); otherwise you get 400 INVALID_REQUEST on destination.

Errors

404 Not Found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "No driving route connects the origin and the destination.",
    "details": {
      "reason": "no_path"
    }
  }
}

Errors
Status	Code	Meaning
400	`INVALID_REQUEST`	A parameter is missing or invalid. `details.field` names it. Also used with status 405 for a wrong HTTP method and 413 for an oversized body.
401	`INVALID_API_KEY`	The Authorization header is missing or malformed, the key does not exist, or it has expired (`details.reason` is `expired`).
403	`API_KEY_REVOKED`	The key was revoked in the dashboard.
403	`ENDPOINT_NOT_ALLOWED`	The key is not allowed to call this endpoint. Each key is limited to the endpoints chosen when it was created; `details.allowed_endpoints` lists them.
404	`NOT_FOUND`	Nothing was found: no address near the point (reverse geocoding), no route or no road near a waypoint (routing, `details.reason` explains), or an unknown path.
408	`REQUEST_TIMEOUT`	The data service behind the API did not answer in time.
429	`RATE_LIMIT_EXCEEDED`	The key used up its requests for the current one-minute window.
500	`INTERNAL_ERROR`	An unexpected error in the API.
502	`UPSTREAM_ERROR`	The data service behind the API failed or returned an invalid answer.
503	`SERVICE_UNAVAILABLE`	The service is temporarily unavailable, for example while a data source is being configured or loaded.

See Errors for how to handle each code.

Try it

GET/v1/routePlayground

Request

GET /v1/route?origin=106.9177%2C47.9184&destination=106.9057%2C47.9220&mode=driving

curl "https://developers.ubhub.mn/v1/route?origin=106.9177%2C47.9184&destination=106.9057%2C47.9220&mode=driving" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

Send a request to see the response.