Distance Matrix

When using and/or manipulating trips, either through REST services or through planning algorithms/jobs, distance matrices can be used. The distance matrix service computes the travel time and distances between each stop in a trip, and uses these values for displaying and calculations. This often gives a more realistic result than when using the Haversine distances and approximated travel times (which is the default).

Note that using distance matrices comes with an additional fee, and requires 'credits' to function.

The UseDistanceMatrix preference indicates whether to use the distance matrix service.

UseDistanceMatrix
Type	Default Value	Example
Boolean	false	true

Depending on the underlying matrix provider used, specific properties must be provided. Two providers are supported: OSRM and Google Routes API.

OSRM provider

The distancematrix.osrm.baseUrl preference indicates the URL of the OSRM table service that the OMD Distance Matrix service should call.

distancematrix.osrm.baseUrl
Type	Default Value	Example
String	Undefined	https://router.project-osrm.org/table/v1/driving/

The distancematrix.osrm.clientSecret indicates the secret/token that will be passed to the OSRM service in a Authorization: Bearer header.

distancematrix.osrm.clientSecret
Type	Default Value	Example
String	Undefined	`<text>`

Google Routes API provider

The Google provider calls the Google Routes API (computeRouteMatrix endpoint) and requires a valid Google Cloud API key with the Routes API enabled.

The maximum matrix size for Google is 25 × 25 (625 elements per request). Larger requests are automatically partitioned.

The distancematrix.google.apiKey is the Google Cloud API key used to authenticate requests.

distancematrix.google.apiKey
Type	Default Value	Example
String	Undefined	`AIzaSy...`

Routing preferences

The routingPreferences object in the request payload allows controlling which road types are avoided. All flags default to false.

Field	Type	Default	Description
`avoidFerries`	Boolean	`false`	Avoid ferry routes.
`avoidHighways`	Boolean	`false`	Avoid highways/motorways.
`avoidTolls`	Boolean	`false`	Avoid toll roads.

Google request example

{
  "config": {
    "provider": "GOOGLE",
    "trafficInfoMode": "NONE",
    "configurationId": 12345,
    "routingPreferences": {
      "avoidFerries": false,
      "avoidHighways": false,
      "avoidTolls": true
    },
    "properties": {
      "apiKey": "AIzaSy..."
    }
  },
  "origins": [
    { "location": { "latitude": 48.3705, "longitude": 10.8977 } },
    { "location": { "latitude": 48.4075, "longitude": 10.0069 } }
  ],
  "destinations": [
    { "location": { "latitude": 48.3705, "longitude": 10.8977 } },
    { "location": { "latitude": 48.4135, "longitude": 10.0116 } }
  ]
}

Notes on the Google provider

The travel mode is always DRIVE; pedestrian and cycling modes are not supported.
Traffic-aware routing (STATISTICAL, ACTUAL) is accepted in the request but currently maps to TRAFFIC_UNAWARE internally. Future versions may honour this setting.
When a route between two points cannot be found (e.g. the destination is on an island without road access), the element is returned with status: ERROR and a 404 error detail rather than being silently omitted.

REST API

The distance matrix service exposes a REST endpoint that can also be called directly, independently of any planning operation.

Endpoint: POST /distancematrix

Query parameters:

Parameter	Type	Default	Description
`async`	Boolean	`false`	When `true`, the request is processed asynchronously.
`useCache`	Boolean	`true`	When `true`, previously computed results are read from and stored in the cache.

Request structure

{
  "config": {
    "provider": "OSRM",
    "trafficInfoMode": "NONE",
    "configurationId": 12345,
    "properties": {
      "serverUrl": "https://osrm.optimizemyday.com/table/v1/driving/",
      "authorizationHeader": "Bearer <token>"
    }
  },
  "origins": [
    { "location": { "latitude": 48.3705, "longitude": 10.8977 } },
    { "location": { "latitude": 48.4075, "longitude": 10.0069 } }
  ],
  "destinations": [
    { "location": { "latitude": 48.3705, "longitude": 10.8977 } },
    { "location": { "latitude": 48.4135, "longitude": 10.0116 } },
    { "location": { "latitude": 48.3800, "longitude": 10.9500 } }
  ]
}

Field descriptions:

Field	Type	Description
`config.provider`	String	Routing provider. Supported values: `OSRM`, `GOOGLE`.
`config.trafficInfoMode`	String	Traffic mode. One of `NONE`, `STATISTICAL`, `ACTUAL`.
`config.configurationId`	Integer	OMD configuration identifier; used to scope the cache.
`config.properties.serverUrl`	String	Base URL of the OSRM table service.
`config.properties.authorizationHeader`	String	Full `Authorization` header value forwarded to OSRM.
`origins`	Array	List of origin locations (latitude/longitude).
`destinations`	Array	List of destination locations (latitude/longitude).

Response structure

The response contains one element per origin–destination pair. The originIndex and destinationIndex fields refer to the zero-based positions in the request origins and destinations arrays respectively.

time is expressed in seconds. distance is expressed in meters.

{
  "status": "OK",
  "data": [
    {
      "status": "OK",
      "timeDistance": {
        "originIndex": 0,
        "destinationIndex": 0,
        "time": 0,
        "distance": 0
      }
    },
    {
      "status": "OK",
      "timeDistance": {
        "originIndex": 0,
        "destinationIndex": 1,
        "time": 2847,
        "distance": 41230
      }
    },
    {
      "status": "OK",
      "timeDistance": {
        "originIndex": 0,
        "destinationIndex": 2,
        "time": 612,
        "distance": 8950
      }
    },
    {
      "status": "OK",
      "timeDistance": {
        "originIndex": 1,
        "destinationIndex": 0,
        "time": 2831,
        "distance": 41230
      }
    },
    {
      "status": "OK",
      "timeDistance": {
        "originIndex": 1,
        "destinationIndex": 1,
        "time": 0,
        "distance": 0
      }
    },
    {
      "status": "OK",
      "timeDistance": {
        "originIndex": 1,
        "destinationIndex": 2,
        "time": 3204,
        "distance": 48100
      }
    }
  ]
}

When a route cannot be computed (e.g. the coordinates are outside the routable network), the element is omitted from the response rather than returned with an error status.

Error response

When the request is invalid or the provider is unavailable, the response has a non-OK status and includes an errorDetails object:

{
  "status": "ERROR",
  "errorDetails": {
    "code": 400,
    "message": "Invalid distance matrix provider",
    "details": "No distance matrix provider found for name: UNKNOWN"
  }
}

Notes on caching

Results are cached per (origin, destination, configurationId, provider, trafficInfoMode) key.
Pairs where origin and destination are at the same coordinates always return time: 0, distance: 0 and are never stored in the cache.
Pass useCache=false to bypass the cache, for example when testing a new OSRM server URL.