Request and Response - Precisely Data Integrity Suite

Data Integrity Suite APIs
Product
Data_Integrity
Spatial_Analytics
Data_Enrichment
geo_addressing_1
Services
Spatial Analytics
Data Enrichment
Geo Addressing
ft:title
Data Integrity Suite APIs
ft:locale
en-US
PublicationType
pt_developer
copyrightfirst
2023
copyrightlast
2026

This section describes how this API works. You may want to try it out with a Free Trial Account.

This method will consume credits.
  1. HTTP Request
    • URL Composition
      • Base URL: https://api.cloud.precisely.com
      • Travel Matrix API : /v1/matrix/location
    • Supported Methods: GET and POST
    • Rate Limit (Transactions per second): 100

    • Authentication and Input Fields: Data Integrity Suite's APIs provide multiple authentication methods. Whether you want to pass the API Key and Secret directly as part of the Basic Authentication header or use bearer tokens, you can do either using the same header. The two ways of authentication are:

      1. Basic Authentication (Using API Key and secret)
      2. Bearer Token Authentication

      For more information about authentication, see How to Authenticate and follow the instructions.

  2. Response
    • Content-type: application/json

Query Parameters

This API takes these query parameters.

Parameter Type Required Description
coordOrder String No Specifies the coordinate order used in the request.

Use LonLat to provide coordinates in longitude, latitude (X, Y) order. Use LatLon to provide coordinates in latitude, longitude (Y,X) order.

If not specified the coordinates are expected to be in the in latitude, longitude (LatLon) order.

This parameter applies to the origin, destination, and waypoints parameters.
originAddresses String No Address of the starting location for the route. Multiple originAddresses should be separated by a comma (,).

Example: "originAddresses": [ { "address": "675 S Broadway Suite 600, Denver, CO 80209, United States", "country": "USA" }, { "address": "476 S Broadway, Denver, CO 80209, United States", "country": "USA" } ],

destinationAddresses String No Address of the destination location for the route. Multiple destinationAddresses should be separated by a comma (,).

Example: "destinationAddresses": [ { "address": "383 S Pearl St, Denver, CO 80209, United States", "country": "USA" }, { "address": "500 S Broadway, Denver, CO 80209, United States", "country": "USA" } ],
origins String Yes origins are the starting point of your route. Ensure that origins are routable land locations. Multiple origins should be separated by a comma (,).

Format: latitude_1,longitude_1,latitude_2,longitude_2

Example: origins=41.349302,2.136480,41.389925,2.136258,41.357961,2.097878
destinations String Yes destinations are the ending coordinates of your route. Ensure that destinations are routable land locations. Multiple destinations should be separated by a comma (,).

Format: latitude_1,longitude_1, latitude_2,longitude_2

Example: destinations=41.349302,2.136480,41.389925,2.136258,41.357961,2.097878
mode String No Set which driving mode the service should use to determine the distance and duration values.

For example, if you use car, the API will return the duration and distance of a route that a car can take. Using truck will return the same for a route a truck can use, taking into account appropriate truck routing restrictions.

When mode=truck, following are the default dimensions that are used:

truck_height = 214 centimeters

truck_width = 183 centimeters

truck_length = 519 centimeters

truck_weight = 5000 kg

If you want to specify custom truck dimensions, use truck_weight and truck_size parameters.

Default: car

Example: mode=car

Allowed Values: car truck motorcycle bike walk
avoid String No Set this parameter to find alternative routes that bypass specified objects. Use a comma (,) to separate multiple values. This is a flexible filter; if no alternative routes exist, the service will still provide a route that includes the objects. For a strict filter, consider using the exclude parameter.
Note:
  • This parameter is effective only when route_type=fastest.
  • Following objects are exceptions to the flexible filtering behavior of avoid parameter: bbox and tunnel. When used, the service will return a 4xx error in case there are no alternative routes available.
  • When using avoid=bbox users also need to specify the boundaries of the bounding box to be avoided. Multiple bounding boxes can be specified simultaneously. The perimeter of a bounding box can not exceed 500 kms.
    • Format: bbox: min_latitude,min_longtitude,max_latitude,max_longitude.
    • Example: avoid=bbox: 34.0635,-118.2547, 34.0679,-118.2478 , bbox: 34.0478,-118.2437, 34.0521,-118.2342
  • When using avoid=sharp_turn, default range of permissible turn angles is (120,240) in the clockwise direction from the current road. In order to override default range, use turn_angle_range parameter.
  • When this parameter is not provided in the input, ferry routes are set to be avoided by default. When this parameter is provided, only the mentioned object(s) are avoided.
  • If none is provided along with other values, an error is returned as a valid route is not feasible.

