GetSegmentData

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 is returned.

Note: The response from the REST service will be in JSON format. When a request contains invalid query parameters in the GET URL or an invalid payload for POST, a cumulative error response will be 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 /rest/Spatial/erm/databases/dbsource/segments.json?point=x,y,srsName&query_parameters

Returning data for a specified segment:

HTTP GET /rest/Spatial/erm/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 Spectrum Spatial Routing 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 The coordinate system to return the segment data and resulting geometry. The default is the coordinate system of the data used.
distanceUnit String no 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 The units to return time. The default is min (minute). Available values are: min(minute), msec(millisecond), s(second), h(hour).
velocityUnit String no The units to return speed. The default is mph (miles per hour). Available values are: mph(miles per hour) and kph(kilometers per hour).
angularUnit String no 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

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>/rest/Spatial/erm/databases/usroutedatabase/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": [[…]]
	}
},
{
	"segmentID": "46ed0e49:d9a7dc",
	"primaryName": "VA-631",
	"primaryNameLanguage": "en",
	"alternateNameList": [{
		"alternateName": "Lloyds Rd",
		"language": "en"
	}],
	"segmentLength": 1.198,
	"segmentLengtUnit": "mi",
	"timeTaken": 1.433,
	"timeUnit": "min",
	"turnAngle": 0.0,
	"turnAngleUnit": "degree",
	"compassDirection": "",
	"speedOfTravel": 49.9955,
	"speedOfTravelUnit": "mph",
	"roadType": "major road rural",
	"segmentDirection": "bidirectional",
	"startJunctionType": "Other",
	"endJunctionType": "",
	"isRoundabout": false,
	"isTollRoad": false,
	"pointsInSegment": {
		"type": "LineString",
		"crs": {
			"type": "name",
			"properties": {
				"name": "epsg:4326"
			}
		},
		"coordinates": [[…]]
	}
}]

Return segment data specifying a segmentID.

http://<server>:<port>/rest/Spatial/erm/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>/rest/Spatial/erm/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>/rest/Spatial/erm/databases/usroutedatabase.json?version=2
  • Response: 
    {"errors": [{
	"errorCode": 4139,
	"userMessage": "Point cannot be empty."
}]}