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.

---

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

Endpoints

All requests need only your API key, as the api-key query parameter - no bearer token:

?api-key=<apiKey>

Distance/duration matrix between many origins and destinations

POST /routing/adapter/sources_to_targets

Base URL: https://api-gw.sovereignsolutions.com/gateway

Request Parameters

Parameter	In	Type	Required	Description	Example
sources	body	array	No	Origins.
sources[]	body	object	No
sources[].lat	body	number	No	Latitude of the point, decimal degrees.
sources[].lon	body	number	No	Longitude of the point, decimal degrees.
targets	body	array	No	Destinations.
targets[]	body	object	No
targets[].lat	body	number	No	Latitude of the point, decimal degrees.
targets[].lon	body	number	No	Longitude of the point, decimal degrees.
costing	body	string	No	Travel mode used for costing. The examples use auto (driving) and pedestrian (walking).
units	body	string	No	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 Schema

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
      }
    ]
  ]
}

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.

Example

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"}'