Format: value_1,value_2

Default: ferry

Example: avoid=toll,highway,bbox:34.0635,-118.2547,34.0679,-118.2478

Allowed Values: toll, ferry, highway, service_road, uturn, sharp_turn, left_turn, right_turn, bbox, tunnel, none
exclude String No This parameter serves as a mandatory filter, ensuring the service returns only those routes that strictly avoid the object(s) indicated. Multiple values should be separated by a comma (,). If no routes can be found that exclude the specified object(s), the service will return a 4xx error. For a less strict filtering approach, consider using the avoid parameter.
Note:
  • This parameter is effective only when route_type=fastest.
  • When using exclude=sharp_turn, default range of permissible turn angles is (120,240) in the clockwise direction from the current road. In order to override default range, please use turn_angle_range parameter.
  • If none is provided along with other values, an error is returned as a valid route is not feasible.

Format: value_1,value_2

Default: none

Example: exclude= highway,toll,uturn

Allowed Values: toll, ferry, highway, service_road, uturn, sharp_turn, left_turn, right_turn, none
approaches String No A semicolon-separated list indicating the side of the road from which the route will approach destinations.

When set to unrestricted a route can arrive at a destination from either side of the road. When set to curb the route will arrive at a destination on the driving side of the region.

The number of values provided must be equal to the number of destinations. However, you can skip a coordinate and show its position in the list with the semicolon (;) separator.

The values provided for the approaches parameter are effective for the destinations value at the same index. Example: curb;;curb will apply curbside restriction on the destinations points provided at the first and third index.

Format: approaches_1;approaches_2;approaches_3

Default: unrestricted

Example: approaches=unrestricted;curb;;unrestricted

Allowed Values: unrestricted, curb
option String Yes Use this option to switch to truck-specific routing or time based routing or if you want to choose between the fastest and shortest route types.

Example: option=flexible

Allowed Values: flexible
departure_time Integer No Use this parameter to set a departure time for your trip using a UNIX timestamp in seconds precision. The response will return a route based on typical traffic conditions at the given start time and week day.

departure_time is ineffective when route_type is set to shortest as the service will return the shortest path possible irrespective of the traffic conditions.

Note: The timestamp must be supplied in the API as a UTC time (Universal Time Coordinated) and will be converted to the time zone of input co-ordinates being sent in origins. Use an UNIX timestamp converter to convert values to and from UNIX timestamps.

Example: departure_time=1759154400 translates to Monday, September 29, 2025 14:00:00 UTC. If the origin coordinate sent in the request is for Kansas USA, the local time used by the API will be Monday, 29 September 2025 09:00:00 since Kansas is 5 hours behind UTC. If the requested origin is for Athens in Greece, then the local time used by the API will be Monday, 29 September 2025 16:00:00 since Greece is 2 hours ahead of UTC.

Note: The departure_time and local_departure_time parameters are mutually exclusive. You must use either departure_time or local_departure_time. If neither parameter is specified, then the traffic conditions at the UTC time of making the request are considered.
local_departure_time String No Use this parameter to set a departure time, expressed as string representing the weekday and hour of the local time at the departure point. The response considers the typical traffic conditions at the given weekday and hour and returns a contour which can be reached under those traffic conditions.
Example: departure_time = Monday 9:00 translates to Monday at 9am local time for all departure points. If the origin coordinate sent in the request is for New York USA, the local time used by the API is 9am. If the requested origin is for Athens in Greece, then the local time used by the API is Monday 9am. The following requests return the same isochrone for New York at 9 am local time:
  • departure_time=1764597600 translates to UTC time 1st December 2025 at 14:00. Local time used in New York is 09:00 am (EST)
  • departure_time= 1751893200 translates to UTC time 7th July 2025 at 13:00. Local time used in New York is 09:00 am (EDT)
  • local_departure_time = Monday 9:00. Local time used in New York is 09:00 am
