Find Similar Locations
The FindSimilarLocations task measures the similarity of candidate locations to one or more reference locations.
Based on criteria you specify, FindSimilarLocations 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 value might be a layer containing your top performing stores or the villages hardest hit by the disease. The searchLayer value contains the 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. The FindSimilarLocations task will rank all of the candidate locations by how closely they match the reference locations across all of the fields you selected.
Request URL
http://<analysis url>/FindSimilarLocations/submitJobLimits
The processInfo parameter and pop-ups are not updated by overwriting the output feature layer if the existing output feature layer already has strings for processInfo and custom pop-ups.
Request parameters
| Parameter | Description |
|---|---|
inputLayer (Required) | A layer containing one or more reference locations that will be evaluated for similarity with the searchLayer features. For example, the inputLayer value 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 one of the following:
Examples:
It is not uncommon for the inputLayer and searchLayer values to be the same feature service. For example, the feature service contains locations of all stores, one of which is your top performing store. 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 parameters. The filter for the inputLayer parameter would select the top performing store, and the filter on the searchLayer parameter 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. For example, if there are two reference locations and you are interested in matching population, the task will identify candidate locations in the searchLayer value with populations that are most similar to the average population for both reference locations. If the values for the reference locations are 100 and 102, for example, the task will identify candidate locations with populations near 101. Consequently, you should 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 identify candidate locations with population values near the average of those two values: 50,050. Keep in mind 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 using the reference locations. Syntax: As described in detail in the Feature input topic, this parameter can be one of the following:
Examples:
|
analysisFields | A list of fields whose values will be used to determine similarity. They must be numeric fields and the fields must exist on both the inputLayer and searchLayer values. The task will find features in the searchLayer value that have field values closest to those of the features in the inputLayer value. Either an analysisFields or criteriaFields value must be provided. Examples:
|
inputQuery | When the inputLayer and searchLayer values are the same feature service, this parameter allows you to input a query on the inputLayer value 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:
|
numberOfResults | The number of ranked candidate locations output to the similarResultLayer value. If numberOfResults is not specified or set to zero, all candidate locations will be ranked and output. |
criteriaFields | The fields in the inputLayer value that correspond to the fields in the searchLayer value that will be used to determine similarity. All fields must be numeric fields. The task will rank the features in the searchLayer value based on the similarity of their field values to the corresponding field values in the inputLayer value. Either an analysisFields or criteriaFields value must be provided. This parameter is available in ArcGIS Enterprise 11.2 or higher. Examples:
|
outputName | If provided, the task will create a feature service of the results. You define the name of the service. If an outputName value is not provided, the task will return a feature collection. Syntax: Syntax: |
context | The Context parameter contains the following additional settings that affect task operation:
Syntax: |
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 value to periodically check the status of the job and messages as described in Check job status.
Once the job has successfully completed, you use
the jobId value to retrieve the results. To track the status, you can make a request in the following form:http://<analysis url>/FindSimilarLocations/jobs/<jobId>
Access 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
| Parameter | Description |
|---|---|
similarResultLayer |
A layer that contains features from the inputLayer and searchLayer values. The number of features from searchLayer is based on the value of the numberOfResults parameter. Fields added to the similarResultLayer value include all the fields from the searchLayer value and the following:
Request example: The result has properties for parameter name, data type, and value. The contents of value depend on the outputName value provided in the initial request.
See Feature Output for more information about how the result layer or collection is accessed. |
processInfo |
Contains strings that summarize the task result. These strings are used for reporting by the Find Similar Locations tool in Map Viewer Classic in ArcGIS Online . You can create custom reports for your application using these strings. There are four parts in the returned JSON:
Example: |