Tutorial: Enrich data

Learn how to add demographic and local facts data to hosted feature layers using the Map Viewer, ArcGIS APIs, and the GeoEnrichment service.

Esri Tapestry Segmentation data for the United States

GeoEnrichment is the process of discovering and adding demographic and local facts data to feature data. To enrich data, you choose from thousands of data variables grouped into categories such as population, age, income, housing, and spending, and then use the Map Viewer, GeoEnrichment service, or spatial analysis service to enrich the data. The additional data can be used to reveal demographic, socioeconomic, and other financial and business-related patterns for a geographic area.

In this tutorial, you use the Map Viewer, ArcGIS API for Python, ArcGIS REST JS, and the ArcGIS REST API to add demographic information to hosted feature layers using the EnrichLayer operation from the spatial analysis service.

Prerequisites

Steps

The easiest way to enrich data is to use the Map Viewer. The main requirement is that you have a hosted feature layer available to perform the enrichment analysis.

The general steps to use the Map Viewer include the following:

Sign in to your portal:
- ArcGIS Location Platform: Go to https://location.arcgis.com > My portal.
- ArcGIS Online: Go to https://www.arcgis.com/home/signin.html.
- ArcGIS Enterprise: Learn more at ArcGIS Enterprise > Use > Get started > Access.
Go to Map Viewer.
In the Content (dark) toolbar, click Add to select and add the hosted feature layers that you want to enrich.
In the Settings (light) toolbar, click Analysis > Tools > Enrich Layer.
For the Input features, select the analysis layer to enrich.
Click + Variable to select the data variables you want and then click Select.
Specify an Output name then click Run.
View the results on the map.

Code examples

The examples below show you how to enrich different types of hosted feature layers with different data variables. The analysis ranges from country to city scale.

Enrich countries with population data

In this example, you add population data to countries in the World Countries (Generalized) hosted feature layer. The data variable used is Total Population.

Steps

Steps to use the Map Viewer

Steps to use ArcGIS Python, REST JS, and REST APIs

Sign in to your portal:
- ArcGIS Location Platform: Go to https://location.arcgis.com > My portal.
- ArcGIS Online: Go to https://www.arcgis.com/home/signin.html.
- ArcGIS Enterprise: Learn more at ArcGIS Enterprise > Use > Get started > Access.
Go to the Map Viewer.
In the Contents (dark) toolbar, click Add > Browse > Living Atlas and type the following: World Countries Generalized.
Select the layer > Add to Map.
Ensure that the layer is visible on the map.
In the Settings (light) toolbar, click Analysis > Tools > Enrich Layer.
Set the following parameters:
- Input features: World Countries Generalized.
- Enrichment variables > + Variable > Population.
- Select 2024 Total Population (Esri).
- Click Select.
Set the Output name to: Enriched World Countries.
Click Estimate credits. The estimated cost for ArcGIS Location Platform is USD $0.251 and ArcGIS Online is 2.51 credits.
Click Run.

Implement user authentication to access the spatial analysis service.
Define the parameters of the request.
Execute the operation. Note: This is a long transaction managed with a job request.
Handle the results.

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
inputLayer = "https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/World_Countries_(Generalized)/FeatureServer/0"

results = enrich_layer(
    input_layer=inputLayer,
    analysis_variables=["KeyGlobalFacts.TOTPOP"],
    output_name="Enriched world countries",  # Outputs results as a hosted feature layer
)

print(f"New item created : {results.itemid}")

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>

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 blocksCopy

POST /arcgis/rest/services/tasks/GPServer/EnrichLayer/submitJob HTTP/1.1
Content-Type: application/x-www-form-urlencoded

f=json
&token=<ACCESS_TOKEN>
&inputLayer={"url":"https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/World_Countries_(Generalized)/FeatureServer/0"}
&analysisVariables=["KeyGlobalFacts.TOTPOP"]
&outputName={"serviceProperties":"name":{"Enrich layers result"}}

Response (JSON)

Use dark colors for code blocksCopy

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

Request

HTTP

cURL

Use dark colors for code blocksCopy
POST /arcgis/rest/services/tasks/GPServer/EnrichLayer/submitJob/jobs/<JOB_ID> HTTP/1.1
Content-Type: application/x-www-form-urlencoded

f=json
&token=<ACCESS_TOKEN>

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": {
    "enrichedLayer": {
      "paramUrl": "results/enrichedLayer"
    }
  },
  "inputs": {},
  "messages": []
}

Request

HTTP

cURL

Use dark colors for code blocksCopy
POST /arcgis/rest/services/tasks/GPServer/EnrichLayer/submitJob/jobs/<JOB_ID>/results/enrichedLayer HTTP/1.1
Content-Type: application/x-www-form-urlencoded

f=json
&token=<ACCESS_TOKEN>

Response (JSON)

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

Results

The results are returned in a new hosted feature layer containing 251 country boundary polygons enriched with population data.

Enrich layers analysis revealing the total population by country.

Enrich USA census blocks with housing data

In this example, you add housing and household data to the USA Census Block Groups hosted feature layer, provided by the ArcGIS Living Atlas of the World.

The data variables include the following:

2024 Average Home Value (Esri)
2020 Renter Occupied Housing Units (U.S. Census)
2024 Average Household Income (Esri)

Steps

Steps to use the Map Viewer

Steps to use ArcGIS Python, REST JS, and REST APIs

Sign in to your portal:
- ArcGIS Location Platform: Go to https://location.arcgis.com > My portal.
- ArcGIS Online: Go to https://www.arcgis.com/home/signin.html.
- ArcGIS Enterprise: Learn more at ArcGIS Enterprise > Use > Get started > Access.
Go to the Map Viewer.
In the Contents (dark) toolbar, click Add > Browse layers and select Living Atlas from the dropdown and type the following: USA Census Block Groups.
Select the layer then click Add to Map.
Ensure that the layer visible on the map.
In the search bar, type in New Orleans, LA.
In the Settings (light) toolbar, click Analysis > Tools > Enrich Layer.
Set the following parameters:
- Input features: U.S. Census Block Groups.
- Under Enrichment data, Click + Variable > In the search box enter the following variable names and check each one to add it to the selected variables:
  - 2024 Average Home Value (Esri)
  - 2020 Renter Occupied Housing Units (U.S. Census)
  - 2024 Average Household Income (Esri)
- Click Select.
- Set the Result Layer > Output name to: NOLA enriched census blocks.
- Under Environment setting > Processing extent, choose Display extent.
Click Estimate credits. The estimated cost for ArcGIS Location Platform is USD $2.84 and ArcGIS Online is 28.44 credits.
Click Run.

Implement user authentication to access the spatial analysis service.
Define the parameters of the request.
Execute the operation. Note: This is a long transaction managed with a job request.
Handle the results.

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
inputLayer = "https://services2.arcgis.com/FiaPA4ga0iQKduv3/arcgis/rest/services/USA_Block_Groups_v1/FeatureServer/0"

results = enrich_layer(
    input_layer=inputLayer,
    analysis_variables=[
        "homevalue.AVGVAL_CY",
        "KeyUSFacts.RENTER_CY",
        "AtRisk.AVGHINC_CY",
    ],
    country="US",
    context={
        "extent": {
            "xmin": -10064584.78182423,
            "ymin": 3469864.993711926,
            "xmax": -10005269.647874909,
            "ymax": 3535218.6528957766,
            "spatialReference": {"wkid": 102100, "latestWkid": 3857},
        }
    },
    output_name="Enrich layers census block results",  # Outputs results as a hosted feature layer
)

print(f"New item created : {results.itemid}")

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>

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

f=json
&token=<ACCESS_TOKEN>
&inputLayer={"url":"https://services2.arcgis.com/FiaPA4ga0iQKduv3/arcgis/rest/services/USA_Block_Groups_v1/FeatureServer/0"}
&analysisVariables=["homevalue.AVGVAL_CY","KeyUSFacts.RENTER_CY","AtRisk.AVGHINC_CY"]
&country=US
&context={"extent": {"xmin": -10064584.78182423,"ymin": 3469864.993711926,"xmax": -10005269.647874909,"ymax": 3535218.6528957766,"spatialReference": {"wkid": 102100, "latestWkid": 3857}}}
&outputName={"serviceProperties":"name":{"Enrich layers result"}}

Response (JSON)

Use dark colors for code blocksCopy

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

Request

HTTP

cURL

Use dark colors for code blocksCopy
POST /arcgis/rest/services/tasks/GPServer/EnrichLayer/submitJob/jobs/<JOB_ID> HTTP/1.1
Content-Type: application/x-www-form-urlencoded

f=json
&token=<ACCESS_TOKEN>

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": {
    "enrichedLayer": {
      "paramUrl": "results/enrichedLayer"
    }
  },
  "inputs": {},
  "messages": []
}

Request

HTTP

cURL

Use dark colors for code blocksCopy
POST /arcgis/rest/services/tasks/GPServer/EnrichLayer/submitJob/jobs/<JOB_ID>/results/enrichedLayer HTTP/1.1
Content-Type: application/x-www-form-urlencoded

f=json
&token=<ACCESS_TOKEN>

Response (JSON)

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

Results

The results are returned in a new hosted feature layer containing census blocks enriched with the housing data.

Enrich layers analysis revealing home value, renter, and household income data.

Enrich tessellations with local business data

In this tutorial, you add local business data related to coffee consumers and spending within the Portland City Boundary hosted feature layer. This data could be used to find the areas best suited to support a new coffee bean roasting business.

To subdivide areas within the Portland City Boundary, you will create a hexagon bin tessellation. After creation, you will enrich the bins with coffee consumer and spending information. The data variables you will use are:

2024 Coffee (average spending)
2024 HH Spent $100-$149 in Average Week at Food Stores
2024 Shopped at Costco Warehouse or Club Store Last 6 Mo
2024 Shopped at Walmart Neighborhood Market Grocery Store Last 6 Mo

Steps

Part 1: Copy the web map

Go to the Enrich data tutorial web map and click Sign in.
Verify that you the following layer by toggling the visibility on and off.
- Portland Boundary
Click Save > Save As > Save Map to save a copy.

Part 2: Generate hexagon bins

Steps to use the Map Viewer

Steps to use ArcGIS Python, REST JS, and REST APIs

In the Settings (light) toolbar, click Analysis > Tools > Generate Tessellations.
Set the following parameters:
- Bin shape type: Hexagon
- Bin size measurement: Area
- Bin size: 1
- Bin size units: Square Miles
- Extent layer: Portland boundary.
- Only keep intersecting tessellations: true (checked).
Set the Output name to: Portland one mile hexbins.
Click Estimate credits. The estimated cost for ArcGIS Location Platform is USD $0.03 and ArcGIS Online is 0.3 credits.
Click Run.

Implement user authentication to access the spatial analysis service.
Define the parameters of the request.
Execute the operation. Note: This is a long transaction managed with a job request.
Handle the results.

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
results = generate_tessellation(
    bin_size=1,
    bin_type="HEXAGON",
    bin_size_unit="Miles",
    intersect_study_area=True,
    extent_layer="https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Boundary/FeatureServer/0",
    # Outputs results as a hosted feature service.
    output_name="Generate tessellation results",
)

Expand

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>

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

&f=json
&token=<ACCESS_TOKEN>
&binType=HEXAGON
&extentLayer={"url":"https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Boundary/FeatureServer/0","name":"Boundary"}
&intersectStudyArea=true
&binSize=1
&binSizeUnit=Miles
&outputName={"serviceProperties":{"name":"Generate tessellations results"}}

Response (JSON)

Use dark colors for code blocksCopy

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

Request

HTTP

cURL

Use dark colors for code blocksCopy
POST <YOUR_ANALYSIS_SERVICE>/arcgis/rest/services/tasks/GPServer/GenerateTessellations/jobs/<JOB_ID> HTTP/1.1
Content-Type: application/x-www-form-urlencoded

&f=json
&token=<ACCESS_TOKEN>

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": {
      "tessellationLayer": {
          "paramUrl": "results/tessellationLayer"
      },
  },
  "inputs": {},
  "messages": []
}

Request

HTTP

cURL

Use dark colors for code blocksCopy
POST <YOUR_ANALYSIS_SERVICE>/arcgis/rest/services/tasks/GPServer/GenerateTessellations/jobs/<JOB_ID>/results/tessellationLayer HTTP/1.1
Content-Type: application/x-www-form-urlencoded

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

Response (JSON)

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

The result is a new hosted feature layer that contains hexagon bins (polygons) for Portland.

Generate tessellations analysis showing one mile hexagon bins.

Part 3: Enrich the hexagon bins

Steps to use the Map Viewer

Steps to use ArcGIS Python, REST JS, and REST APIs

In the Settings (light) toolbar, click Analysis > Tools > Enrich Layer.
Set the following parameters:
1. Input features: Portland one mile hexbins.
2. Click + Variable.
3. In the search box, enter and select the following variables:
  - 2024 Coffee
  - 2024 HH Spent $100-$149 in Average Week at Food Stores
  - 2024 Shopped at Costco Warehouse or Club Store Last 6 Mo.
  - 2024 Shopped at Walmart Neighborhood Market Grocery Store Last 6 Mo.
4. Click Select.
Set the Output name to: Portland - Enriched hexbins.
Click Estimate credits. The estimated cost for ArcGIS Location Platform is USD $0.08 and ArcGIS Online is 8.12 credits.
Click Run.

Implement user authentication to access the spatial analysis service.
Define the parameters of the request.
Execute the operation. Note: This is a long transaction managed with a job request.
Handle the results.

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
results = enrich_layer(
    input_layer="<Generate tessellations results URL>",
    analysis_variables=[
        "food.X1122_A",
        "GroceryAlcoholicBeverages.MP13002H_B",
        "GroceryAlcoholicBeverages.MP13026A_B",
        "GroceryAlcoholicBeverages.MP13030A_B",
    ],
    output_name="Enriched one mile hexbin results",  # Outputs results as a hosted feature layer
)

print(f"New item created : {results.itemid}")

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>

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

f=json
&token=<ACCESS_TOKEN>
&inputLayer={"url":"<Generate tessellations results URL>"}
&analysisVariables=["food.X1122_A","GroceryAlcoholicBeverages.MP13002H_B","GroceryAlcoholicBeverages.MP13026A_B","GroceryAlcoholicBeverages.MP13030A_B"]
&outputName={"serviceProperties":"name":{"Enrich layers result"}}

Response (JSON)

Use dark colors for code blocksCopy

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

Request

HTTP

cURL

Use dark colors for code blocksCopy
POST /arcgis/rest/services/tasks/GPServer/EnrichLayer/submitJob/jobs/<JOB_ID> HTTP/1.1
Content-Type: application/x-www-form-urlencoded

f=json
&token=<ACCESS_TOKEN>

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": {
    "enrichedLayer": {
      "paramUrl": "results/enrichedLayer"
    }
  },
  "inputs": {},
  "messages": []
}

Request

HTTP

cURL

Use dark colors for code blocksCopy
POST /arcgis/rest/services/tasks/GPServer/EnrichLayer/submitJob/jobs/<JOB_ID>/results/enrichedLayer HTTP/1.1
Content-Type: application/x-www-form-urlencoded

f=json
&token=<ACCESS_TOKEN>

Response (JSON)

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

Results

The result is a new hosted feature layer containing 203 hexagons enriched with consumer spending data.

Enrich layers analysis visualizing consumer spending by data variable.

What's next?

Learn how to use additional tools, APIs, and location services in these tutorials:

Create data sources

Import, create, and generate data for feature analysis.

ArcGIS portal

Find data sources

Discover data in ArcGIS that you can use for feature analysis.

ArcGIS Online ArcGIS Living Atlas ArcGIS Hub

Find and extract data

Find data with attribute and spatial queries using find analysis operations.

Map Viewer Python API REST JS REST API

Combine data

Overlay, join, and dissolve features using combine analysis operations.

Map Viewer Python API REST JS REST API

Summarize data

Aggregate and summarize features using summarize analysis operations.

Map Viewer Python API REST JS REST API

Discover patterns in data

Find patterns and trends in data using spatial analysis operations.

Map Viewer Python API REST JS REST API

Perform a feature analysis

Perform a feature analysis using ArcGIS REST JS.

Esri Leaflet MapLibre GL JS OpenLayers REST JS REST API