ArcGIS Blog

Developers

Esri Demographics

Esri’s 2022 Updated Demographics for the U.S. are Available in GeoEnrichment

By Daniel Stauning

The June 2022 release of ArcGIS Online includes major updates to the GeoEnrichment service and underlying content. In addition to demographic data updates for Greenland, 25 countries in Europe, and 22 countries in Africa, this release includes the annual US demographic updates. For the first time ever, the previous year’s US data will be maintained side-by-side with the release of the new US data. Esri 2022 US Demographics are based on the latest Census 2020 boundaries. Maintaining both vintages of data is being done primarily to allow users whose workflows depend on the Esri 2021 US Demographics, which are based on 2010 Census boundaries, to continue their work with minimal interruption.

This blog is targeted at developers who are using the GeoEnrichment Service in custom apps and workflows. The Esri 2022 US Demographics will be the default data source when enriching data and creating reports and the goal is to provide guidance on how to use the previous year’s data if you are not ready to migrate to the 2022 data based on the new Census 2020 boundaries.

Note: As of June 2022, The U.S. Census Bureau has released the PL94-171 Redistricting dataset, this is a small subset of the data to be released. In May 2023, the Census Bureau plans to release a larger set of data in the Demographic and Housing Characteristic (DHC) file.

The Crime Indexes data is available in the Esri 2021 US Demographic data which is based on Census 2010 boundaries. It is not yet available in the Esri 2022 US Demographics data based on Census 2020 boundaries but will be coming soon.

Data Enrichment and Reports

GeoEnrichment has the concept of a hierarchy, a tag used to indicate which data source to use. The hierarchy tag can be passed in a parameter called useDatato specify a non-default data source. For example, in the U.S. the census2020 hierarchy is the default and indicates the latest data based on the Census 2020 boundaries. If the useDataparameter is blank, the census2020 hierarchy will be used. The census hierarchy is based on the 2010 census boundaries and can be passed in the useData parameter to override the default hierarchy.

Current year data (default)

  • useData={"sourceCountry":"US","hierarchy":"census2020" }

Previous year data

  • useData={"sourceCountry":"US","hierarchy":"census" }

URL Request

Example 1. Enrich a point location in the US with data from the current year.

https://geoenrich.arcgis.com/arcgis/rest/services/World/geoenrichmentserver/Geoenrichment/enrich?

  • studyAreas=[{'geometry':{'x': -117.1956, 'y': 34.0572}}]
  • analysisVariables=AtRisk.TOTPOP_CY
  • f=json
  • token=<ACCESS_TOKEN>

Example 2. Enrich a point location in the US with data from the previous year. The useData parameter is used to override the default census2020 hierarchy.

https://geoenrich.arcgis.com/arcgis/rest/services/World/geoenrichmentserver/Geoenrichment/enrich?

  • studyAreas=[{'geometry':{'x': -117.1956, 'y': 34.0572}}]
  • useData={"sourceCountry":"US","hierarchy":"census"}
  • analysisVariables=AtRisk.TOTPOP_CY
  • f=json
  • token=<ACCESS_TOKEN>

Example 3. Enrich a standard geography location in the US with data from the previous year.

https://geoenrich.arcgis.com/arcgis/rest/services/World/geoenrichmentserver/Geoenrichment/enrich?

  • studyAreas=[{"sourceCountry":"US","layer":"US.BlockGroups","ids":["060710001031"]}]
  • useData={"sourceCountry":"US","hierarchy":"census"}
  • analysisVariables=AtRisk.TOTPOP_CY
  • f=json
  • token=<ACCESS_TOKEN>

Example 4. Run a report for a point location in the US using data from the previous year.

https://geoenrich.arcgis.com/arcgis/rest/services/World/geoenrichmentserver/Geoenrichment/createReport?

  • studyAreas=[{'geometry':{'x': -117.1956, 'y': 34.0572}}]
  • useData={"sourceCountry":"US","hierarchy":"census"}
  • report=community_profile
  • f=bin
  • token=<ACCESS_TOKEN>

 

Standard Geography Query

For the Standard Geography Query option, there is parameter called optionalCountryHierarchythat can be used to return the 2010 census boundaries instead of the default 2020 boundaries.

Current year boundaries (default)

  • optionalCountryHierarchy=census2020

Previous year boundaries

  • optionalCountryHierarchy=census

URL Request

Example: Return a Zip Code boundary in the US from the previous year data based on Census 2010 boundaries.

https://geoenrich.arcgis.com/arcgis/rest/services/World/geoenrichmentserver/StandardGeographyQuery?

  • sourceCountry=US
  • optionalCountryHierarchy=census
  • geographyLayers=US.ZIP5
  • geographyIds=92373
  • returnGeometry=true
  • f=json
  • token=<ACCESS_TOKEN>

 

Discovery Methods

Discovery methods are server endpoints which return information about the underlying data and information products. For example a list of levels of geography for a country or a list of available reports.

URL Request

Example 1. Return a list a list of supported hierarchies for a country.

https://geoenrich.arcgis.com/arcgis/rest/services/World/geoenrichmentserver/Geoenrichment/Countries/US?

  • f=json

Example 2. Return a list of reports for the default current year data.

https://geoenrich.arcgis.com/arcgis/rest/services/World/geoenrichmentserver/Geoenrichment/Reports/US?

  • f=json

Example 3. Return a list of reports for the previous year data.

https://geoenrich.arcgis.com/arcgis/rest/services/World/geoenrichmentserver/Geoenrichment/Reports/US/census?

  • f=json

Example 4: Return a list of geography levels for the US based on the default 2020 census boundaries.

https://geoenrich.arcgis.com/arcgis/rest/services/World/geoenrichmentserver/Geoenrichment/StandardGeographyLevels/US?

  • f=json

Example 5: Return a list of geography levels for the US based on the 2010 census boundaries.

https://geoenrich.arcgis.com/arcgis/rest/services/World/geoenrichmentserver/Geoenrichment/StandardGeographyLevels/US/census?

  • f=json

Example 6: Return a list of data collections for the US based on the 2010 census boundaries.

https://geoenrich.arcgis.com/arcgis/rest/services/World/geoenrichmentserver/Geoenrichment/DataCollections/US/census?

  • f=json

Example Scenarios

Example 1. I’m working with a census tract that existed in the census hierarchy but no longer exists in the census2020 hierarchy.

https://geoenrich.arcgis.com/arcgis/rest/services/World/geoenrichmentserver/Geoenrichment/enrich?

  • studyAreas=[{"sourceCountry":"US","layer":"US.Tracts","ids":["01001020802"]}]
  • analysisVariables=AtRisk.TOTPOP_CY
  • f=json
  • token=<ACCESS_TOKEN>

The response will return this message:

messages: (1)
description: The following Standard Geography IDs are invalid in Layer US.Tracts and were removed from the result output: 01001020802.
id: 500
type: WARNING

The solution is to migrate to the newer census boundaries or to pass the census hierarchy containing the 2010 boundaries in the useData parameter.

https://geoenrich.arcgis.com/arcgis/rest/services/World/geoenrichmentserver/Geoenrichment/enrich?

  • studyAreas=[{“sourceCountry”:”US”,”layer”:”US.Tracts”,”ids”:[“01001020802”]}]
  • useData={"sourceCountry":"US","hierarchy":"census"}
  • analysisVariables=AtRisk.TOTPOP_CY
  • f=json
  • token=<ACCESS_TOKEN>

Example 2. I’m enriching a point location with a variable that no longer exists in the census2020 hierarchy.

https://geoenrich.arcgis.com/arcgis/rest/services/World/geoenrichmentserver/Geoenrichment/enrich?

  • studyAreas=[{“geometry”:{“x”: -122.435, “y”: 37.785}}]
  • analysisVariables=AutomobilesAutomotiveProducts.MP02017a_b
  • f=json
  • token=<ACCESS_TOKEN>

The response will return this error:

messages: (1)
description: Variables [AutomobilesAutomotiveProducts.MP02017a_B] are not defined for the country ‘US’.
id: 10050024
type: ERROR

The solution is to remove this variable from your analysis or pass the census hierarchy containing the 2010 boundaries in the useData parameter. For more information on variables that have been added and removed in the 2022 US data update, see the release notes. 

https://geoenrich.arcgis.com/arcgis/rest/services/World/geoenrichmentserver/Geoenrichment/enrich?

  • studyAreas=[{“geometry”:{“x”: -122.435, “y”: 37.785}}]
  • analysisVariables=AutomobilesAutomotiveProducts.MP02017a_b
  • useData={"sourceCountry":"US","hierarchy":"census"}
  • f=json
  • token=<ACCESS_TOKEN

Learn More

To learn more details about these datasets, standard reports, and Census 2020 geography, view the Release Notes – Esri 2022 US Demographics. And this blog from my colleague Lucy Guerra.

To learn more about working with the GeoEnrichment service, please refer to the documentation here and here. 

Share this article

Subscribe
Notify of
0 Comments
Oldest
Newest
Inline Feedbacks
View all comments