Skip To Content ArcGIS for Developers Sign In Dashboard

ArcGIS API for Python

Part 3 - Where to enrich? (what are Named Statistical Areas?)

In [3]:
# Import Libraries
from arcgis.gis import GIS
from arcgis.geoenrichment import Country
In [4]:
# Create a GIS Connection
gis = GIS(profile='your_online_profile')

Exploring Named Statistical Areas

Each country has several named statistical areas in a hierarchy of geography levels (such as states, counties, zip codes, etc). The Country class can be used to discover the data collections, sub-geographies and available reports for a country. When working with a particular country, you will find it convenient to get a reference to it using the Country.get() method. This method accepts the country name or its 2 letter abbreviation or ISO3 code and returns an instance of that country.

Let's look into some countries and explore their subgeographies.

Explore subgeographies (State, County, Tract and Zip Code) for U.S.

Geographic level: Country

In [96]:
# Get US as a country
usa = Country.get('US')
type(usa)
Out[96]:
arcgis.geoenrichment.enrichment.Country

Now that we have a country, let's look at different levels of geographies available for U.S.

In [97]:
us_levels = [level for level in usa.levels]
us_levels
Out[97]:
[{'id': 'US.WholeUSA',
  'name': 'Entire Country',
  'isWholeCountry': True,
  'adminLevel': 'Admin1',
  'singularName': 'United States of America',
  'pluralName': 'United States of America'},
 {'id': 'US.States',
  'name': 'States',
  'isWholeCountry': False,
  'adminLevel': 'Admin2',
  'singularName': 'State',
  'pluralName': 'States'},
 {'id': 'US.DMA',
  'name': 'DMAs',
  'isWholeCountry': False,
  'adminLevel': '',
  'singularName': 'DMA',
  'pluralName': 'DMAs',
  'description': 'A Designated Market Area (DMA), also referred to as a media market, is a region of the United States that is used to define television and radio markets. DMAs are determined by the Nielsen Company and are usually defined based on metropolitan areas, with suburbs often being combined within. Esri creates these boundaries by dissolving the TIGER 2020 Block Groups with Esri modified Shoreline.'},
 {'id': 'US.CD',
  'name': 'Congressional Districts',
  'isWholeCountry': False,
  'adminLevel': '',
  'singularName': 'Congressional District',
  'pluralName': 'Congressional Districts'},
 {'id': 'US.CBSA',
  'name': 'CBSAs',
  'isWholeCountry': False,
  'adminLevel': '',
  'singularName': 'CBSA',
  'pluralName': 'CBSAs',
  'description': 'Core-Based Statistical Areas (CBSAs) are comprised of Metropolitan and Micropolitan Statistical Areas. Metropolitan statistical areas have at least one urbanized area of 50,000 or more population and Micropolitan statistical areas have at least one urban cluster of at least 10,000 but less than 50,000 population. CBSAs are defined by the Office of Management and Budget (OMB) and are comprised of whole counties and Esri created these boundaries by dissolving the TIGER 2020 County Boundaries with Esri modified shoreline.'},
 {'id': 'US.Counties',
  'name': 'Counties',
  'isWholeCountry': False,
  'adminLevel': 'Admin3',
  'singularName': 'County',
  'pluralName': 'Counties'},
 {'id': 'US.CSD',
  'name': 'County Subdivisions',
  'isWholeCountry': False,
  'adminLevel': '',
  'singularName': 'County Subdivision',
  'pluralName': 'County Subdivisions'},
 {'id': 'US.ZIP5',
  'name': 'ZIP Codes',
  'isWholeCountry': False,
  'adminLevel': 'Admin4',
  'singularName': 'ZIP Code',
  'pluralName': 'ZIP Codes'},
 {'id': 'US.Places',
  'name': 'Cities and Towns (Places)',
  'isWholeCountry': False,
  'adminLevel': '',
  'singularName': 'Place',
  'pluralName': 'Places'},
 {'id': 'US.Tracts',
  'name': 'Census Tracts',
  'isWholeCountry': False,
  'adminLevel': '',
  'singularName': 'Census Tract',
  'pluralName': 'Census Tracts'},
 {'id': 'US.BlockGroups',
  'name': 'Block Groups',
  'isWholeCountry': False,
  'adminLevel': '',
  'singularName': 'Block Group',
  'pluralName': 'Block Groups'}]

