Derive new locations

A derive analysis resulting in a new layer with parks within 150 meters from a bike route.

What is a derive new locations analysis?

A derive new location analysis is the process of selecting and, potentially, modifying features that satisfy one or more SQL and/or spatial expressions. To execute the analysis, use the spatial analysis service and the DeriveNewLocations operation.

A derive new location analysis is similar to the Find location analysis. For example, if you perform a SQL query using where, or the spatial expressions completely within or completey contains, the results between the two analyses will be the same. However, if you use a derive analysis with a spatial expression such as intersects or within a distance of, the results can contain features with new geometries. This analysis is often used for site selection.

Real-world examples of this analysis include the following:

Determining the portions of areas that are suitable for wildlife habitats.
Evaluating the suitability for real estate developments for site selection.
Finding areas closest to places of interest (POIs).

How to derive new locations

The general steps to performing a derive new locations analysis are as follows:

Review the parameters for the DeriveNewLocations operation.
Determine if you would like the results as a feature collection (dynamic) or hosted feature layer (stored).
Send a request to get the spatial analysis service URL.
Execute a job request with the following URL and parameters:
- URL: https://<YOUR_ANALYSIS_SERVICE>/arcgis/rest/services/tasks/GPServer/DeriveNewLocations/submitJob
- Parameters:
  - expressions: The SQL or spatial relation to select a subset of the data.
  - inputLayers: The feature collection(s) or hosted feature layer(s) from which you want to extract features.
  - outputName: A string representing the name of the hosted feature layer to return with the results.
Check the status.
Get the output layer results.

To see examples using ArcGIS API for Python, ArcGIS REST JS, and the ArcGIS REST API, go to Examples below.

URL request

Use dark colors for code blocksCopy
https://<YOUR_ANALYSIS_SERVICE>/arcgis/rest/services/tasks/GPServer/DeriveNewLocations/submitJob?<parameters>

Required parameters

Name	Description	Examples
`f`	The format of the data returned.	`f=json` `f=pjson`
`token`	An OAuth 2.0 access token.	`token=<ACCESS_TOKEN>`
`inputLayers`	The layer(s) that will be used to construct the query.	`[{"url":"https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Find_Locations_in_SF_Neighborhoods/FeatureServer/0"},{"url":"https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Police_Stations/FeatureServer/0"}]`
`expressions`	The SQL or spatial query.	`[{"operator":"","layer":0,"selectingLayer":1,"spatialRel":"withinDistance","distance":0.25,"units":"Miles"}]`

Key parameters

Name	Description	Examples
`outputName`	A string representing the name of the hosted feature layer to return with the results. NOTE: If you do not include this parameter, the results are returned as a feature collection (JSON).	`{"serviceProperties": {"name": "<SERVICE_NAME>"}}`
`context`	A bounding box or output spatial reference for the analysis.	`"extent":{"xmin:", "ymin:", "xmax:", "ymax:"}`

Code examples

Find neighborhoods sections near police stations

This example uses the DeriveNewLocations operation to construct a spatial query to return the sections of San Francisco Neighborhoods that are within half a mile from a police station. While the results of the analysis return partial features that match the spatial query, the new features still contain the attribute information from the originally hosted feature layer.

For the analysis, the inputLayers value is the Police stations and neighborhoods hosted feature layers. The expression value used is: SF Neighborhoods within a distance of 0.5 Miles from Police Stations.

Portions of San Francisco neighborhoods within .25 miles of police stations.

APIs

ArcGIS API for Python

ArcGIS REST JS

Expand

Use dark colors for code blocks

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
police_stations = "https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Police_Stations/FeatureServer/0"

neighborhoods = "https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/SF_Neighborhoods/FeatureServer/0"

results = derive_new_locations(
    input_layers=[neighborhoods, police_stations],
    expressions=[
        {
            "operator": "",
            "layer": 0,
            "selectingLayer": 1,
            "spatialRel": "withinDistance",
            "distance": 0.25,
            "units": "Miles",
        }
    ],
    # Ouputs results as a hosted feature service.
    output_name = "Derive analysis results"
)

result_features = results.layers[0].query()

Expand

Go to tutorial

Service requests

Request

HTTP

cURL

Use dark colors for code blocksCopy
POST arcgis.com/sharing/rest/portals/self HTTP/1.1
Content-Type: application/x-www-form-urlencoded

&f=json
&token=<ACCESS_TOKEN>
Run in Postman

Response (JSON)

Use dark colors for code blocksCopy
{
  "helperServices": {
    // Other parameters
    "analysis": {
      "url": "https://<YOUR_ANALYSIS_SERVICE>/arcgis/rest/services/tasks/GPServer"
    },
    "geoenrichment": {
      "url": "https://geoenrich.arcgis.com/arcgis/rest/services/World/GeoenrichmentServer"
    }
  }
}

Request

HTTP

cURL

Use dark colors for code blocks

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

POST <YOUR_ANALYSIS_SERVICE>/arcgis/rest/services/tasks/GPServer/DeriveNewLocations/submitJob HTTP/1.1
Content-Type:application/x-www-form-urlencoded

f=json
&token=<ACCESS_TOKEN>
&expressions=[{"operator":"","layer":0,"selectingLayer":1,"spatialRel":"withinDistance","distance":0.25,"units":"Miles"}]
&inputLayers=[{"url":"https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Find_Locations_in_SF_Neighborhoods/FeatureServer/0","name":"Find_Locations_in_SF_Neighborhoods"},{"url":"https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Police_Stations/FeatureServer/0","name":"Police Stations"}]
&outputName={"serviceProperties":{"name":"Derive results analysis}}
&context={"extent":{"xmin":-13642856.438393056,"ymin":4532585.13569076,"xmax":-13605937.353731368,"ymax":4556013.084860135,"spatialReference":{"wkid":102100,"latestWkid":3857}}}

Run in Postman

Response (JSON)

Use dark colors for code blocksCopy

{
  "jobId": "<JOB_ID>",
  "jobStatus": "esriJobSubmitted",
  "results": {},
  "inputs": {},
  "messages": []
}

Request

HTTP

cURL

Use dark colors for code blocks

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
POST <YOUR_ANALYSIS_SERVICE>/arcgis/rest/services/tasks/GPServer/DeriveNewLocations/jobs/<JOB_ID> HTTP/1.1
Content-Type: application/x-www-form-urlencoded

f=json
&token=<ACCESS_TOKEN>

Run in Postman

Response (JSON)

Use dark colors for code blocksCopy
// Executing job
{
  "jobId": "<JOB_ID>",
  "jobStatus": "esriJobExecuting",
  "results": {},
  "inputs": {},
  "messages": []
}
// Job succeeded
{
  "jobId": "<JOB_ID>",
  "jobStatus": "esriJobSucceeded",
  "results": {"resultLayer": {"paramUrl": "results/resultLayer"}},
  "inputs": {},
  "messages": []
}

Request

HTTP

cURL

Use dark colors for code blocks

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
POST <YOUR_ANALYSIS_SERVICE>/arcgis/rest/services/tasks/GPServer/DeriveNewLocations/jobs/<JOB_ID>/results/resultLayer HTTP/1.1
Content-Type: application/x-www-form-urlencoded

f=json
&token=<ACCESS_TOKEN>
&returnType=data

Run in Postman

Response (JSON)

Use dark colors for code blocksCopy
{
  "paramName": "resultLayer",
  "dataType": "GPString",
  "value": {
      "url": "<SERVICE_URL>",
      "itemId": "<ITEM_ID>"
  }
}

Find light rail lines that intersect neighborhoods

This example uses the DeriveNewLocations operation to construct a spatial query that returns only the sections of light rail lines that intersect Downtown Portland.

For the analysis, the inputLayers are the Light rail lines and Portland neighborhoods hosted feature layers. The expression used is: Light rail lines intersects Portland neighborhoods.

Portions of rail lines that intersect the Downtownowntown neighborhood of Portland.

APIs

ArcGIS API for Python

ArcGIS REST JS

Expand

Use dark colors for code blocks

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
rail_lines = "https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Light Rail Lines/FeatureServer/0"

neighborhoods = "https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Enriched_Portland_Neighborhoods/FeatureServer/0"

results = derive_new_locations(
    input_layers=[neighborhoods, rail_lines],
    expressions=[
        {
            "operator": "",
            "layer": 0,
            "selectingLayer": 1,
            "spatialRel": "intersects"
        }
    ],
    # Ouputs results as a hosted feature service.
    output_name = "Derive analysis results"
)

result_features = results.layers[0].query()

Expand

Go to tutorial

Service requests

Request

HTTP

cURL

Use dark colors for code blocksCopy
POST arcgis.com/sharing/rest/portals/self HTTP/1.1
Content-Type: application/x-www-form-urlencoded

&f=json
&token=<ACCESS_TOKEN>
Run in Postman

Response (JSON)

Use dark colors for code blocksCopy
{
  "helperServices": {
    // Other parameters
    "analysis": {
      "url": "https://<YOUR_ANALYSIS_SERVICE>/arcgis/rest/services/tasks/GPServer"
    },
    "geoenrichment": {
      "url": "https://geoenrich.arcgis.com/arcgis/rest/services/World/GeoenrichmentServer"
    }
  }
}

Request

HTTP

cURL

Use dark colors for code blocks

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

POST <YOUR_ANALYSIS_SERVICE>/arcgis/rest/services/tasks/GPServer/DeriveNewLocations/submitJob HTTP/1.1
Content-Type:application/x-www-form-urlencoded

f=json
&token=<ACCESS_TOKEN>
&expressions=[{"operator":"","layer":0,"selectingLayer":1,"spatialRel":"intersects"}]
&inputLayers=[{"url":"https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Enriched_Portland_Neighborhoods/FeatureServer/0"},{"url":"https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Light Rail Lines/FeatureServer/0"}]
&outputName={"serviceProperties":{"name":"Derive results analysis"}}
&context={}

Run in Postman

Response (JSON)

Use dark colors for code blocksCopy

{
  "jobId": "<JOB_ID>",
  "jobStatus": "esriJobSubmitted",
  "results": {},
  "inputs": {},
  "messages": []
}

Request

HTTP

cURL

Use dark colors for code blocks

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
POST <YOUR_ANALYSIS_SERVICE>/arcgis/rest/services/tasks/GPServer/DeriveNewLocations/jobs/<JOB_ID> HTTP/1.1
Content-Type: application/x-www-form-urlencoded

f=json
&token=<ACCESS_TOKEN>

Run in Postman

Response (JSON)

Use dark colors for code blocksCopy
// Executing job
{
  "jobId": "<JOB_ID>",
  "jobStatus": "esriJobExecuting",
  "results": {},
  "inputs": {},
  "messages": []
}
// Job succeeded
{
  "jobId": "<JOB_ID>",
  "jobStatus": "esriJobSucceeded",
  "results": {"resultLayer": {"paramUrl": "results/resultLayer"}},
  "inputs": {},
  "messages": []
}

Request

HTTP

cURL

Use dark colors for code blocks

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
POST <YOUR_ANALYSIS_SERVICE>/arcgis/rest/services/tasks/GPServer/DeriveNewLocations/jobs/<JOB_ID>/results/resultLayer HTTP/1.1
Content-Type: application/x-www-form-urlencoded

f=json
&token=<ACCESS_TOKEN>
&returnType=data

Run in Postman

Response (JSON)

Use dark colors for code blocksCopy
{
  "paramName": "resultLayer",
  "dataType": "GPString",
  "value": {
      "url": "<SERVICE_URL>",
      "itemId": "<ITEM_ID>"
  }
}