Find centroids

A find centroids analysis resulting in a new layer that contains center points within USA state boundaries.

What is a find centroid analysis?

A find centroid analysis is the process of finding the representative centers of each multipoint, polyline, or polygon feature. To execute the analysis, use the spatial analysis service and the FindCentroids operation.

Real-world examples of this analysis include the following:

Preparing home or spending values for analyses that require point data.
Finding the representative centers of parcels.
Finding the representative centers for open spaces.

How to find centroids

The general steps to find centroids are as follows:

Review the parameters for the FindCentroids operation.
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/FindCentroids/submitJob
- Parameters:
  - inputLayer: Your points dataset as a hosted feature layer or feature collection.
  - pointLocation: Whether the output point locations are calculated by the geometric center of each input feature.
  - 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
http://<YOUR_ANALYSIS_SERVICE>/arcgis/rest/services/tasks/GPServer/FindCentroids/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>`
`inputLayer`	The multipoint, line, or polygon features that will be used to generate centroid point features.	`{"url":"https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Average_PDX_home_values/FeatureServer/0","name":"Average_PDX_home_values"}`

Key parameters

Name	Description	Examples
`pointLocation`	Output points are determined by the calculated geometric center of each input feature. If set to `true` the points will be contained by the bounds of the input feature.	`false` (default)
`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 centroids within square bins

This example uses the FindCentroids operation to generate points within square bins. The inputLayer value is the Generate tessellations in Portland hosted feature layer. The feature layer was created using the GenerateTessellations operation. To learn how to generate square bins, go to generate tessellations.

Find centroid analysis showing centroids generated within square bins.

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
inputLayer = {
    "url": "https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Generate_tessellations_on_Portland_boundary/FeatureServer/0"
}

results = find_centroids(
    input_layer=inputLayer,
    point_location=False,
    #Outputs results as a hosted feature layer.
    output_name=f"Find centroids results"
)

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

print(
    f"The find centroids layer has {len(result_features.features)} new records"
)

Go to API Reference

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

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

&f=json
&token=<ACCESS_TOKEN>
&inputLayer={"url":"https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Generate_tessellations_on_Portland_boundary/FeatureServer/0"}
&pointLocation=false
&outputName={"serviceProperties":{"name":"Find centroids"}}
&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
POST <YOUR_ANALYSIS_SERVICE>/arcgis/rest/services/tasks/GPServer/FindCentroids/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": {
      "outputLayer": {
          "paramUrl": "results/outputLayer"
      },
  },
  "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
POST <YOUR_ANALYSIS_SERVICE>/arcgis/rest/services/tasks/GPServer/FindCentroids/jobs/<JOB_ID>/results/outputLayer HTTP/1.1
Content-Type: application/x-www-form-urlencoded

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

Run in Postman

Response (JSON)

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

Find centroids for census blocks

This example uses the FindCentroids operation to generate points that represent census blocks. The inputLayer value is the Census blocks in SF hosted feature layer.

Find centroid analysis showing centroids generated from census blocks.

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
inputLayer = "https://services3.arcgis.com/GVgbJbqm8hXASVYi/ArcGIS/rest/services/Intersect_of_U_S__Census_Blocks_and_SF_Neighborhoods/FeatureServer/0"

results = find_centroids(
    input_layer=inputLayer,
    point_location=False,
    #Outputs results as a hosted feature layer.
    output_name=f"Find centroids results"
)

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

print(
    f"The find centroids layer has {len(result_features.features)} new records"
)

Go to API Reference

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
POST <YOUR_ANALYSIS_SERVICE>/arcgis/rest/services/tasks/GPServer/FindCentroids/submitJob HTTP/1.1
Content-Type: application/x-www-form-urlencoded

&f=json
&token=<ACCESS_TOKEN>
&inputLayer={"url":"https://services3.arcgis.com/GVgbJbqm8hXASVYi/ArcGIS/rest/services/Intersect_of_U_S__Census_Blocks_and_SF_Neighborhoods/FeatureServer/0"}
&pointLocation=false
&outputName={"serviceProperties":{"name":"Find centroids results"}}
&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
POST <YOUR_ANALYSIS_SERVICE>/arcgis/rest/services/tasks/GPServer/FindCentroids/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": {
      "outputLayer": {
          "paramUrl": "results/outputLayer"
      },
  },
  "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
POST <YOUR_ANALYSIS_SERVICE>/arcgis/rest/services/tasks/GPServer/FindCentroids/jobs/<JOB_ID>/results/outputLayer HTTP/1.1
Content-Type: application/x-www-form-urlencoded

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

Run in Postman

Response (JSON)

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