Referent To Geometry

URL:: https://<network-layer-url>/referentToGeometry
Methods:: GET
Required Capability:: The ArcGIS Location Referencing license is required to use this resource.
Version Introduced:: 11.2

Description

This operation converts one or more point referent locations into geographic locations along a set of routes.

A status message is returned indicating success or more details on why the conversion failed.

Status messages

The following table contains an enumeration of the possible locating statuses:

Status	Description
`esriLocatingOK`	Locating was successful.
`esriLocatingMultipleLocation`	Locating was successful and the input point was located on more than one route.
`esriLocatingCannotFindRoute`	The route does not exist.
`esriLocatingRouteShapeEmpty`	The route does not have a shape or the shape is empty.
`esriLocatingRouteMeasuresNull`	The route does not have measures or the measures are null.
`esriLocatingRouteNotMAware`	The route is not an m-aware polyline.
`esriLocatingCannotFindLocation`	The route location's shape cannot be found because the route has no measures or the route location's measures do not exist on the route.
`esriLocatingFromPartialMatch`	The route location's shape cannot be found because the from offset is outside of the route measure range.
`esriLocatingToPartialMatch`	The route location's shape cannot be found because the to offset is outside of the route measure range.
`esriLocatingInvalidOID`	The input object Id does not exist or is invalid.
`esriLocatingInvalidOffset`	The input offset value is invalid.

Request parameters

Parameter Details

Parameter	Details
`location`	A list of referent values used to convert to geometry. Syntax: Use dark colors for code blocksCopy 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 [ { "geometry": {"x": <x1>,"y": <y1>,"z": <z1>}, "offset": <offset1> }, { "geometry": {"x" :<x2>, "y": <y2>,"z": <z2>}, "fromOffset": <fromOffset2>, "toOffset": <toOffset2> }, { "fromGeometry": {"x": <x3>,"y": <y3>,"z": <z3>}, "toGeometry": {"x": <x4>,"y": <y4>,"z": <z4>}, "fromOffset": <fromOffset3>, "toOffset": <toOffset3> }, { "layerId": <layerId4>, "objectId": <objectId4>, "offset": <offset4> }, { "layerId": <layerId5>, "objectId": <objectId5>, "fromOffset": <fromOffset5>, "toOffset": <toOffset5> }, { "layerId": <layerId6>, "fromObjectId": <fromObjectId6>, "fromOffset": <fromOffset6>, "toObjectId": <toObjectId6>, "toOffset": <toOffset6> }, ... ]
`offsetUnit` (Optional)	Specifies the unit used for offset values. If this parameter is not specified, the network units are used to calculate the referent offset value. Values: `esriInches` \| `esriFeet` \| `esriYards` \| `esriMiles` \| `esriNauticalMiles` \| `esriMillimeters` \| `esriCentimeters` \| `esriMeters` \| `esriKilometers` \| `esriDecimalDegrees` \| `esriDecimeters` \| `esriIntInches` \| `esriIntFeet` \| `esriIntYards` \| `esriIntMiles` \| `esriIntNauticalMiles`
`temporalViewDate` (Optional)	The time instant to use as a temporal view date when locating route features. If this parameter is not specified, the current date is used. The parameter value is a number that represents the number of milliseconds since epoch (January 1, 1970) in UTC. Syntax: Use dark colors for code blocksCopy `1 temporalViewDate=<timeInstant>` Example: Use dark colors for code blocksCopy `1 temporalViewDate=1230768000000 (1 Jan 2009 00:00:00 GMT)`
`outSR` (Optional)	The spatial reference of the returned geometry. The spatial reference can be specified as either a Well-Known ID (WKID) or a spatial reference JSON object. If `outSR` is not specified, the output geometries are in the spatial reference specified by `inSR`. If `inSR` is also not specified, the output geometries are in the spatial reference of the map.
`gdbVersion` (Optional)	Specifies the geodatabase version to use. If this parameter is not specified, the published map's version is used. Syntax: Use dark colors for code blocksCopy `1 gdbVersion=<version>` Example: Use dark colors for code blocksCopy `1 gdbVersion="user1.version1"`
`f` (Optional)	Specifies the response format. The default response format is `html`. Values: `html` \| `json` \| `pjson`

location

A list of referent values used to convert to geometry.

Syntax:

Use dark colors for code blocksCopy
[
  {
    "geometry": {"x": <x1>,"y": <y1>,"z": <z1>},
    "offset": <offset1>
  },
  {
    "geometry": {"x" :<x2>, "y": <y2>,"z": <z2>},
    "fromOffset": <fromOffset2>,
    "toOffset": <toOffset2>
  },
  {
    "fromGeometry": {"x": <x3>,"y": <y3>,"z": <z3>},
    "toGeometry": {"x": <x4>,"y": <y4>,"z": <z4>},
    "fromOffset": <fromOffset3>,
    "toOffset": <toOffset3>
  },
  {
    "layerId": <layerId4>,
    "objectId": <objectId4>,
    "offset": <offset4>
  },
  {
    "layerId": <layerId5>,
    "objectId": <objectId5>,
    "fromOffset": <fromOffset5>,
    "toOffset": <toOffset5>
  },
  {
    "layerId": <layerId6>,
    "fromObjectId": <fromObjectId6>,
    "fromOffset": <fromOffset6>,
    "toObjectId": <toObjectId6>,
    "toOffset": <toOffset6>
  },
  ...
]

offsetUnit

