Transient Updates - Spectrum_Routing_for_Big_Data

Description

It allows you to set transient updates (point, segment, road type 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 Transient Updates service allows a user to override aspects of the network. The overrides can be done on a per-road type, at a specific point or a specific segment. The Transient Update is valid only for a specific data source and may not be valid after a data update.

Using the Transient Updates, you can perform the following:

Exclude a point
Exclude a segment
Set the speed of a point, segment, or road type
Change (increase or decrease) the speed of a point, segment, or road type by a value
Change (increase or decrease) the speed of a point, segment, or road type by a percentage

The following is a description of the transient update types.

point Update

Point updates are changes applied to a corresponding point (X, Y). 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:

Point Update Type Description

PointUpdate Type	Description
percentage	Specifies the speed update where you can replace the speed of the point by specifying a percentage to increase (positive value) or decrease (negative value) the speed.
speed	Specifies the speed update where you can define the new speed of the point by specifying the new velocity. For speed updates, the velocity can have one of the following values: kph (kilometers per hour) mph (miles per hour) mtps (meters per second) mtpm (meters per minute)
speedAdjustment	Specifies a speed update where you can define a change in the speed of the point by specifying the change in the value. The speed velocity can be increased (positive value) or decreased (negative value). For speed updates, the velocity can have one of the following values: kph (kilometers per hour) mph (miles per hour) mtps (meters per second) mtpm (meters per minute)
exclude	Specifies a 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). This is a String update type.

SegmentID Update

Specifies the segment updates applied to a corresponding segment ID. For a particular segment, you can exclude the segment, set the speed of the segment, or change (increase or decrease) the speed of the segment by a value or percentage. Use one of the following types of updates:

SegmentID Update Type	Description
percentage	Specifies a speed update where you can define an increase in the speed of the segmentID by specifying a percentage to increase (positive value) or decrease (negative value) the speed.
speed	Specifies a speed update where you define the new speed of the segmentID by specifying the new velocity. For speed updates, the velocity can have one of the following values: kph (kilometers per hour) mph (miles per hour) mtps meters per second) mtpm (meters per minute)
speedAdjustment	Specifies the speed update where you can define a change in the speed of the segmentID by specifying the change in velocity. Speed values can be increased (positive value) or decreased (negative value). For speed updates, the velocity can have one of the following values: kph (kilometers per hour) mph (miles per hour) mtps (meters per second) mtpm (meters per minute)
exclude	Specifies the 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). This is a String update type.
roadType	Specifies a value to change the road type for the segment for the route calculation. See the "roadType" list below.

roadType Update

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:

roadType Update Type	Description
percentage	Specifies the speed update where you can 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	Specifies the speed update where you can define the new speed of the road type by specifying the 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	Specifies the speed update where you can define a change in the speed of the road type by specifying the change in velocity. Speed values can be increased (positive value) or decreased (negative value). For speed updates, the velocity can have one of the following values: kph (kilometers per hour) mph (miles per hour) mtps (meters per second) mtpm (meters per minute)

roadType

Specifies a value to change the road type for the segment for the route calculation. 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
normal 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

Code Examples

Example of transient update HTTP POST payload

{
 "transientUpdates": [{
   "segmentID": "specify a segment id", 
   "updates": [{
     "exclude": "Y"
    }, {
     "roadType": "a road type"
    }, {
     "percentage": 26.0
    }, {
     "speed": { 
      "velocity": 25,
      "velocityUnit": "kph"
     }
    }, {
     "percentage": -13.5
    }, {
     "speedAdjustment": { 
      "velocity": 5, 
      "velocityUnit": "kph"
     }
    }
   ]
  }, {
   "point": "specify a geojson point", 
   "updates": [{
     "exclude": "Y"
    }, {
     "percentage": 26.0
    }, {
     "speed": { 
      "velocity": 25, 
      "velocityUnit": "kph"
     }
    }, {
     "percentage": -13.5
    }, {
     "speedAdjustment": { 
      "velocity": 5, 
      "velocityUnit": "kph"
     }
    }
   ]
  }, {
   "roadType": "specify a road type", 
   "updates": [{
     "percentage": 26.0
    }, {
     "speed": { 
      "velocity": 25, 
      "velocityUnit": "kph"
     }
    }, {
     "percentage": -13.5
    }, {
     "speedAdjustment": { 
      "velocity": 5, 
      "velocityUnit": "kph"
     }
    }
   ]
  }
 ]
}

Example of geojson point

"point": { 
 "type": "Point", 
 "crs": {
  "type": "name", 
  "properties": {
   "name": "epsg:4326"
  }
 },
 "coordinates":
 [-73.979102, 40.785193]
}

Version specific error response

When you enter an invalid parameter value (for example, json missing) in a request, the error response you get depends on the version entered by you. When the version is 1, you get value and error whereas when the version is 2, the response only contains the error.

Request when version is 1:

http://server:port/webApp-context/services/databases/usroutedatabase.json?
     startPoint=-73.972033%2C40.794928%2Cepsg%3A4326&distanceUnit=mi
     &endPoint=-73.985617%2C40.747%2Cepsg%3A4326&q=route&version=1

Response:

{
 "value": "Invalid POST payload specified: JSON is not valid.", 
 "errors": [
   {
    "errorCode": 4182,
    "userMessage": "Invalid POST payload specified: JSON is not valid."
   }
  ]
}

Request when version is 2:

http://server:port/webApp-context/services/databases/usroutedatabase.json?
     startPoint=-73.972033%2C40.794928%2Cepsg%3A4326&distanceUnit=mi
     &endPoint=-73.985617%2C40.747%2Cepsg%3A4326&q=route&version=2