- URL:
- https://<geoanalytics-url>/FindSimilarLocations
- Methods:
GET
- Version Introduced:
- 10.5
Description
The Find
operation measures the similarity of candidate locations to one or more reference locations.
Based on criteria you specify, Find
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 input
parameter), the candidate
location (the search
parameter), and the fields representing the criteria you want to match. For example, the
input
might be a layer containing your top performing stores or the villages hardest hit by the disease. The
search
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. The Find
operation will rank
all of the candidate locations by how closely they match your reference locations across all of the fields you have selected.
Request parameters
Parameter | Details |
---|---|
| The Syntax: As described in Feature input, this parameter can be one of the following:
REST examples
|
| The layer containing candidate locations that will be evaluated against the reference locations. For more information on Syntax: As described in Feature input, this parameter can be one of the following:
REST examples
|
| A list of fields whose values are used to determine similarity. They must be numeric fields, and the fields must exist on both the REST examples
|
| The features you want to be returned. You can search for features that are either most similar or least similar to the Values: REST examples
|
| The method that specifies how matching is determined. The Values: REST examples
|
| The number of ranked candidate locations output to REST examples
|
| Add fields to your data from your search layer. By default, all fields from the search layer are appended. REST examples
|
|
The task will create a feature service of the results. You define the name of the service. REST examples
|
|
The
Syntax:
|
|
The response format. The default response format is Values: |
Notes on inputLayer and searchLayer
It is not uncommon for input
and search
to be 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 input
and
search
. The filter on input
would select the top performing store, while the filter on search
would select all stores except for the top performing store. You can use the optional filter 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
analysis
parameter. For example, if there are two reference locations and you are interested in matching
population, the task will look for candidate locations in search
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.
Example usage
Below is a sample request URL for Find
:
https://webadaptor.domain.com/server/rest/services/System/GeoAnalyticsTools/GPServer/FindHotSpots/submitJob?inputLayer={"url":"https://webadaptor.domain.com/server/rest/services/Hurricane/hurricaneTrack/0"}&searchLayer={"url":"https://webadaptor.domain.com/server/rest/services/Hosted/tornadoTrack/0"}&analysisFields=shelterLocations, shelterCapacity&mostOrLeastSimilar=MostSimilar&matchMethod=AttributeValues&numberOfResults=20&appendFields=&outputName=myOutput&context={"extent":{"xmin":-122.68,"ymin":45.53,"xmax":-122.45,"ymax":45.6,"spatialReference":{"wkid":4326}}}&f=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 job
to periodically check the status of the job and messages as described in Check job status. Once the job has successfully completed, use job
to retrieve the results. To track the status, you can make a request of the following form:
https://<analysis-url>/FindSimilarLocations/jobs/<jobId>
Accessing results
When the status of the job request is esri
, you can access the results of the analysis by making a request of the following form:
https://<anaylsis-url>/FindSimilarLocations/jobs/<jobId>/results/<result type>?token=<your token>&f=json
Response | Description |
---|---|
| Contains features from the
The result has properties for parameter name, data type, and value. The contents of
See Feature output for more information about how the result layer is accessed. |
| The
|