Find Similar Locations

Find Similar Locations

The Find Similar Locations task measures the similarity of candidate locations to one or more reference locations.

Based on criteria you specify, Find Similar Locations can answer questions such as the following:

  • Which of your stores are most similar to your top performers with regard to customer profiles?
  • Based on characteristics of villages hardest hit by the disease, which other villages are high risk?

To answer questions such as these, you provide the reference locations (the inputLayer parameter), the candidate locations (the searchLayer parameter), and the fields representing the criteria you want to match. For example, the inputLayer might be a layer containing your top performing stores or the villages hardest hit by the disease. The searchLayer contains your candidate locations to search. This might be all of your stores or all other villages. Finally, you supply a list of fields to use for measuring similarity. Find Similar Locations will rank all of the candidate locations by how closely they match your reference locations across all of the fields you have selected.

Request URL

http://<analysis url>/FindSimilarLocations/submitJob

Request Parameters

ParameterDescription

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.

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>}

It is not uncommon that the inputLayer and searchLayer are the same feature service. For example, the feature service contains locations of all stores, one of which is your top performing store. If you want to rank the remaining stores from most to least similar to your top performing store, you can provide a filter for both the inputLayer and the searchLayer. The filter on the inputLayer would select the top performing store while the filter on the searchLayer would select all stores except for the top performing store. You can also use the optional inputQuery parameter to specify reference locations.

If there is more than one reference location, similarity will be based on averages for the fields you specify in the analysisFields parameter. So, for example, if there are two reference locations and you are interested in matching population, the task will look for candidate locations in the searchLayer with populations that are most like the average population for both reference locations. If the values for the reference locations are 100 and 102, for example, the task will look for candidate locations with populations near 101. Consequently, you will want to use fields for the reference locations fields that have similar values. If, for example, the population values for one reference location is 100 and the other is 100,000, the tool will look for candidate locations with population values near the average of those two values: 50,050. Notice that this averaged value is nothing like the population for either of the reference locations.

searchLayer

(Required)

The layer containing candidate locations that will be evaluated against the reference locations.

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>}

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. The task will find features in the searchLayer that have field values closest to those of the features in your inputLayer.

Examples:

  • "analysisFields":["value"] (single analysis field)
  • "analysisFields":["pop2010", "pop10_sqmi", "pop2012", "med_age", "households"] (multiple analysis fields)

inputQuery

In the situation where the inputLayer and the searchLayer are the same feature service, this parameter allows you to input a query on the inputLayer to specify which features are the reference locations. The reference locations specified by this query will not be analyzed as candidates. The syntax of inputQuery is the same as a filter.

Examples:

  • "inputQuery":"age_10_14 = 1"] (for numeric field)
  • "inputQuery":"color = 'Green'"] (for text field)

numberOfResults

The number of ranked candidate locations output to the similarResultLayer. If numberOfResults is not specified, or set to zero, all candidate locations will be ranked and output.

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 Find Similar Locations, there are two settings.

  1. Extent (extent)—A bounding box that defines the analysis area. Only those features in the input list inputLayers that intersect the bounding box will be analyzed.
  2. 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

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, you use the jobId to retrieve the results. To track the status, you can make a request in the following form:

http://<analysis url>/FindSimilarLocations/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 in the following form:

http://<analysis url>/FindSimilarLocations/jobs/<jobId>/results/<output parameter name>?token=<your token>&f=json

ParameterDescription

similarResultLayer

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 the similarResultLayer include all the fields from the searchLayer and the following:

  • MATCH_ID—the feature ID of the input reference location. For candidate features, this field will contain null.
  • CAND_ID—the feature ID of the input candidate location. For reference features, this field will contain null.
  • SIMRANK—the similarity rank. Contains the rank for candidate locations, where 1 equals the candidate location most similar 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.
Request example:
{"url": 
"http://<analysis url>/FindSimilarLocations/jobs/<jobId>/results/similarResultLayer"}

The result has properties for parameter name, data type, and value. The contents of value depends upon the outputName parameter provided in the initial request.

  • If outputName was provided, value contains the url to the feature service layer.
    {
    "paramName":"similarResultLayer", 
    "dataType":"GPString",
    "value":{"url":"<hosted featureservice layer url>"}
    }
  • If outputName was not provided, value contains a feature collection.
    {
    "paramName":"similarResultLayer",
    "dataType":"GPString",
    "value":{"layerDefinition": {}, "featureSet": {}}
    }

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

processInfo

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

  1. messageCode—the serial number for each unique message.
  2. message—text which may or may not contain parameters (in ${paramsName} format) that need to be replaced by values.
  3. params—dictionary of the keys and values to be inserted into the ${paramsName} in the message.
  4. style—for formatting of the report produced by the Find Similar Locations tool found in the ArcGIS.com map viewer.
Example:
{
"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>" ,,
}