Referent To Geometry—ArcGIS REST APIs

URL:https://<network-layer-url>/referentToGeometry
Version Introduced:11.2

Description

License:

The ArcGIS Pipeline Referencing license is required to use this resource.

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
location	A list of referent values used to convert to geometry. Syntax [ { "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 parameter. 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 parameter. The time instant to use as a temporal view date when locating route features. The parameter value is a number that represents the number of milliseconds since epoch (January 1, 1970) in UTC. Syntax: temporalViewDate=<timeInstant> Example: temporalViewDate=1230768000000 (1 Jan 2009 00:00:00 GMT)
outSR	Optional parameter. 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 parameter to specify the geodatabase version to use. If this parameter is not specified, the published map's version is used. Syntax: gdbVersion=<version> Example: gdbVersion="user1.version1"
f	Optional parameter to specify the response format. The default response format is html. Values: html \| json

Example usage

Example 1

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

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:

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:

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;

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:

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

{
  {
    "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:

{
  {
    "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}
          }
        ]
      }
    ]
  }
}

ArcGIS REST APIs