GetSegmentData - Spectrum_Routing_for_Big_Data

Description

The GetSegmentData service returns segment information for a point or segment ID. When a point is specified, the closest route segments are returned. When a segment ID is specified, the route data for that specified route segment data is returned.

Note: The response from the REST service comes in JSON format. When a request contains invalid query parameters in the GET URL , a cumulative error response is returned in a JSON array. The value node in the response JSON is deprecated. For error checking, only the errors node should be utilized.

HTTP GET URL Format

The following format is used for HTTP GET requests. The HTTP GET requests are different for either returning segment data at a point, or returning segment data for a segment ID.

Returning data for a segment at a specified point:

HTTP GET /webApp-context/services/databases/dbsource/
  segments.json?point=x,y,srsName&query_parameters

Returning data for a specified segment:

HTTP GET /webApp-context/services/databases/dbsource/segments/
  segmentID.json?query_parameters

Where dbsource is the name of the database that contains the data to use for the route. Use the database name specified in the Database Resource tool. The segmentID is segment identifier you want to return the data.

Query Parameters

This operation takes these query parameters.

Parameter	Type	Required	Description
destinationSrs	String	No	Specifies the coordinate system to return the segment data and resulting geometry. The default is the coordinate system of the data used.
distanceUnit	String	No	Specifies the units to return distance. The default is m (meter). Available values are: m (meter) km (kilometer) yd (yard) ft (foot) mi (mile)
timeUnit	String	No	Specifies the units to return time. The default is min (minute). Available values are: min (minute) msec (millisecond) s (second) h (hour)
velocityUnit	String	No	Specifies the units in which the speed will be returned. The default is mph (miles per hour). Available values are: mph (miles per hour) kph (kilometers per hour)
angularUnit	String	No	Specifies the units to return turn angles. The default is deg (degree). Available values are: deg (degree) rad (radian) minute (minute) sec (second) grad (grad)
segmentGeometryStyle	String	No	Specifies the format of the geometry that represents a segment of the route. Default value is None. Specify this parameter if you required segment geometries to be returned. The options when specifying route directions are: None: No geometric representation of a segment will be returned. Default, if not specified. End: Each segment of the route will be returned with just its endpoints in a LineString. All: Each segment will be returned with all its shape points as a LineString. The LineString can be used as an overlay on a map.
version	String	No	Specifies the version of the GetSegmentData REST service. Valid values are 1 and 2. The default value for version is 1.

Examples

Return segment data specifying a point

http://<server>:<port>/<webApp-context>/services/databases/<US>/
     segments.json?point=-77,38,epsg:4326&segmentGeometryStyle=all

Response

[{
  "segmentID": "aa18eb33:1b7bbe", 
  "primaryName": "VA-631", 
  "primaryNameLanguage": "en",
  "alternateNames": [{
    "alternateName": "Lloyds Rd", 
    "language": "en"
   }, {
    "alternateName": "VA-631", 
    "language": "en"
   }
  ],
  "segmentLength": 4.954, 
  "segmentLengthUnit": "mi", 
  "timeTaken": 5.9333, 
  "timeUnit": "min",
  "turnAngle": 0.0,
  "turnAngleUnit": "deg", 
  "compassDirection": "", 
  "speedOfTravel": 49.9955,
  "speedOfTravelUnit": "mph", 
  "roadType": "major road rural", 
  "segmentDirection": "bidirectional", 
  "startJunctionType": "", 
  "endJunctionType": "Other", 
  "isRoundabout": false,
  "isTollRoad": false, 
  "geometry": {
   "type": "LineString", 
   "crs": {
    "type": "name", 
    "properties": {
     "name": "epsg:4326"
    }
   },
   "coordinates": [[…]]
  }
 },
 },
 "coordinates": [[…]]
 }
}]

Return segment data specifying a segmentID

http://www.precisely.com/webApp-context/services/databases/usroutedatabase/
     segments/aa18eb33:1b7bbe.json?distanceUnits=mi

Response

[{
  "segmentID": "aa18eb33:1b7bbe", 
  "primaryName": "VA-631", 
  "primaryNameLanguage": "en",
  "alternateNames": [{
    "alternateName": "Lloyds Rd", 
    "language": "en"
   }, {
    "alternateName": "VA-631", 
    "language": "en"
   }
  ],
  "segmentLength": 4.954, 
  "segmentLengthUnit": "mi",
  "timeTaken": 5.9333, 
  "timeUnit": "min",
  "turnAngle": 0.0, 
  "turnAngleUnit": "deg", 
  "compassDirection": "", 
  "speedOfTravel": 49.9955,
  "speedOfTravelUnit": "mph", 
  "roadType": "major road rural",
  "segmentDirection": "bidirectional", 
  "startJunctionType": "", 
  "endJunctionType": "Other",
  "isRoundabout": false,
  "isTollRoad": false
 }

Version specific error response

When you enter an invalid parameter value (for example, point 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?version=1

Response:

{
  "value": "Point cannot be empty.", 
  "errors": [
  {
   "errorCode": 4139,
   "userMessage": "Point cannot be empty."
  }
 ]
}

Request when version is 2:

http://server:port/webApp-context/services/databases/usroutedatabase.json?version=2