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

Add matrix request

Endpoint:HTTP post /api/matrix/v1/add

Authorization:

BEARER

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 been started; `completed` - task execution has been completed; `cancelled` - task execution has been cancelled due to timeout or an 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

Add incremental matrix request

Queues new incremental origin-destination matrix request for processing. Returns created optimization task ID.

Endpoint:HTTP post /api/matrix/v1/add-incremental

Authorization:

BEARER

Body:application/json

object

new_origins required	GeographicLocations, array< object > >= 1 items New origin and destination locations to incrementally add to existing origin-destination matrix
prev_matrix required	WorkerNonGenCostMatrix, oneOf<GcsCostMatrixReference \| JsonCostMatrix \| CompositeCostMatrix> Previously generated origin-destination matrix. Note that new origins will be appeneded to origins of previously generated matrix.

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 been started; `completed` - task execution has been completed; `cancelled` - task execution has been cancelled due to timeout or an 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:

BEARER

Path parameters:

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 \| 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 been started; `completed` - task execution has been completed; `cancelled` - task execution has been cancelled due to timeout or an 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

Endpoint:HTTP get /api/matrix/v1/schemas/openapi.json

Responses

Status:HTTP 200

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

Response body:text/html

string