Geometry To Referent

URL:: https://<network-layer-url>/geometryToReferent
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 coordinate locations or route and measure inputs along a route into a referent and offset value.

A status message is returned indicating success or 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.
`esriLocatingReferentOffsetSpansGap`	The offset value found spans across a gap.

Request parameters

Parameter Details

Parameter	Details
`f` (Optional)	Specifies the response format. The default response format is `html`. Values: `html` \| `json` \| `pjson`
`location`	A list of geometries used to convert to referent and offset values. Syntax: Use dark colors for code blocksCopy `1 2 3 4 5 6 7 8 9 10 11 12 [ { "layerId": <layerId1>, "geometry": { "x": <x1>, "y": <y1>, "z": <z1> } }, { "layerId": <layerId2>, "routeId": "<routeId2>", "measure": <measure2> // in network units }, ... ]`
`outOffsetUnit` (Optional)	Specifies the unit used for output offset values. If this parameter is not specified, the network units are used to return the referent offset value. Values: `esriInches` \| `esriFeet` \| `esriYards` \| `esriMiles` \| `esriNauticalMiles` \| `esriMillimeters` \| `esriCentimeters` \| `esriMeters` \| `esriKilometers` \| `esriDecimalDegrees` \| `esriDecimeters` \| `esriIntInches` \| `esriIntFeet` \| `esriIntYards` \| `esriIntMiles` \| `esriIntNauticalMiles`
`referentSelectionType` (Optional)	Specifies how the referent will be selected along a route. `closest` selects the closest referent in the layer irrespective of whether it's upstream or downstream of the location. `nearestUpstream` selects the nearest referent that is upstream of the provided location. This ensures that the referent selected is always upstream of the location and ensures a positive offset. The default is `closest`. Values: `closest` \| `nearestUpstream`
`featureIdFieldName` (Optional)	A field of the referent layer returned by the REST endpoint instead of the default ObjectID. Syntax: Use dark colors for code blocksCopy `1 featureIdFieldName=<fieldName>` Example: Use dark colors for code blocksCopy `1 featureIdFieldName="RouteName"`
`tolerance` (Optional)	The maximum distance in map units to snap a point to the closest location on a nearby route. If a point is farther than the tolerance from a route, a message is returned stating that the point can't be located.
`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)`
`inSR` (Optional)	The spatial reference of the input geometry. The spatial reference can be specified as either a Well-Known ID (WKID) or a spatial reference JSON object. If `inSR` is not specified, the geometry is assumed to be in the spatial reference of the map.
`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 geometries used to convert to referent and offset values.

Syntax:

Use dark colors for code blocksCopy
[
  {
    "layerId": <layerId1>,
    "geometry": { "x": <x1>, "y": <y1>, "z": <z1> }
  },
  {
    "layerId": <layerId2>,
    "routeId": "<routeId2>",
            "measure": <measure2>  // in network units
  },
  ...
]

outOffsetUnit

(Optional)

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

referentSelectionType

(Optional)

Specifies how the referent will be selected along a route. closest selects the closest referent in the layer irrespective of whether it's upstream or downstream of the location. nearestUpstream selects the nearest referent that is upstream of the provided location. This ensures that the referent selected is always upstream of the location and ensures a positive offset. The default is closest.

Values: closest | nearestUpstream

featureIdFieldName

(Optional)

A field of the referent layer returned by the REST endpoint instead of the default ObjectID.

Syntax:

Use dark colors for code blocksCopy
featureIdFieldName=<fieldName>

Example:

Use dark colors for code blocksCopy
featureIdFieldName="RouteName"

tolerance

(Optional)

The maximum distance in map units to snap a point to the closest location on a nearby route. If a point is farther than the tolerance from a route, a message is returned stating that the point can't be located.

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)

inSR

(Optional)

The spatial reference of the input geometry.

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

If inSR is not specified, the geometry is assumed to be in the spatial reference of the map.

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"

Example usage

Example 1

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

Use dark colors for code blocksCopy
http://sampleserver/arcgis/rest/services/MyLRS/MapServer/exts/LRSServer/networkLayers/1/geometryToReferent?f=json&locations=[{"layerId":2,"geometry":{"x":260631,"y":-437080}}]&offsetUnit=esriMeters&referentSelectionType=”nearestUpstream”&featureIdFieldName=”EventId”&outSR=3310

Example 2

The following is a URL for converting multiple geometries to referents and offsets:

Use dark colors for code blocksCopy
http://sampleserver/arcgis/rest/services/MyLRS/MapServer/exts/LRSServer/networkLayers/1/geometryToReferent?f=json&locations=[{"layerId":2,"geometry":{"x":260631,"y":-437080}},{"layerId":2,"geometry":{"x":260639,"y":-437080}}]&offsetUnit=esriFeet&outSR=3310

JSON Response syntax

Use dark colors for code blocksCopy
{
  {
    "offsetUnit": "<units>",
    "distanceUnit": "<units>",
    "spatialReference": "<spatialReference>",
    "locations": [
      {
        "status": "<status1>",
        "results": [
          {
            "objectId": "<objectId1>",
            "featureId": "<featureId1>",
            "offset": "<offset1>",
            "routeId": "<routeId1>",
            "distance": <distance1>,
            "geometryType": "esriGeometryPoint",
	          "geometry": { "x": <x>, "y": <y>, "z": <z> }
          },
          ...
        ]
      },
      {
        "status": "<status2>",
        "results": [
          {
            "objectId": "<objectId2>",
            "featureId": "<featureId2>",
            "offset": "<offset2>",
            "routeId": "<routeId2>",
            "distance": <distance2>,
            "geometryType": "esriGeometryPoint",
	          "geometry": { "x": <x>, "y": <y>, "z": <z> }
          },
          ...
        ]
      },
      ...
  }
}

JSON Response example

The following is an example of a successful response:

Use dark colors for code blocksCopy
{
 "offsetUnit": "esriMeters",
 "distanceUnit": "esriMeters",
 "spatialReference": {
  "wkid": 3310
 },
 "locations": [
  {
   "status": "esriLocatingOK",
   "results": [
    {
     "objectId": 1317,
     "featureId": "Event17",
     "offset": -3,
     "routeId": "R10",
     "distance": 0,
     "geometryType": "esriGeometryPoint",
     "geometry": {
      "x": 260675,
      "y": -437072,
      "z": 0
     }
    }
   ]
  }
 ]
}```