Route Matrix

Contents

Route Matrix is a licensed add-on for our RESTful Web APIs that calculates travel time and distance between all possible pairs in a list of origins and destinations. It is a powerful tool for load planning and scheduling, as it returns data used to:

  • Optimize stops based on travel time or distance
  • Maintain a list of distances and times between your depots, customers locations, or both, for planning and billing
  • Set up drivers’ loads for the day using carrier, shipper and third party logistics applications or your own custom integrations
Route Matrix screenshot
Map illustration—not an API output—showing two origins and 10 destinations

How does Route Matrix work? #

With the Route Matrix API, you enter up to 10 origins and 10 destinations (per API call) as a series of GPS coordinates. You can also customize how the routing algorithm selects the route used in travel time and distance calculations by setting Routing Options, including:

  • The vehicle type (Truck, LightTruck and Auto) and vehicle dimensions
  • The routing type—Practical or Shortest
  • Whether the route should try to avoid tolls or adhere to hazmat restrictions
  • Specialized settings such as routing to Sites you’ve created in ContentTools or routing to a specific side of the road
  • The PC*MILER version (dataset) to use in calculations

Note: Unlike our other Routing APIs, the Route Matrix API defaults to Highway Only routing. The parameter hwyOnly must be set to false to include local streets in calculations.

What information does Route Matrix provide? #

The Route Matrix API is called via a GET or POST request, and will:

  • Geocode the GPS coordinates entered, and return full address information about each origin and destination. Return the time and distance for each origin and destination pair, in the following order:
    • Origin A to destinations (A, B, C …);
    • Origin B to destinations (A, B, C …);
    • And so on up to 10 origins and 10 destinations per API call.

Sample GET Request #

https://pcmiler.alk.com/apis/rest/v1.0/service.svc/route/matrix?originStops=-76.115321,42.906618;-76.136139,42.824290;-76.126161,42.734645&destStops=-76.553871,42.236842;-76.323899,42.065558;-76.350302,41.998647&authToken={YOUR API KEY}

Sample Response #