Note:
  • Allowed values for day names are Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday or Mon, Tue, Wed, Thu, Fri, Sat, Sun
  • The hour values must in the form nn:00 where 'nn' represents the hour (00:00 to 23:00)
  • The departure_time and local_departure_time parameters are mutually exclusive. You must use either departure_time or local_departure_time. If neither parameter is specified, then the traffic conditions at the UTC time of making the request are considered.
truck_size String No This defines the dimensions of a truck in centimeters (cm). This parameter is effective only when the mode=truck. Maximum dimensions are as follows:

Height = 1000 cm

Width = 5000 cm

Length = 5000 cm

Format: height,width,length

Example: truck_size=200,210,600
truck_weight Integer No This parameter defines the weight of the truck including trailers and shipped goods in kilograms (kg). This parameter is effective only when mode=truck.

Minimum: 1

Maximum: 100000

Example: truck_weight=11770
route_type String No Set the route type that needs to be returned.

Default: fastest

Example: route_type=fastest

Allowed Values: fastest, shortest
cross_border Boolean No Specify if crossing an international border is expected for operations near border areas. When set to false, the API will prohibit routes crossing the borders. When set to true, the service will return routes which cross the borders between countries, if required for the given set destination and waypoints.
truck_axle_load Number No Specify the total load per axle (including the weight of trailers and shipped goods) of the truck, in tonnes. When used, the service will return routes which are legally allowed to carry the load specified per axle.
Note: This parameter is effective only when `mode=truck`.

Example: 5.6
hazmat_type String No Specify the type of hazardous material being carried and the service will avoid roads which are not suitable for the type of goods specified. Multiple values can be separated using a comma (,) .
Note: This parameter is effective only when mode=truck.

Example: hazmat_type=explosives , corrosive

Allowed Values: explosives, gas, flammable_liquid, flammable_gas, organic, toxic, radioactive, corrosive, other
turn_angle_range Integer No Specify the turn angles that can be taken safely by the vehicle. The permissible turn angles are calculated as (0 + turn_angle_range , 360 - turn_angle_range).
Note: This parameter is effective only when avoid = sharp_turn.

Providing smaller angles might lead to 4xx errors as route engine might not be able find routes satisfying the smaller turn angle criteria for all turns in the route.
route_failed_prompt Boolean No A prompt to modify the response in case no feasible route is available for a given pair of origin and destination. When set to true a value of "-1" is returned for those pairs in which:
  • either origin or the destination can not be snapped to a nearest road. If all the origins and destinations in a request can't be snapped to their nearest roads, a 4xx error is returned instead, as the entire request failed.
  • both origin and destination can be snapped to the nearest road but the service can't find a valid route between them.

However, a value of "0" is returned if both the origin and destination are snapped to the same location.

False is the default value. In this case, a "0" value is returned for all the above cases. A 4xx error is returned, in this case as well, when all origins and destinations in the request can't be snapped to their nearest road.
bearings String No Limits the search to segments with given bearing in degrees towards true north in clockwise direction. Each bearing should be in the format of degree,range, where the degree should be a value between (0, 360) and range should be a value between (0, 180).
Note: The number of bearings should be equal to the sum of the number of points in origins and destinations. If a route can approach a destination from any direction, the bearing for that point can be specified as "0,180".

Format: degree0,range0;degree1,range1

Default: none

Example: bearings=0,180;0,180
emission_class

String

No Specify the emission class to which the vehicle (engine) belongs to. The service will use this setting to generate routes that are permissible for that engine class. Only the emission classifications in the EU regions are supported currently.

Example: emission_class=euro2 , euro3

Allowed Values: euro0, euro1, euro2, euro3, euro4, euro5, euro6, euro7, euro8, euro9
Note: When specifying locations, the coordinate-based parameters and address-based parameters are mutually exclusive. A request must use only one set of parameters consistently. You must provide all locations using either origin, destination, and waypoints, or originAddress, destinationAddress, and waypointAddresses.

Examples

Request

https://api.cloud.precisely.com/v1/matrix/location?mode=car&departure_time=1563254734&origins=41.349302,2.136480,41.389925,2.136258,41.357961,2.097878&destinations=41.349302,2.136480,41.389925,2.136258,41.357961,2.097878&exclude=none&approaches=unrestricted;unrestricted;unrestricted&truck_weight=11770&route_type=fastest&cross_border=false&route_failed_prompt=false&option=flexible&coordOrder=LatLon
 
https://api.cloud.precisely.com/v1/matrix/location?option=flexible
{
  "coordOrder": "LatLon",
  "origins": "41.349302,2.136480|41.389925,2.136258|41.357961,2.097878",
  "destinations": "41.349302,2.136480|41.389925,2.136258|41.357961,2.09787",
  "mode": "car",
  "avoid": "ferry",
  "exclude": "none",
  "approaches": "unrestricted;unrestricted;unrestricted",
  "departure_time": 1563254734,
  "route_type": "fastest",
  "cross_border": false,
  "route_failed_prompt": false
}
 
https://api.cloud.precisely.com/v1/matrix/location?option=flexible
{
    "originAddresses": [
        {
            "address": "675 S Broadway Suite 600, Denver, CO 80209, United States",
            "country": "USA"
        },
        {
            "address": "476 S Broadway, Denver, CO 80209, United States",
            "country": "USA"
        }
    ],
    "destinationAddresses": [
        {
            "address": "383 S Pearl St, Denver, CO 80209, United States",
            "country": "USA"
        },
        {
            "address": "500 S Broadway, Denver, CO 80209, United States",
            "country": "USA"
        }
    ],
    "mode": "car",
    "avoid": "ferry",
    "exclude": "none",
    "departure_time": 1563254734,
    "route_type": "fastest",
    "cross_border": false,
    "route_failed_prompt": false
}

Response

{
    "status": "Ok",
    "rows": [
        {
            "elements": [
                {
                    "duration": {
                        "value": 0
                    },
                    "distance": {
                        "value": 0
                    }
                },
                {
                    "duration": {
                        "value": 929
                    },
                    "distance": {
                        "value": 7038
                    }
                },
                {
                    "duration": {
                        "value": 577
                    },
                    "distance": {
                        "value": 7839
                    }
                }
            ]
        },
        {
            "elements": [
                {
                    "duration": {
                        "value": 965
                    },
                    "distance": {
                        "value": 6938
                    }
                },
                {
                    "duration": {
                        "value": 0
                    },
                    "distance": {
                        "value": 0
                    }
                },
                {
                    "duration": {
                        "value": 912
                    },
                    "distance": {
                        "value": 7671
                    }
                }
            ]
        },
        {
            "elements": [
                {
                    "duration": {
                        "value": 692
                    },
                    "distance": {
                        "value": 7654
                    }
                },
                {
                    "duration": {
                        "value": 936
                    },
                    "distance": {
                        "value": 7798
                    }
                },
                {
                    "duration": {
                        "value": 0
                    },
                    "distance": {
                        "value": 0
                    }
                }
            ]
        }
    ]
}
 
{
    "status": "Ok",
    "rows": [
        {
            "elements": [
                {
                    "duration": {
                        "value": 230
                    },
                    "distance": {
                        "value": 1477
                    }
                },
                {
                    "duration": {
                        "value": 172
                    },
                    "distance": {
                        "value": 875
                    }
                }
            ]
        },
        {
            "elements": [
                {
                    "duration": {
                        "value": 135
                    },
                    "distance": {
                        "value": 740
                    }
                },
                {
                    "duration": {
                        "value": 49
                    },
                    "distance": {
                        "value": 149
                    }
                }
            ]
        }
    ]
}