arcgis.geoenrichment module

Enables access to data and methods for a specific country. This class can reference country data and methods available using data accessed through both a Web GIS and a local installation of ArcGIS Pro with the Business Analyst extension and local country data installed. Specifying this source is accomplished using the gis parameter when instantiating. If using the keyword Pro, Country will use ArcGIS Pro with Business Analyst and will error if the specified country is not available locally. Available countries can be discovered using get_countries().

property data_collections

Returns the supported data collections and analysis variables as a Pandas dataframe.

The dataframe is indexed by the data collection id(dataCollectionID) and contains columns for analysis variables(analysisVariable).

property dataset

Returns the currently used dataset for this country.json.

Note

This is only supported when using a Web GIS (ArcGIS Online or ArcGIS Enterprise as the gis source.

enrich(study_areas, enrich_variables=None, return_geometry=True, standard_geography_level=None, standard_geography_id_column=None, proximity_type=None, proximity_value=None, proximity_metric=None, output_spatial_reference=None, **kwargs)

Enrich provides access to a massive dataset describing exactly who people are in a geographic location. The most common way to delineate study_areas for enrichment is using polygons delineated areas, although points and lines can be used as well.

When points or lines are provided, an area surrounding the geometries is used for enrichment. This area can be defined using additional parameters, but by default is one kilometer around the geometry. Also, only straight-line distance is supported with line geometries, but points can use available transportation network methods [typically drive distance or drive time].

While already popular for site analysis, forecast modeling for a store or facility location, enrich provides access to a massive amount of data for any analysis of people and their relationship and interaction with the surrounding community, culture, economy and even the natural environment. Succinctly, enrich is how to access data for human geography analysis.

The study_areas for enrichment can be provided in a number of forms: a Spatially Enabled Pandas Data Frame or an Iterable my be provided. The iterable may be comprised of Geometry object instances or standard geography identifiers. While other values, such as string addresses or points-of-interest names may be provided, it is recommended to retrieve these locations in your workflow before performing enrichment.

Parameter	Description
study_areas	Required list, dictionary, FeatureSet or SpatiallyEnabledDataFrame containing the input areas to be enriched.
enrich_variables	Enrich variables can be specified using either a list of strings or the Pandas DataFrame returned from the enrich_variables() property. If using a list of strings, the values are matched against the enrich_variables() dataframe columns for name, ‘enrich_name’, or ‘enrich_field_name’. All the values must match to one of these columns.
return_geometry	Boolean indicating if the geometry needs to be returned in the output. The default is True.
standard_geography_level	If using a list of standard geography identifiers, the geography level must be specified here. This value is the level_name column retrieved in the levels() property.
standard_geography_id_column	If providing a Pandas DataFrame as input, and the DataFrame contains a column with standard geography identifiers you desire to use for specifying the input study_areas, please provide the name of the column as a string in this parameter.
proximity_type	If providing point geometries as input study_areas, you have the option to provide the method used to create the proximity around the point based on the available travel modes. These travel modes can be discovered using the travel_modes property. Valid values are from the name column in this returned DataFrame. Also, in addition to the transportation network travel modes, you also have the option of using straight_line, just using a straight line distance, a buffer, around the geometry. This is the default, and the only option if the geometry type is line.
proximity_value	This is the scalar value as either a decimal float or integer defining the size of the proximity zone around the source geometry to be used for enrichment. For instance, if desiring a five minute drive time, this value will be 5.
proximity_metric	This is the unit of measure defining the area to be used in defining the area surrounding geometries to use for enrichment. If interested in getting a five minute drive time, this value will be minutes.
output_spatial_reference	The default output will be WGS84 (WKID 4326). If a different output spatial reference is desired, please provide it here as a WKID or SpatialReference object instance.
hierarchy	The hierarchy of the datasets to use. The hierarchy is the “ID” that can be found in the hierarchies property. If none is provided, the default hierarchy will be used.

Returns

Pandas DataFrame with enriched data.

Here is an example of using ArcGIS Pro with Business Analyst and the United States data pack installed locally to enrich with a few key variables.

from arcgis.gis import GIS
from arcgis.geoenrichment import Country

# create country object instance to use local ArcGIS Pro + Business Analyst + USA data pack
usa = Country('usa', gis=GIS('pro'))

# select current year key enrichment variables for analysis
ev_df = usa.enrich_variables
kv_df = ev_df[
    (ev_df.data_collection.str.lower().str.contains('key'))  # key data collection
    & (ev_df.alias.str.lower().str.endswith('cy'))           # current year
]

# get data from ArcGIS Online to enrich as Spatially Enabled DataFrame
itm_id = '15d227c6da8d4b7baf713709ba3693ce'  # USA federal district court polygons
gis = GIS()  # anonymous connection to ArcGIS Online
aoi_df = gis.content.get(itm_id).layers[0].query().sdf

# enrich with variables selected above
enrich_df = usa.enrich(aoi_df, enrich_variables=kv_df)

Next, we can perform a similar workflow using ArcGIS Online instead of ArcGIS Pro by creating a couple of point geometries and using five-minute drive times around the locations.

import os

from arcgis.gis import GIS
from arcgis.geoenrichment import Country
from arcgis.geometry import Geometry
from dotenv import find_dotenv, load_dotenv

# load environment settings from .env file
load_dotenv(find_dotenv())

# create connection to ArcGIS Online organization using values saved in .env file
gis_agol = GIS(
    url=os.getenv('ESRI_GIS_URL'),
    username=os.getenv('ESRI_GIS_USERNAME'),
    password=os.getenv('ESRI_GIS_PASSWORD')
)

# create a country object instance
usa = Country('usa', gis=gis_agol)

# get just key variables for the current year
ev_df = usa.enrich_variables
kv_df = ev_df[
    (ev_df.data_collection.str.lower().str.contains('key'))  # key data collection
    & (ev_df.alias.str.lower().str.endswith('cy'))           # current year
]

# create a couple of point geometries on the fly for the example
coord_lst = [
    (-122.9074835, 47.0450249),  # Bayview Grocery Store
    (-122.8749600, 47.0464031)   # Ralph's Thriftway Grocery Store
]
geom_lst = [Geometry({'x': pt[0], 'y': pt[1], 'spatialReference': {'wkid': 4326}}) for pt in coord_lst]

# enrich the geometries and get a spatially enabled dataframe
enrich_df = usa.enrich(
    study_areas=geom_lst,
    enrich_variables=kv_df,
    proximity_type='driving_time',
    proximity_value=5,
    proxmity_metric='minutes'
)

Finally, we can also use standard geography identifiers to specify the study_areas as well.

import os

from arcgis.gis import GIS
from arcgis.geoenrichment import Country
from arcgis.geometry import Geometry
from dotenv import find_dotenv, load_dotenv

# load environment settings from .env file
load_dotenv(find_dotenv())

# create connection to ArcGIS Online organization using values saved in .env file
gis_agol = GIS(
    url=os.getenv('ESRI_GIS_URL'),
    username=os.getenv('ESRI_GIS_USERNAME'),
    password=os.getenv('ESRI_GIS_PASSWORD')
)

# create a country object instance
usa = Country('usa', gis=gis_agol)

# get just key variables for the current year
ev_df = usa.enrich_variables
kv_df = ev_df[
    (ev_df.data_collection.str.lower().str.contains('key'))  # key data collection
    & (ev_df.alias.str.lower().str.endswith('cy'))           # current year
]

# the block group ids for Olympia, WA
id_lst = ['530670101001', '530670101002', '530670101003', '530670101004', '530670102001', '530670102002',
          '530670102003', '530670103001', '530670103002', '530670103003', '530670103004', '530670104001',
          '530670104002', '530670104003', '530670105101', '530670105201', '530670105202', '530670105203',
          '530670105204', '530670106001', '530670106002', '530670106003', '530670106004', '530670106005',
          '530670107001', '530670107002', '530670107003', '530670108001', '530670108002', '530670109101',
          '530670109102', '530670109103', '530670110001', '530670111002', '530670112001', '530670113001',
          '530670116211', '530670117101', '530670117102', '530670117103', '530670120002', '530670122121',
          '530670122122', '530670122124', '530670111001', '530670121004']

# enrich the geometries and get a spatially enabled dataframe
enrich_df = usa.enrich(
    study_areas=geom_lst,
    enrich_variables=kv_df,
    standard_geography_level='block_groups'
)

property enrich_variables

Pandas Dataframe of available geoenrichment variables.

For instance, the following code, if run in Jupyter, will render the table below.

from arcgis.gis import GIS
from arcgis.geoenrichment import Country

usa = Country('usa', gis=GIS('pro'))

usa.enrich_variables.head()

	name	alias	data_collection	enrich_name	enrich_field_name
0	CHILD_CY	2021 Child Population	AgeDependency	AgeDependency.CHILD_CY	AgeDependency_CHILD_CY
1	WORKAGE_CY	2021 Working-Age Population	AgeDependency	AgeDependency.WORKAGE_CY	AgeDependency_WORKAGE_CY
2	SENIOR_CY	2021 Senior Population	AgeDependency	AgeDependency.SENIOR_CY	AgeDependency_SENIOR_CY
3	CHLDDEP_CY	2021 Child Dependency Ratio	AgeDependency	AgeDependency.CHLDDEP_CY	AgeDependency_CHLDDEP_CY
4	AGEDEP_CY	2021 Age Dependency Ratio	AgeDependency	AgeDependency.AGEDEP_CY	AgeDependency_AGEDEP_CY

The values in this table can be useful for filtering to identify the variables you want to use for analysis and also for matching to existing datasets. This table, once filtered to variables of interest can be used as input directly into the enrich() method’s enrich_variables parameter.

Also, the enrich_field_name column in this table corresponds to the field naming convention used in output from the Enrich Layer tool in ArcGIS Pro. This enables you to, with a little scripting, identify variables used in previous analysis.

property geometry

Returns a Polygon object delineating the country’s area.

Note

Currently this is only supported when using a Web GIS (ArcGIS Online or ArcGIS Enterprise) as the gis source.

classmethod get(name, gis=None, year=None)

Get a reference to a particular country, given its name, or its two letter abbreviation or three letter ISO3 code.

Parameter	Description
name	Required string. The country name, two letter code or three letter ISO3 code identifying the country.
gis	Optional GIS instance. This specifies what GIS country sources are available based on the GIS source, a Web GIS (either ArcGIS Online or ArcGIS Enterprise) or ArcGIS Pro with the Business Analyst extension and at least one country data pack. If not explicitly specified, it tries to use an active GIS already created in the Python session. If an active GIS is not available, it then tries to use local resources, ArcGIS Pro with Business Analyst and at least one country dataset installed locally. Finally, if neither of these (Pro or an active GIS) are available, a GIS object instance must be explicitly provided.
year	Optional integer. Explicitly specifying the vintage (year) of data to use. This option is only available when using a ‘local’ GIS source, and will be ignored if used with a Web GIS source.

Returns

Country instance for the requested country.

property hierarchies

Return the available hierarchies and information for them as a dataframe.

property hierarchy

Get/Set the current hierarchy used. This will affect the enrichment variables

property levels

Returns levels of geography in this country, for the current dataset.

property properties

Returns namedtuple of relevant properties based on the gis source.

property reports

Returns the available reports for this country as a Pandas dataframe.

Note

Currently this is only supported when using a Web GIS (ArcGIS Online or ArcGIS Enterprise as the gis source.

search(query, layers=['*'])

Searches this country for places that have the specified query string in their name.

Returns a list of named areas matching the specified query

Parameter	Description
query	Required string. The query string to search for places within this country.
levels	Optional list of layer ids. Layer ids for a country can be queried using Country.levels properties.

Returns

A list of named areas that match the query string

Note

Currently this is only supported when using a Web GIS (ArcGIS Online or ArcGIS Enterprise as the gis source.

property subgeographies

Returns the named geographical places in this country, as NamedArea objects. Each named area has attributes for the supported subgeography levels within it, and the value of those attributes are dictionaries containing the named places within that level of geography. This allows for interactive selection of places using intellisense and a notation such as the following:

# Usage Example 1

usa = Country.get('USA')
usa.subgeographies.states['California'].counties['San_Bernardino_County']

# Usage Example 2

india.named_places.states['Bihar'].districts['Aurangabad'].subdistricts['Barun']

Note

Currently this is only supported when using a Web GIS (ArcGIS Online or ArcGIS Enterprise as the gis source.

property travel_modes

DataFrame of available travel modes for the country. This is determined by what transportation networks are available for the given country.

For instance, running the following code in Jupyter will return the table below.

from arcgis.gis import GIS
from arcgis.geoenrichment import Country

usa = Country('usa', gis=GIS('pro'))

usa.travel_modes

	name	alias	description	type	impedance	impedance_category	time_attribute_name	distance_attribute_name
0	driving_time	Driving Time	Models the movement of cars…	AUTOMOBILE	TravelTime	temporal	TravelTime	Kilometers
1	driving_distance	Driving Distance	Models the movement of cars…	AUTOMOBILE	Kilometers	distance	TravelTime	Kilometers
2	trucking_time	Trucking Time	Models basic truck travel b…	TRUCK	TruckTravelTime	temporal	TruckTravelTime	Kilometers
3	trucking_distance	Trucking Distance	Models basic truck travel b…	TRUCK	Kilometers	distance	TruckTravelTime	Kilometers
4	walking_time	Walking Time	Follows paths and roads tha…	WALK	WalkTime	temporal	WalkTime	Kilometers

Note

The values in the name column are what is required for the proximity_type parameter for the enrich() method.

BufferStudyArea allows you to buffer point and street address study areas.

area

Alias for field number 0

count(value, /)

Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

overlap

Alias for field number 3

radii

Alias for field number 1

travel_mode

Alias for field number 4

units

Alias for field number 2