{
    "Origins": [
        {
            "Address": {
                "StreetAddress": "I-81",
                "City": "La Fayette",
                "State": "NY",
                "Zip": "13084",
                "County": "Onondaga",
                "Country": "United States",
                "SPLC": null,
                "CountryPostalFilter": 0,
                "AbbreviationFormat": 0,
                "StateName": "New York",
                "StateAbbreviation": "NY",
                "CountryAbbreviation": "US"
            },
            "Coords": {
                "Lat": "42.906618",
                "Lon": "-76.115321"
            },
            "Region": 4,
            "Label": "",
            "PlaceName": "",
            "TimeZone": "EST",
            "Errors": [],
            "SpeedLimitInfo": null,
            "ConfidenceLevel": "Exact",
            "DistanceFromRoad": 0,
            "CrossStreet": null
        },
        {
            "Address": {
                "StreetAddress": "991 NY-11 A",
                "City": "Tully",
                "State": "NY",
                "Zip": "13159",
                "County": "Onondaga",
                "Country": "United States",
                "SPLC": null,
                "CountryPostalFilter": 0,
                "AbbreviationFormat": 0,
                "StateName": "New York",
                "StateAbbreviation": "NY",
                "CountryAbbreviation": "US"
            },
            "Coords": {
                "Lat": "42.824290",
                "Lon": "-76.136139"
            },
            "Region": 4,
            "Label": "",
            "PlaceName": "",
            "TimeZone": "EST",
            "Errors": [],
            "SpeedLimitInfo": null,
            "ConfidenceLevel": "Exact",
            "DistanceFromRoad": 0,
            "CrossStreet": null
        },
        {
            "Address": {
                "StreetAddress": "6795 US-11",
                "City": "Tully",
                "State": "NY",
                "Zip": "13159",
                "County": "Onondaga",
                "Country": "United States",
                "SPLC": null,
                "CountryPostalFilter": 0,
                "AbbreviationFormat": 0,
                "StateName": "New York",
                "StateAbbreviation": "NY",
                "CountryAbbreviation": "US"
            },
            "Coords": {
                "Lat": "42.734645",
                "Lon": "-76.126161"
            },
            "Region": 4,
            "Label": "",
            "PlaceName": "",
            "TimeZone": "EST",
            "Errors": [],
            "SpeedLimitInfo": null,
            "ConfidenceLevel": "Exact",
            "DistanceFromRoad": 0,
            "CrossStreet": null
        }
    ],
    "Destinations": [
        {
            "Address": {
                "StreetAddress": "513 Langford Creek Road  (Route 13)",
                "City": "Van Etten",
                "State": "NY",
                "Zip": "14889",
                "County": "Chemung",
                "Country": "United States",
                "SPLC": null,
                "CountryPostalFilter": 0,
                "AbbreviationFormat": 0,
                "StateName": "New York",
                "StateAbbreviation": "NY",
                "CountryAbbreviation": "US"
            },
            "Coords": {
                "Lat": "42.236842",
                "Lon": "-76.553871"
            },
            "Region": 4,
            "Label": "",
            "PlaceName": "",
            "TimeZone": "EST",
            "Errors": [],
            "SpeedLimitInfo": null,
            "ConfidenceLevel": "Exact",
            "DistanceFromRoad": 0.004,
            "CrossStreet": null
        },
        {
            "Address": {
                "StreetAddress": "Southern Tier Expressway  (NY-17)",
                "City": "Nichols",
                "State": "NY",
                "Zip": "13812",
                "County": "Tioga",
                "Country": "United States",
                "SPLC": null,
                "CountryPostalFilter": 0,
                "AbbreviationFormat": 0,
                "StateName": "New York",
                "StateAbbreviation": "NY",
                "CountryAbbreviation": "US"
            },
            "Coords": {
                "Lat": "42.065558",
                "Lon": "-76.323899"
            },
            "Region": 4,
            "Label": "",
            "PlaceName": "",
            "TimeZone": "EST",
            "Errors": [],
            "SpeedLimitInfo": null,
            "ConfidenceLevel": "Exact",
            "DistanceFromRoad": 0.001,
            "CrossStreet": null
        },
        {
            "Address": {
                "StreetAddress": "1653 South Main Street  (NY-282)",
                "City": "Nichols",
                "State": "NY",
                "Zip": "13812",
                "County": "Tioga",
                "Country": "United States",
                "SPLC": null,
                "CountryPostalFilter": 0,
                "AbbreviationFormat": 0,
                "StateName": "New York",
                "StateAbbreviation": "NY",
                "CountryAbbreviation": "US"
            },
            "Coords": {
                "Lat": "41.998647",
                "Lon": "-76.350302"
            },
            "Region": 4,
            "Label": "",
            "PlaceName": "",
            "TimeZone": "EST",
            "Errors": [],
            "SpeedLimitInfo": null,
            "ConfidenceLevel": "Exact",
            "DistanceFromRoad": 0.001,
            "CrossStreet": null
        }
    ],
    "MatrixInfo": [
        [
            {
                "Success": true,
                "Errors": [],
                "Time": "01:41:09",
                "Distance": "71.56"
            },
            {
                "Success": true,
                "Errors": [],
                "Time": "01:33:14",
                "Distance": "87.20"
            },
            {
                "Success": true,
                "Errors": [],
                "Time": "01:41:45",
                "Distance": "94.55"
            }
        ],
        [
            {
                "Success": true,
                "Errors": [],
                "Time": "01:36:21",
                "Distance": "65.87"
            },
            {
                "Success": true,
                "Errors": [],
                "Time": "01:28:26",
                "Distance": "81.51"
            },
            {
                "Success": true,
                "Errors": [],
                "Time": "01:36:57",
                "Distance": "88.86"
            }
        ],
        [
            {
                "Success": true,
                "Errors": [],
                "Time": "01:30:10",
                "Distance": "59.26"
            },
            {
                "Success": true,
                "Errors": [],
                "Time": "01:24:14",
                "Distance": "75.67"
            },
            {
                "Success": true,
                "Errors": [],
                "Time": "01:32:45",
                "Distance": "83.01"
            }
        ]
    ]
}

For more information, please see:

Route Matrix API Documentation


Last updated April 1, 2021.

Share this article: