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_CYf=jsontoken=<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_CYf=jsontoken=<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_CYf=jsontoken=<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_profilef=bintoken=<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=USoptionalCountryHierarchy=censusgeographyLayers=US.ZIP5geographyIds=92373returnGeometry=truef=jsontoken=<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_CYf=jsontoken=<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_CYf=jsontoken=<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_bf=jsontoken=<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_buseData={"sourceCountry":"US","hierarchy":"census"}f=jsontoken=<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.
Article Discussion: