Connect with our team:
Join with Slack Connect:
Open Slack
Join with Telegram:
Open Telegram
Or reach us here:
E-mail, contact form, phone

Traffic Matrix API (v1)

Authentication

Bearer

All requests to the API must be authorized with user's API key. The API uses HTTP Bearer authorization scheme, and must be provided in HTTP headers in one of the following formats:

Authorization: Bearer <your API key>
Authorization: Apikey <your API key>

Matrix operations

API endpoints for asynchronous request of origin-destination matrix

Submit matrix request

Endpoint:HTTP post /api/matrix/v1/add
Authorization:
Body:application/json
oneOf<OriginsDestinationsRequest | LegacyOriginsRequest>
oneOf
  • OriginsDestinationsRequest
  • LegacyOriginsRequest
origins
required
GeographicLocations, array< object > >= 1 items

Origin locations

destinations
GeographicLocations, array< object > >= 1 items

Destination locations. When omitted, destinations are equal to origins.

provider
required
OdmatrixProvider, oneOf<HereCostMatrix | OsrmCostMatrix>

Data provider

Responses

Status:HTTP 200

Task has been queued for execution.

Response headers:
Location
string

URL to poll for task completion.

Response body:application/json
object
id
required
string

Task unique id

status
required
string
enum: created | started | completed | cancelled

Current status of an asynchronous task.

Status values:

  • created - request JSON has been parsed and validated, and task was created;
  • started - task execution has started;
  • completed - task execution has been completed;
  • cancelled - task execution has been cancelled due to timeout or error.

The status of a task will change only in the following ways during execution:

  • created ⟶ cancelled;
  • created ⟶ started ⟶ (completed or cancelled).
status_log
required
StatusLogEntry, array< object >

Task status log

Status:HTTP 400

Invalid or empty JSON in POST request body

Status:HTTP 401

Request is not authorized

Status:HTTP 500

Server error during request processing

Receive result

Endpoint:HTTP get /api/matrix/v1/result/{id}
Authorization:
Path parameters:
id
required
string <byte> 22 characters

Task ID to query

Responses

Status:HTTP 200

Task execution completed

Response body:application/json
oneOf<ResultResponse | ErrorResponse>
oneOf
  • ResultResponse
  • ErrorResponse
result
required
OdmatrixOutput, oneOf<GcsCostMatrixReference | UrlCostMatrixReference | JsonCostMatrix | CompositeCostMatrix>
id
required
string

Task unique id

status
required
string
enum: created | started | completed | cancelled

Current status of an asynchronous task.

Status values:

  • created - request JSON has been parsed and validated, and task was created;
  • started - task execution has started;
  • completed - task execution has been completed;
  • cancelled - task execution has been cancelled due to timeout or error.

The status of a task will change only in the following ways during execution:

  • created ⟶ cancelled;
  • created ⟶ started ⟶ (completed or cancelled).
status_log
required
StatusLogEntry, array< object >

Task status log

Status:HTTP 202

Task is executing

Status:HTTP 401

Request is not authorized

Status:HTTP 404

Requested task is not found.

Status:HTTP 500

Server error during request processing

Service operations

API endpoints for development, monitoring and maintenance

OpenAPI 3.0 schema

Responses

Status:HTTP 200

OK

Response body:application/json
object

Status and availability

Provides information in service avialability and status

Endpoint:HTTP get /api/matrix/v1/ping

Responses

Status:HTTP 200

Service is available

Response body:application/json
object
status
string
value: OK

Documentation

API documentation in HTML format

Endpoint:HTTP get /api/matrix/v1/doc

Responses

Status:HTTP 200

OK

Response body:text/html
string
string
(c) 2023 Routinghub LLC