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: percentage This is a speed update where you define an increase in the speed of the point by specifying a percentage to increase(positive value) or decrease(negative value) the speed. speed This is a speed update where you define the new speed of the point by specifying the velocity unit and new velocity. For speed updates, the velocity unit can have one of the following values: kph (kilometers per hour), mph (miles per hour), mtps (meters per second), mtpm (meters per minute). speedAdjustment This is a speed update where you define a change in the speed of the point by specifying the change in velocity (unit and value). Speed values can be increased(positive value) or decreases(negative value). For speed updates, the velocity unit can have one of the following values: kph (kilometers per hour), mph (miles per hour), mtps (meters per second), mtpm (meters per minute). exclude This is a string value to exclude the specified point from the route calculation. To exclude a point you need to specify the point and include the exclude parameter defined as Y. Valid values are Y (yes) and N (no).
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: percentage This is a speed update where you define an increase in the speed of the segmentID by specifying a percentage to increase(positive value) or decrease(negative value) the speed. speed This is a speed update where you define the new speed of the segmentID by specifying the velocity unit and new velocity. For speed updates, the velocity unit can have one of the following values: kph (kilometers per hour), mph (miles per hour), mtps (meters per second), mtpm (meters per minute). speedAdjustment This is a speed update where you define a change in the speed of the segmentID by specifying the change in velocity (unit and value). Speed values can be increased(positive value) or decreases(negative value). For speed updates, the velocity unit can have one of the following values: kph (kilometers per hour), mph (miles per hour), mtps (meters per second), mtpm (meters per minute). exclude This is a string value to exclude the specified segmentID from the route calculation. To exclude a segmentID you need to specify the segmentID and include the exclude parameter defined as Y. Valid values are Y (yes) and N (no). roadType This is a string value to change the value of the road type for the segment for the route calculation. The roadType can be one of the following: access way back road connector ferry footpath limited access dense urban limited access rural limited access suburban limited access urban local road dense urban local road rural local road suburban local road urban major local road dense urban major local road rural major local road suburban major local road urban major road dense urban major road rural major road suburban major road urban minor local road dense Urban minor local road rural minor local road suburban minor local road urban mormal road dense urban normal road rural normal road rural normal road urban primary highway dense urban primary highway rural primary highway suburban primary highway urban ramp dense urban ramp limited access ramp major road ramp primary highway ramp rural ramp secondary highway ramp urban ramp suburban secondary highway dense urban secondary highway rural secondary highway suburban secondary highway urban
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: percentage This is a speed update where you define an increase in the speed of the road type by specifying a percentage to increase(positive value) or decrease(negative value) the speed. speed This is a speed update where you define the new speed of the road type by specifying the velocity unit and new velocity. For speed updates, the velocity unit can have one of the following values: kph (kilometers per hour), mph (miles per hour), mtps (meters per second), mtpm (meters per minute). speedAdjustment This is a speed update where you define a change in the speed of the road type by specifying the change in velocity (unit and value). Speed values can be increased(positive value) or decreases(negative value). For speed updates, the velocity unit can have one of the following values: kph (kilometers per hour), mph (miles per hour), mtps (meters per second), mtpm (meters per minute).

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: vehicleType Choose either ALL or one of the types of vehicles: STRAIGHT, SEMI_TRAILOR, STANDARD_DOUBLE, INTERMEDIATE_DOUBLE, LONG_DOUBLE, TRIPLE, OTHER_LONG_COMBINATION_VEHICLE. weight Specifies the maximum weight of a vehicle. Any vehicles over this value will be restricted when determining the route. The units of weight are: kg, lb, mt, t. height Specifies the maximum height of a vehicle. Any vehicles over this value will be restricted when determining the route. The units of height are: ft, yd, mi, m, km. length Specifies the maximum length of a vehicle. Any vehicles over this value will be restricted when determining the route. The units of length are: ft, yd, mi, m, km. width Specifies the maximum width of a vehicle. Any vehicles over this value will be restricted when determining the route. The units of width are: ft, yd, mi, m, km. Note: You need to specify either weight/height or length/width along with its corresponding unit.

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