Route Matrix API

Compute a full distance and travel-time matrix between a set of origins and a set of destinations, in a single request.

Where it's used

Use cases, value and how it works

Overview & Solution

Which of our drivers is actually closest to this order? Which warehouse should we ship from? Answering that well means comparing every option, not guessing from a map. With several drivers and several open orders, that's a lot of individual distance checks to run and compare by hand.

The Route Matrix API does that comparison in one step. Give it your list of drivers (or warehouses, or pickup points) and your list of orders (or delivery addresses), and it returns the travel distance and time between every pair - so you can see at a glance which combination is closest, and let your own process decide what to do with that.

Industry Use Cases

1. Fleet & Delivery Dispatch

• Nearest-driver comparison - get real road distance and time from every available driver to every open order in one call, instead of one call per driver.

2. Multi-Warehouse Fulfillment

• Fulfillment cost comparison - compare transit distance and time from every candidate warehouse to a customer address before choosing where to ship from.

3. Shuttle & Stop Planning

• Candidate stop comparison - evaluate travel time from several possible pickup points to several possible drop points as an input to a routing decision.

API reference

Route and Journey Intelligence APIs · API key only

Quick try

curl

curl -X POST 'https://api-gw.sovereignsolutions.com/gateway/routing/adapter/sources_to_targets?api-key=$API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"sources": [{"lat": 19.300572, "lon": 72.862937}, {"lat": 19.297798, "lon": 72.8771}, {"lat": 19.287935, "lon": 72.868946}], "targets": [{"lat": 19.29073, "lon": 72.878752}, {"lat": 19.302273, "lon": 72.869868}, {"lat": 19.289839, "lon": 72.857637}], "costing": "auto", "units": "km"}'

Distance/duration matrix between many origins and destinations

POST https://api-gw.sovereignsolutions.com/gateway/routing/adapter/sources_to_targets

Auth: api-key query parameter only - no bearer token, no tenant in the URL

Request parameters

Parameter	In	Type	Required	Description
sources	body	array	-	Origins.
sources[]	body	object	-
sources[].lat	body	number	-	Latitude of the point, decimal degrees.
sources[].lon	body	number	-	Longitude of the point, decimal degrees.
targets	body	array	-	Destinations.
targets[]	body	object	-
targets[].lat	body	number	-	Latitude of the point, decimal degrees.
targets[].lon	body	number	-	Longitude of the point, decimal degrees.
costing	body	string	-	Travel mode used for costing. The examples use auto (driving) and pedestrian (walking).
units	body	string	-	Distance unit: km.

Request body

{
  "sources": [
    {
      "lat": 19.300572,
      "lon": 72.862937
    },
    {
      "lat": 19.297798,
      "lon": 72.8771
    },
    {
      "lat": 19.287935,
      "lon": 72.868946
    }
  ],
  "targets": [
    {
      "lat": 19.29073,
      "lon": 72.878752
    },
    {
      "lat": 19.302273,
      "lon": 72.869868
    },
    {
      "lat": 19.289839,
      "lon": 72.857637
    }
  ],
  "costing": "auto",
  "units": "km"
}

Response

200 OK

{
  "algorithm": "costmatrix",
  "units": "kilometers",
  "sources": [
    {
      "lon": 72.862917,
      "lat": 19.300587
    },
    {
      "lon": 72.877165,
      "lat": 19.297887
    },
    {
      "lon": 72.868706,
      "lat": 19.287927
    }
  ],
  "targets": [
    {
      "lon": 72.878502,
      "lat": 19.290924
    },
    {
      "lon": 72.869882,
      "lat": 19.302307
    },
    {
      "lon": 72.857414,
      "lat": 19.289787
    }
  ],
  "sources_to_targets": [
    [
      {
        "distance": 2.847,
        "time": 277,
        "to_index": 0,
        "from_index": 0
      },
      {
        "distance": 1.287,
        "time": 145,
        "to_index": 1,
        "from_index": 0
      },
      {
        "distance": 1.846,
        "time": 157,
        "to_index": 2,
        "from_index": 0
      }
    ],
    [
      {
        "distance": 1.22,
        "time": 170,
        "to_index": 0,
        "from_index": 1
      },
      {
        "distance": 1.441,
        "time": 161,
        "to_index": 1,
        "from_index": 1
      },
      {
        "distance": 3.106,
        "time": 281,
        "to_index": 2,
        "from_index": 1
      }
    ],
    [
      {
        "distance": 1.947,
        "time": 245,
        "to_index": 0,
        "from_index": 2
      },
      {
        "distance": 2.626,
        "time": 291,
        "to_index": 1,
        "from_index": 2
      },
      {
        "distance": 1.734,
        "time": 189,
        "to_index": 2,
        "from_index": 2
      }
    ]
  ]
}

Response fields (17)

Field	Type	Description
algorithm	string	Matrix algorithm used.
units	string	Distance unit used in the response.
sources	array	Sources as snapped to the road network.
sources[]	object
sources[].lon	number
sources[].lat	number
targets	array	Targets as snapped to the road network.
targets[]	object
targets[].lon	number
targets[].lat	number
sources_to_targets	array	One row per source; each row has one cell per target.
sources_to_targets[]	array
sources_to_targets[][]	object
sources_to_targets[][].distance	number	Distance from source to target, in units.
sources_to_targets[][].time	integer	Travel time from source to target, seconds.
sources_to_targets[][].to_index	integer	Index of the target in your request.
sources_to_targets[][].from_index	integer	Index of the source in your request.

Errors: non-2xx responses use the standard status codes listed on Errors.