Find Similar Locations

inputLayer (Required)

The inputLayer contains one or more reference locations against which features in the searchLayer will be evaluated for similarity. For example, the inputLayer might contain your top performing stores or the villages hardest hit by a disease. For more information on inputLayer and searchLayer, see below.

Syntax: As described in Feature input, this parameter can be one of the following:

• A URL to a feature service layer with an optional filter to select specific features
• A URL to a big data catalog service layer with an optional filter to select specific features
• A feature collection

REST examples

1
2
3
4
5
//REST web example
{"url": "https://organization.example.com/<context>/rest/services/Hosted/hurricaneTrack/FeatureServer/0", "filter": "Month = 'September'"}

//REST scripting example
"inputLayer": {"url": "https://organization.example.com/<context>/rest/services/Hosted/hurricaneTrack/FeatureServer/0", "filter": "Month = 'September'"}

searchLayer (Required)

The layer containing candidate locations that will be evaluated against the reference locations. For more information on inputLayer and searchLayer, see below.

Syntax: As described in Feature input, this parameter can be one of the following:

• A URL to a feature service layer with an optional filter to select specific features
• A URL to a big data catalog service layer with an optional filter to select specific features
• A feature collection

REST examples

1
2
3
4
5
//REST web example
{"url":"https://organization.example.com/<context>/rest/services/Hosted/hurricaneTrack/FeatureServer/0", "filter": "Month = 'September'"}

//REST scripting example
"searchLayer": {"url":"https://organization.example.com/<context>/rest/services/Hosted/hurricaneTrack/FeatureServer/0", "filter": "Month = 'September'"}

analysisFields (Required)

A list of fields whose values are used to determine similarity. They must be numeric fields, and the fields must exist on both the inputLayer and the searchLayer. Depending on the matchMethod selected, the task will find features that are most similar based on values or profiles of the fields.

REST examples

1
2
3
4
5
//REST web example
CrimeRate, Beat

//REST scripting example
"analysisFields": "CrimeRate, Beat"

mostOrLeastSimilar (Required)

The features you want to be returned. You can search for features that are either most similar or least similar to the inputLayer, or search both the most and least similar.

Values: MostSimilar | LeastSimilar | Both

REST examples

1
2
3
4
5
//REST web example
LeastSimilar

//REST scripting example
"mostOrLeastSimilar": "MostSimilar"

matchMethod (Required)

The method that specifies how matching is determined. The AttributeValues method uses the squared differences of standardized values. This is the default. The AttributeProfiles method uses cosine similarity mathematics to compare the profile of standardized values. Using AttributeProfiles requires the use of at least two analysis fields.

Values: AttributeValues | AttributeProfiles

REST examples

1
2
3
4
5
//REST web example
AttributeValues

//REST scripting example
"matchMethod": "AttributeProfiles"

numberOfResults (Required)

The number of ranked candidate locations output to similarResultLayer. If numberOfResults is not set, the 10 locations will be returned. The maximum number of results is 10000.

REST examples

1
2
3
4
5
//REST web example
15

//REST scripting example
"numberOfResults": 15

appendFields (Optional)

Add fields to your data from your search layer. By default, all fields from the search layer are appended.

REST examples

1
2
3
4
5
//REST web example
ID Number

//REST scripting example
"appendFields": "ID Number"

outputName (Required)

The task will create a feature service of the results. You define the name of the service.

REST examples

1
2
3
4
5
//REST web example
myOutput

//REST scripting example
"outputName": "myOutput"

context (Optional)

The context parameter contains additional settings that affect task execution. For this task, there are four settings:

• Extent (extent )—A bounding box that defines the analysis area. Only those features that intersect the bounding box will be analyzed.
• Processing spatial reference (processSR )—The features will be projected into this coordinate system for analysis.
• Output spatial reference (outSR )—The features will be projected into this coordinate system after the analysis to be saved. The output spatial reference for the spatiotemporal big data store is always WGS84.
• Data store (dataStore )—Results will be saved to the specified data store. The default is the spatiotemporal big data store.

Syntax:

1
2
3
4
5
6
{
  "extent": {extent},
  "processSR": {spatial reference},
  "outSR": {spatial reference},
  "dataStore": {data store}
}

f

The response format. The default response format is html .

Values: html | json | pjson

output

Contains features from the inputLayer and the searchLayer. The number of features from the searchLayer is based on the value of the numberOfResults parameter. Fields added to outputName include all the fields from the searchLayer and the following:

• location_type —A string denoting if the feature was an input reference location or a search location.
• simrank —The similarity rank. Contains the rank for search locations, where 1 equals the candidate location most similar to the reference locations. Contains zero for reference locations.
• dissimrank —The dissimilarity rank. Contains the rank for search locations, where -1 equals the candidate location most dissimilar to the reference locations. Contains zero for reference locations.
• simindex —Quantifies how similar a candidate is compared to the reference locations. If a candidate location matches a reference location exactly, the value is zero. The larger the value, the more dissimilar a candidate is from the reference locations.
• cosimindex —Quantifies how similar a candidate's profile is compared to the reference location's profile. If the profile of a candidate location matches the profile of a reference location exactly, the value is zero. The larger the value, the more dissimilar a candidate is from the reference locations.
• labelrank —Used for labelling and rendering the outputs. The higher the values, the more similar; the lower the values, the more dissimilar. Values of 0 represent the reference locations.
• reference_id — A unique ID value for reference features. Search features are given a null value.
• search_id — A unique ID value for search value features. Reference features are given a null value.

1
{"url": "https://<analysis-url>/FindSimilarLocations/jobs/<jobId>/results/output"}

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. The value contains the URL of the feature service layer.

1
2
3
4
5
{
  "paramName": "output",
  "dataType": "GPRecordSet",
  "value":{"url": "<hosted featureservice layer url>"}
}

See Feature output for more information about how the result layer is accessed.

processInfo

The processInfo parameter contains strings that summarize the Find Similar Locations result. These strings are used for reporting by the Find Similar Locations tool found in Map Viewer Classic. You can create your own custom reports for your application using these strings. There are four parts in the returned json:

• messageCode —The serial number for each unique message.
• message —Text that may or may not contain parameters (in ${paramsName} format) that need to be replaced by values.
• params —A dictionary of the keys and values to be inserted into the ${paramsName} parameter in the message.
• style —The formatting of the report produced by the Find Similar Locations tool in Map Viewer Classic.

1
2
3
4
5
6
{
"messageCode" : "SS_84507",
"message" : ["Attribute", "Min", "Max", "SD", "Mean","Input"],
"params" : {},
"style" : "<table><tr><th></th><th></th><th></th><th></th><th></th><th></th></tr>"
}