(Optional)

Specifies the unit used for offset values. If this parameter is not specified, the network units are used to calculate the referent offset value.

temporalViewDate

(Optional)

The time instant to use as a temporal view date when locating route features. If this parameter is not specified, the current date is used.

The parameter value is a number that represents the number of milliseconds since epoch (January 1, 1970) in UTC.

Syntax:

Use dark colors for code blocksCopy
temporalViewDate=<timeInstant>

Example:

Use dark colors for code blocksCopy
temporalViewDate=1230768000000 (1 Jan 2009 00:00:00 GMT)

outSR

(Optional)

The spatial reference of the returned geometry.

The spatial reference can be specified as either a Well-Known ID (WKID) or a spatial reference JSON object.

If outSR is not specified, the output geometries are in the spatial reference specified by inSR. If inSR is also not specified, the output geometries are in the spatial reference of the map.

gdbVersion

(Optional)

Specifies the geodatabase version to use. If this parameter is not specified, the published map's version is used.

Syntax:

Use dark colors for code blocksCopy
gdbVersion=<version>

Example:

Use dark colors for code blocksCopy
gdbVersion="user1.version1"

f

(Optional)

Specifies the response format. The default response format is html.

Values: html | json | pjson

Example usage

Example 1

The following is a URL for converting a single referent to point geometry:

Use dark colors for code blocksCopy
https://sampleserver/arcgis/rest/services/MyLRS/MapServer/exts/LRSServer/networkLayers/1/referentToGeometry?f=json&locations=[{"layerId":2,"objectId":201,"offset":1.4}]&offsetUnit=esriMile&outSR=102100

Example 2

The following is a URL for converting a referent range to line geometry:

Use dark colors for code blocksCopy
https://sampleserver/arcgis/rest/services/MyLRS/MapServer/exts/LRSServer/networkLayers/1/referentToGeometry?f=json&locations=[{"layerId":2,"objectId":201,"fromOffset":-0.5,"toOffset":0.4}]&offsetUnit=esriMile&outSR=102100

Example 3

The following is a URL for converting multiple referents to point geometry:

Use dark colors for code blocksCopy
https://sampleserver/arcgis/rest/services/MyLRS/MapServer/exts/LRSServer/networkLayers/1/referentToGeometry?f=json&locations=[{"layerId":2,"objectId":201,"offset":1.4},{"layerId":2,"objectId":202,"offset":-0.9},{"layerId":3,"objectId":1301,"offset":0.4}]&offsetUnit=esriMile&outSR=102100

Example 4

The following is a URL for converting multiple referents and referent ranges to point and line geometry;

Use dark colors for code blocksCopy
https://sampleserver/arcgis/rest/services/MyLRS/MapServer/exts/LRSServer/networkLayers/1/referentToGeometry?f=json&locations=[{"layerId":2,"objectId":201,"fromOffset":-0.5,"toOffset":0.4},{"layerId":2,"objectId":1404,"offset":9.4}]&offsetUnit=esriMile&outSR=102100

Example 5

The following is a URL for converting a referent range that spans different routes on the same line to line geometry:

Use dark colors for code blocksCopy
https://sampleserver/arcgis/rest/services/MyLRS/MapServer/exts/LRSServer/networkLayers/1/referentToGeometry?f=json&locations=[{"layerId":2,"fromObjectId":201,"fromOffset":-0.5,"toObjectId":203,"toOffset":0.4}]&offsetUnit=esriMile&outSR=102100

JSON Response syntax

Use dark colors for code blocksCopy
{
  {
    "unitsOfMeasure": "<units>",
    "spatialReference": "<spatialReference>",
    "locations": [
      {
        "status": "<status1>",
        "results": [
          {
            "routeId": "<routeId1>",
            "measure": <measure1>,
            "geometryType": "<geometryType1>",
	           "geometry": {"x": <x>,"y": <y>,"z": <z>,"m": <m>} // syntax for point geometry
          },
          ...
        ]
      },
      {
        "status": "<status2>",
        "results": [
          {
            "routeId": "<routeId2>",
            "measure": <measure2>,
            "toMeasure": <toMeasure2>,
            "geometryType": "<geometryType2>",
	           "geometry": {"paths": [[[<x1>,<y1>,<z1>,<m1>],[<x2>,<y2>,<z2>,<m2>], ...]]} // syntax for line geometry
          },
          ...
        ]
      },
	     {
        "status": "<status3>",
        "results": [
          {
            "routeId": "<routeId3>",
            "measure": <measure3>,
            "toRouteId": "<toRouteId3>",
	           "toMeasure": <toMeasure3>,
            "geometryType": "<geometryType3>",
	           "geometry": {"paths": [[[<x1>,<y1>,<z1>,<m1>],[<x2>,<y2>,<z2>,<m2>], ...]]} // syntax for line geometry that spans multiple routes
          },
          ...
        ]
      },
      ...
    ]
  }
}

JSON Response example

The following is an example of a successful response:

Use dark colors for code blocksCopy
{
  {
    "unitsOfMeasure": "esriMiles",
    "spatialReference": {"wkid": 102100},
    "locations": [
      {
        "status": "esriLocatingOK",
        "results": [
          {
            "routeId": "I90",
            "measure": "17.146",
            "geometryType": "esriGeometryPoint",
            "geometry": {"x": -8479118.349,"y": 5326520.134,"z": 0.1,"m": 17.146}
          }
        ]
      }
    ]
  }
}