GetRouteCostMatrix HTTP POST Options
HTTP POST URL Format
In addition to the regular HTTP GET parameters, you can add HTTP POST payload options to your request that specifies transient updates and priority for road types. The HTTP POST payload can also be used if the list of input points exceeds the limits of the caller’s URL buffer. The content type must be set to application/json. The following format is used for HTTP POST requests:
HTTP POST: /rest/Spatial/erm/databases/dbsource.json?q=routeCostMatrix&query_parameters
POST BODY: Content-Type:application/json {Route Data}
Define Start and End Points
To include a set of start or end points in a HTTP POST request, add the MultiPoint JSON payload indicating the points that the route will include. When Start and End points are defined in the HTTP POST payload, the startPoints and endPoints parameters are not mandatory query parameters in the URL. If they are defined in the URL they are ignored. A warning message is logged in spectrum-server.log file when points in URL are ignored.
Example start points HTTP POST payload.
{
"startPoints": {"type": "MultiPoint","crs": {"type": "name","properties": {"name": "epsg:4326"}},"coordinates": [[ -73.976266,40.788717],[ -73.973562,40.792193],[ -73.971802,40.794630]]}
}
Example end points HTTP POST payload.
{
"endPoints": {"type": "MultiPoint","crs": {"type": "name","properties": {"name": "epsg:4326"}},"coordinates": [[ -73.976266,40.788717],[ -73.973562,40.792193],[ -73.971802,40.794630]]}
}
Transient Updates
This set of preferences allows you to set transient updates for each request. For instance, you can request that the server attempt to avoid all of the major road types. Each request can contain one or more updates. For speed updates, positive speed value is a speed increase and negative speed value is a speed decrease. The following is a description of the transient update types:
Update Type |
Description |
---|---|
point |
Point updates are changes applied to a corresponding point (Latitude, Longitude). For a particular point, you can: exclude the point, set the speed of the point or change (increase or decrease) the speed of the point by a value or percentage. Use one of the following types of updates:
|
segmentID |
Segment updates are changes applied to a corresponding segment ID. For a particular segment, you can: exclude the segment, set the speed of the segment, change (increase or decrease) the speed of the segment by a value or percentage, or change the road type of the segment. Use one of the following types of updates:
|
roadType |
Road type updates are changes applied to a corresponding road type. For a particular road type, you can: set the speed of the roadtype, or change (increase or decrease) the speed of the road type by a value or percentage. Use one of the following types of updates:
|
Example transient update HTTP POST payload.
{
"transientUpdates": [
{
"segmentID": "7e3396fc:151186f",
"updates": [
{"percentage": 26.0}
]
},
{
"point": {"type": "Point",
"crs":
{
"type": "name",
"properties":
{
"name": "epsg:4326"
}
},
"coordinates":
[
-73.972776,
40.795076
]
},
"updates": [
{"speedAdjustment" : { "velocity": 5, "velocityUnit": "kph"}}
]
},
{
"roadType": "major road dense urban",
"updates": [
{"speed": { "velocity": 25, "velocityUnit": "kph"}}
]
}
]
}
Commercial Vehicle Restrictions
Commercial vehicle restrictions are composed of directives to the routing engine that guides the behavior and attributes of commercial vehicles making trips along the route. Depending upon vehicle attributes provided (such as height, width, length, weight) and the commercial vehicle restriction attributes present in the road network, decision is made whether to allow to route a particular vehicle over a segment or not. If there is no commercial vehicle restriction attribute present in road network, input restriction parameters will have no effect in the resultant route.
Following are the set of parameters for commercial vehicle restrictions:
Option | Description |
---|---|
looseningBarrierRestrictions |
Specifies that barriers will be removed when determining the route. These restrictions are most often when a commercial vehicle is prohibited from traversing a segment due to local ordinance or a commercial vehicle is allowed on the segment but only when it must (for example, last mile access, local delivery, and so on). Routes where a barrier has been removed will still have a higher route cost even if the route it shorter/faster than a route with no barrier. |
vehicleAttributes |
Specifies that details of the vehicle that will be restricted based on the type, height, weight, length, or width when determining the route. Commercial vehicles are divided into different types ranging from short trailers to long triples. The Commercial Vehicle Restrictions attribution is organized on a per-vehicle type basis. This means it is entirely possible for a segment to be preferred for one vehicle type and the same segment have a restriction for another type of vehicle. Use the following types of vehicle information:
|
Examples
Without Vehicle Restrictions
Request:
HTTP GET /rest/Spatial/erm/databases/US_CVR.json?q=routeCostMatrix&startPoints=-74.7221203,42.9737073,epsg:4326&endPoints=-74.6671887,42.8097083,epsg:4326
Response:
{
"matrix": [{
"distance": 40025,
"distanceUnit": "m",
"endPoint": {
"type": "Point",
"coordinates": [-74.6671887, 42.8097083]
},
"startPoint": {
"type": "Point",
"coordinates": [-74.7221203, 42.9737073]
},
"time": 36.57,
"timeUnit": "min"
}]
}
With Vehicle Restrictions
Request:
HTTP GET /rest/Spatial/erm/databases/US_CVR.json?q=routeCostMatrix&startPoints=-74.7221203,42.9737073,epsg:4326&endPoints=-74.6671887,42.8097083,epsg:4326
Commercial Vehicle Restriction HTTP POST payload.
{
"cvr":{
"looseningBarrierRestrictions":"n","vehicleAttributes":{
"vehicleType":"ALL","heightUnit":"meter","height":"4","weightUnit":"Kilogram","weight":"40000"
}
}
}
Response:
{
"matrix": [{
"distance": 44933,
"distanceUnit": "m",
"endPoint": {
"type": "Point",
"coordinates": [-74.6671887, 42.8097083]
},
"startPoint": {
"type": "Point",
"coordinates": [-74.7221203, 42.9737073]
},
"time": 37.48,
"timeUnit": "min"
}]
}
the distance and time value has changed with CVR.
Road Type Priority
Specifies the priority to give to different types of roads when determining the route. The following is a description of the road type priority options:
Option |
Description |
---|---|
high |
Prefer the road type over other road types. |
medium |
Give this road type equal preference with other road types. If no preference is specified for a road type, the default is Medium. |
low |
Prefer other road types over this road type. |
avoid |
Exclude the road type from routes if possible. It is not always possible to exclude a road type from the travel directions. Depending on the situation, the alternative to an avoided road type may be so poor that the software will choose a route that uses an avoided road type. Also, if the starting or ending point lies along a segment whose road type has been avoided, the software will still use that segment. |
Example road type priority HTTP POST payload.
{
"roadTypesPriority": {
"RoadType.MajorRoadDenseUrban": "High",
"RoadType.LimitedAccessDenseUrban":"Low",
"RoadType.LimitedAccessRural":"Medium",
"RoadType.PrimaryHighwayUrban":"Avoid"
}
}