We can see various levels of subgeographies for the U.S. such as states, counties, cities, places being returned as a dictionary object, and the key-value pair of the dictionary includes id, name, adminLevel etc.

The subgeographies property of a country can be used to discover these standard geographic/statistical areas within that country.

This information is available through a heirarchy of dynamic properties (like states, counties, tracts, zip-codes,...). Each such dynamic property reflects the geographical levels within that country, with subgeographies grouped logically under the higher levels of geographies. The properties are dictionaries containing the names of the standard geographic places and their values are instances of NamedArea class. The NamedArea objects can be used as study areas in the enrich() method.

Note: Setting the `IPCompleter.greedy=True` configuration option in Jupyter notebook enables you to dynamically discover the various levels of subgeographies using intellisense, as in the example below:
In [98]:
%config IPCompleter.greedy=True

Geographic level: State

usa.subgeographies.states returns a dictionary of different state names along with their details. To view all states and their details you may use usa.subgeographies.states in the code cell. We will only look at the first few records.

In [99]:
us_states = [state for state in usa.subgeographies.states.items()][:5]
us_states
Out[99]:
[('Alabama',
  <NamedArea name:"Alabama" area_id="01", level="US.States", country="United States">),
 ('Alaska',
  <NamedArea name:"Alaska" area_id="02", level="US.States", country="United States">),
 ('Arizona',
  <NamedArea name:"Arizona" area_id="04", level="US.States", country="United States">),
 ('Arkansas',
  <NamedArea name:"Arkansas" area_id="05", level="US.States", country="United States">),
 ('California',
  <NamedArea name:"California" area_id="06", level="US.States", country="United States">)]

We see that various states are listed along with the "NamedArea" object that contains different properties such as name, area_id, level etc. Let's select a state and further explore its subgeographies.

In [100]:
# Select a state
us_state = usa.subgeographies.states['California']
us_state
Out[100]:
<NamedArea name:"California" area_id="06", level="US.States", country="United States">

Visualize on a map

In [103]:
# Create a map
state_map = gis.map('California')
state_map
In [102]:
# Plot on a map
state_map.draw(us_state.geometry)

Geographic level: County

Let's look at different counties in California. Following a similar pattern as above, we will look at the first few counties. To look at all counties you may use usa.subgeographies.states['California'].counties.

In [104]:
ca_counties = [county for county in usa.subgeographies.states['California'].counties.items()][:5]
ca_counties
Out[104]:
[('Alameda_County',
  <NamedArea name:"Alameda County" area_id="06001", level="US.Counties", country="United States">),
 ('Alpine_County',
  <NamedArea name:"Alpine County" area_id="06003", level="US.Counties", country="United States">),
 ('Amador_County',
  <NamedArea name:"Amador County" area_id="06005", level="US.Counties", country="United States">),
 ('Butte_County',
  <NamedArea name:"Butte County" area_id="06007", level="US.Counties", country="United States">),
 ('Calaveras_County',
  <NamedArea name:"Calaveras County" area_id="06009", level="US.Counties", country="United States">)]

Let's select a county in California. Notice how a county can be selected using its key i.e. Alameda_County or San_Bernardino_County.

In [105]:
sb_county = usa.subgeographies.states['California'].counties['San_Bernardino_County']
sb_county
Out[105]:
<NamedArea name:"San Bernardino County" area_id="06071", level="US.Counties", country="United States">

Visualize on a map

In [108]:
# Create a map
county_map = gis.map('California',6)
county_map