Join Features

Join Features

The Join Features task works with two layers and joins the attributes from one feature to another based on spatial and attribute relationships.

Request URL

http://<analysis url>/JoinFeatures/SubmitJob

Request Parameters

ParameterDescription

targetLayer

(Required)

The point, line, polygon or table layer that will have attributes from the joinLayer appended to its table.

Syntax: As described in detail in the Feature Input topic, this parameter can be

  • a URL to a feature service layer with an optional filter to select specific features, or
  • a feature collection.

Examples:

  • {"url": <feature service layer url>, "filter": <where clause>}
  • {"layerDefinition": {}, "featureSet": {}, "filter": <where clause>}

joinLayer

Required

The point, line, polygon or table layer that will be joined to the targetLayer.

Syntax: As described in detail in the Feature Input topic, this parameter can be

  • a URL to a feature service layer with an optional filter to select specific features, or
  • a feature collection.

spatialRelationhip

Defines the spatial relationship used to spatially join features.

Values: Identical to | Intersects | Completely contains | Completely within | Within a distance of.

Examples:

  • "spatialRelationship" : "identicalto"
  • "spatialRelationship" : "intersects"
  • "spatialRelationship" : "completelycontains"
  • "spatialRelationship" : "completelywithin"
  • "spatialRelationship" : "withindistance "

spatialRelationhipDistance

(Required if spatialRelationship is withindistance)

A double value used for the search distance to determine if the targetFeatures are near or within a specified distance of the joinFeatures. This is only applied if Within a distance of is the selected spatialRelationship. You can only enter a single distance value. The units of the distance values are supplied by the spatialRelationshipDistanceUnits parameter.

Examples:

  • "spatialNearDistance" : 4
  • "spatialNearDistance" : 53.4

spatialRelationhipDistanceUnits

(Required if spatialRelationship is withindistance)

The linear unit to be used with the distance value specified in spatialRelationshipDistance.

Values: Miles | Yards | Feet | NauticalMiles | Meters | Kilometers

The default is Miles.

Example: "spatialRelationshipDistanceUnits" : "Meters"

attributeRelationhip

Defines an attribute relationship used to join features. Features are matched when the field values in the join layer are equal to field values in the target layer.

Syntax: attributeRelationship: [{"targetField":"target fieldname","operator":"equal","joinField":"join fieldname"}]

Examples:

  • [{"targetField":"ZipArea","operator":"equal","joinField":"ZipCode"}]
  • [{"targetField":"ownerID","operator":"equal","joinField":"InsuranceClaim"}]

joinOperation

Required

A string representing the type of join that will be applied.

Syntax: JoinOneToOne | JoinOneToMany.

  • JoinOneToOne—If multiple join features are found that have the same relationships with a single target feature, the attributes from the multiple join features will be aggregated using the specified summary statistics. For example, if a point target feature is found within two separate polygon join features, the attributes from the two polygons will be aggregated before being transferred to the output point feature class. If one polygon has an attribute value of 3 and the other has a value of 7, and a SummaryField of sum is selected, the aggregated value in the output feature class will be 10. There will always be a Count field calculated, with a value of 2, for the number of features specified. This is the default.
  • JoinOneToMany—If multiple join features are found that have the same relationship with a single target feature, the output feature class will contain multiple copies (records) of the target feature. For example, if a single point target feature is found within two separate polygon join features, the output feature class will contain two copies of the target feature: one record with the attributes of the first polygon, and another record with the attributes of the second polygon. There are no summary statistics calculated with this method.

Note:
Adding summary statistics is not supported for JoinOneToMany operations.

Example: "joinOperation" : "JoinOneToMany"

summaryFields

A list of field names and statistical summary types that you want to calculate. Note that the count is always returned by default.

Syntax: [{"statisticType":"<statistic type","onStatisticField":"<fieldName>"}, ...]

fieldName is the name of one of the numeric fields found in the input join layer.

statisticType is one of the following:

  • SUM—Adds the total value of all the points in each polygon
  • MEAN—Calculates the average of all the points in each polygon
  • MIN—Finds the smallest value of all the points in each polygon
  • MAX—Finds the largest value of all the points in each polygon
  • STDDEV—Finds the standard deviation of all the points in each polygon

Example: [{"statisticType":"MEAN","onStatisticField":"Total_Sales"}]

OutputName

If provided, the task will create a feature service of the results. You define the name of the service. If outputName is not supplied, the task will return a feature collection.

Syntax:
{
  "serviceProperties": {
    "name": "<service name>"
  }
}

Context

Context contains additional settings that affect task execution. For Join Features, there are the following two settings:

  • Extent (extent)—A bounding box that defines the analysis area. Only those features in the input layer that intersect the bounding box will be buffered.
  • Output Spatial Reference (outSR)—The output features will be projected into the output spatial reference.

Syntax:

{
"extent" : {extent}
"outSR" : {spatial reference}
}

f

The response format. The default response format is html.

Values: html | json | kmz

Response

When you submit a request, the service assigns a unique job ID for the transaction.

Syntax:

{
"jobId": "<unique job identifier>",
"jobStatus": "<job status>"
}

After the initial request is submitted, you can use the jobId to periodically check the status of the job and messages as described in Checking job status. Once the job has successfully completed, use the jobId to retrieve the results. To track the status, you can make a request of the following form:

http://<analysis url>/JoinFeatures/jobs/<jobId>

Accessing results

When the status of the job request is esriJobSucceded, you can access the results of the analysis by making a request of the following form:

http://<analysis url>/JoinFeatures/jobs/<jobId>/results/outputLayer?token=<your token>&f=json

ParameterDescription

outputLayer

The outputLayer will have the same geometry as the targetLayer.

The targetLayer will inherit all the attributes of the joined joinLayer. If a JoinOneToOne was applied, the output will have a Count attribute, which is the number of features that matched the join conditions. If a summaryFields parameter is specified in the task request, the layer will have additional attributes for each requested summary. For example, if you had requested:

[{"statisticType":"SUM","onStatisticField":"Total_Sales"},{"statisticType":"MEAN","onStatisticField":"Total_Sales"}]

The result polygon features would have two attributes, Sum_Total_Sales and Mean_Total_Sales, to contain the calculated values.

If a JoinOneToMany was applied, the output will have each pair of joined features.

Example:

{"url": 
"http://<analysis url>/JoinFeatures/jobs/<jobId>/results/outputLayer"}

The result has properties for parameter name, data type, and value. The contents of value depend on the OutputName parameter provided in the initial request.

  • If OutputName was provided, value contains the URL to the feature service layer.

    {
    "paramName":"output", 
    "dataType":"GPString",
    "value":{"url":"<hosted featureservice layer url>"}
    }

  • If OutputName was not provided, value contains a feature collection.

    {
    "paramName":"output",
    "dataType":"GPString",
    "value":{"layerDefinition": {}, "featureSet": {}  }
    }

See Feature Output for more information about how the result layer or collection is accessed.