FRAMES | NO FRAMES Description | Parameters | Examples | Response
Relation (Operation)
URL http://<geometryservice-url>/relation
Parent Resource Geometry Service

Note: The Relation operation was added at 9.3 SP1.

Description

The relation operation is performed on a geometry service resource. This operation determines the pairs of geometries from the input geometry arrays that participate in the specified spatial relation.

This operation computes the set of pairs of geometries from geometries1 and geometries2 that belong to the specified relation. Both arrays are assumed to be in the spatial reference specified by sr, which is a required parameter. The relations are evaluated in 2D. Z coordinates are not used. Geometry types cannot be mixed within an array.

From 10.1 onwards this operation will call Simplify on the input geometries1 and geometries2.

You can provide arguments to the relation operation as query parameters defined in the parameters table below.

Parameters

Parameter Details
f Description: The response format. The default response format is html.

Values: html | json
geometries1 Description: The first array of geometries to compute the relations. The structure of each geometry in the array is same as the structure of the json geometry objects returned by the ArcGIS REST API.

Syntax and Examples:

JSON Structures:

Syntax:
{
"geometryType" : "<esriGeometryPoint | esriGeometryMultipoint | esriGeometryPolyline | esriGeometryPolygon | esriGeometryEnvelope>"
"geometries" : [ <geometry1>, <geometry2> ]
}

The "geometries1" property is an array of input geometries. All geometries in this array should be of the type defined by "geometryType".

Example:
{
"geometryType" : "esriGeometryPoint",
"geometries" : [
{"x" : -104.53, "y" : 34.74},
{"x" : -63.53, "y" : 10.23}
]
}

URL based:

For a large set of geometries, you can specify a URL to the input geometries stored in a JSON structure in a file on a public server. The expected format of the file’s contents will be exactly the same as that expected if the geometries were directly embedded in the request.

Syntax: geometries1={ "url" : "<URL to file>" }
Example: geometries1={ "url" : "http://myserver/mygeometries/afile.txt" }

geometries2 Description: The second array of geometries to compute the relations. The structure of each geometry in the array is same as the structure of the json geometry objects returned by the ArcGIS REST API.

Syntax and Examples:

JSON Structures:

Syntax:
{
"geometryType" : "<esriGeometryPoint | esriGeometryMultipoint | esriGeometryPolyline | esriGeometryPolygon | esriGeometryEnvelope>",
"geometries" : [ <geometry1>, <geometry2> ]
}

The "geometries2" property is an array of input geometries. All geometries in this array should be of the type defined by "geometryType".

Example:
{
"geometryType" : "esriGeometryPoint",
"geometries" : [
{"x" : -104.53, "y" : 34.74},
{"x" : -63.53, "y" : 10.23}
]
}

URL based:

For a large set of geometries, you can specify a URL to the input geometries stored in a JSON structure in a file on a public server. The expected format of the file’s contents will be exactly the same as that expected if the geometries were directly embedded in the request.

Syntax: geometries2={ "url" : "<URL to file>" }
Example: geometries2={ "url" : "http://myserver/mygeometries/afile.txt" }

sr Description: The well-known ID of the spatial reference or a spatial reference json object for the input geometries. For a list of valid WKID values, see Projected coordinate Systems and Geographic coordinate Systems.
relation Description: The spatial relationship to be tested between the two input geometry arrays.

Values: esriGeometryRelationCross | esriGeometryRelationDisjoint | esriGeometryRelationIn | esriGeometryRelationInteriorIntersection | esriGeometryRelationIntersection | esriGeometryRelationLineCoincidence | esriGeometryRelationLineTouch | esriGeometryRelationOverlap | esriGeometryRelationPointTouch | esriGeometryRelationTouch | esriGeometryRelationWithin | esriGeometryRelationRelation

Note that if the relation is specified as esriGeometryRelationRelation, the relationParam parameter describes the spatial relationship and must be specified.
relationParam Description: The 'Shape Comparison Language' string to be evaluated. Strings such as RELATE(G1, G2, "FFFTTT***") are accepted, in addition to other kinds of strings.

This string describes the spatial relationship to be tested when the relation parameter is specified as esriGeometryRelationRelation.

See the following EDN topic for more details on the Shape Comparison Language.

Example Usage

Example 1: This example determines which of the 2 input points lie within the input polygon:

http://sampleserver1.arcgisonline.com/arcgis/rest/services/Geometry/GeometryServer/relation?
sr=4326&
relation=esriGeometryRelationWithin&
geometries1={"geometryType" : "esriGeometryPoint","geometries" : [{"x":-104.53,"y":34.74},{"x":-63.53,"y":10.23}]}&
geometries2={"geometryType" : "esriGeometryPolygon","geometries" : [{"rings":[[[-105,34],[-104,34],[-104,35],[-105,35],[-105,34]]]}]}

Example 2: Example using a Shape Comparison Language string (relationParam):

http://sampleserver1.arcgisonline.com/arcgis/rest/services/Geometry/GeometryServer/relation?
sr=104000&geometries1={"geometryType" : "esriGeometryPoint","geometries" : [{"x" : -72.9676788799999,"y" : 44.231699167}, {"x" : -71.3731490419999,"y" : 42.8930815260001},{"x" : -71.3731490419999,"y" : 43.3655348110001},{"x" : -70.6054124539999,"y" : 43.3655348110001}]}
&geometries2={"geometryType" : "esriGeometryPoint","geometries" : [{"x" : -71.3731490419999,"y" : 43.3655348110001},{"x" : -70.6054124539999,"y" : 43.3655348110001}]}
&relation=esriGeometryRelationRelation&relationParam=RELATE(G1,G2,'tfffffff*')&f=html

JSON Response Syntax

{
  "relations" : [
    { "geometry1Index" : <geometry1Index1>, "geometry2Index" : <geometry2Index1> },
    { "geometry1Index" : <geometry1Index2>, "geometry2Index" : <geometry2Index2> }
  ]
}

JSON Response Example

{
  "relations" : [
    { "geometry1Index" : 0, "geometry2Index" : 1 },
    { "geometry1Index" : 1, "geometry2Index" : 1 }
  ]
}