arcgis.geoenrichment module¶

The arcgis.geoenrichment module enables you to answer questions about locations that you can’t answer with maps alone.

GeoEnrichment provides the ability to get facts about a location or area. Using GeoEnrichment, you can get information about the people, places, and businesses in a specific area or within a certain distance or drive time from a location. It enables you to query and use information from a large collection of data sets including population, income, housing, consumer behavior, and the natural environment.

For example: What kind of people live here? What do people like to do in this area? What are their habits and lifestyles? What kind of businesses are in this area?

The enrich method to can be used retrieve demographics and other relevant characteristics associated with the area surrounding the requested places. You can also use the arcgis.geoenrichment module to obtain additional geographic context (for example, the ZIP Code of a location) and geographic boundaries (for example, the geometry for a drive-time service area).

Site analysis is a popular application of this type of data enrichment. For example, GeoEnrichment can be leveraged to study the population affected by the development of a new community center within their neighborhood. With the enrich method, the proposed site can be submitted, and the demographics and other relevant characteristics associated with the area around the site will be returned.

Country¶

class arcgis.geoenrichment.Country(iso3: str, gis: arcgis.gis.GIS = None, year: Union[str, int] = None, **kwargs)¶

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 (See get()). If using the keyword Pro, Country will try to use ArcGIS Pro with Business Analyst and will error if the specified country is not available locally. Available countries can be discovered using the get_countries() function.

Note

Currently, when using a GIS(‘Pro’) instance, only the data_collections and enrich_variables properties are supported to discover available enrichment variables.

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

property enrich_variables¶: Pandas Dataframe of available geoenrichment variables.

property geometry¶

classmethod get(name: str, gis: arcgis.gis.GIS = None, year: Union[str, int] = None)¶

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

Argument	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 levels¶: Returns levels of geography in this country, for the current dataset

property properties¶

property reports¶: Returns the available reports for this country as a Pandas dataframe

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

Argument	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

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']

get_countries¶

arcgis.geoenrichment.get_countries(gis: arcgis.gis.GIS = None, as_df: bool = False)¶

Retrieve available countries based on the GIS source being used.

Argument	Description
gis	Optional `GIS` instance. This specifies what GIS country sources are available based on the Web GIS source, whether it be ArcGIS Online, ArcGIS Enterprise, or ArcGIS Pro with the Business Analyst extension and at least one country data pack. If not 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 resourcea, ArcGIS Pro with Business and at least one country dataset installed locally. Finally, if neither of these sources are available, a `GIS` object must be explicitly provided.
as_df	Optional boolean, specifying if a Pandas DataFrame output is desired. If `False` (the default), a list of `Country` objects will be returned. If `True`, a Pandas DataFrame of available countries is returned.

Returns: Available countries as a list of Country objects, or a Pandas DataFrame of available countries.

create_report¶

arcgis.geoenrichment.create_report(study_areas, report=None, export_format='pdf', report_fields=None, options=None, return_type=None, use_data=None, in_sr=4326, out_name=None, out_folder=None, gis=None)¶

The Create Report method allows you to create many types of high quality reports for a variety of use cases describing the input area. If a point is used as a study area, the service will create a 1-mile ring buffer around the point to collect and append enrichment data. Optionally, you can create a buffer ring or drive-time service area around points of interest to generate PDF or Excel reports containing relevant information for the area on demographics, consumer spending, tapestry market, business or market potential.

Report options are available and can be used to describe and gain a better understanding about the market, customers / clients and competition associated with an area of interest.

Argument	Description
study_areas	required list. Required parameter: Study areas may be defined by input points, polygons, administrative boundaries or addresses.
report	optional string. identify the id of the report. This may be one of the many default reports available along with our demographic data collections or a customized report. Custom report templates are stored in an ArcGIS Online organization as a Report Template item. The organization URL and a valid ArcGIS Online authentication token is required for security purposes to access these templates. If no report is specified, the default report is census profile for United States and a general demographic summary report for most countries.
export_format	Optional parameter to specify the format of the generated report. Supported formats include PDF and XLSX.
report_fields	Optional parameter specifies additional choices to customize reports. Below is an example of the position on the report header for each field.
options	Optional parameter to specify the properties for the study area buffer. For a full list of valid buffer properties values and further examples review the Input XY Locations’ options parameter. By default a 1 mile radius buffer will be applied to point(s) and address locations to define a study area.
return_type	Optional parameter used for storing an output report item to Portal for ArcGIS instead of returning a report to a customer via binary stream. The attributes are used by Portal to determine where and how an item is stored. Parameter attributes include: user, folder, title, item_properties, URL, token, and referrer. Example Creating a new output in a Portal for ArcGIS Instance: return_type = {‘user’‘testUser’, ‘folder’ : ‘FolderName’, ‘title’ : ‘Report Title’, ‘item_properties’ : ‘<properties>’, ‘url’ : ‘https://hostname.domain.com/webadaptor’, ‘token’ : ‘token’, ‘referrer’ : ‘referrer’}
use_data	Optional dictionary. This parameter explicitly specify the country or dataset to query. When all input features specified in the study_areas parameter describe locations or areas that lie in the same country or dataset, this parameter can be specified to provide an additional ‘performance hint’ to the service. By default, the service will automatically determine the country or dataset that is associated with each location or area submitted in the study_areas parameter. Specifying a specific dataset or country through this parameter will potentially improve response time. By default, the data apportionment method is determined by the size of the study area. Small study areas use block apportionment for higher accuracy whereas large study areas (100 miles or more) will use a cascading centroid apportionment method to maintain performance. This default behavior can be overridden by using the detailed_aggregation parameter.
in_sr	Optional parameter to define the input geometries in the study_areas parameter in a specified spatial reference system. When input points are defined in the study_areas parameter, this optional parameter can be specified to explicitly indicate the spatial reference system of the point features. The parameter value can be specified as the well-known ID describing the projected coordinate system or geographic coordinate system. The default is 4326
out_name	Optional string. Name of the output file [ending in .pdf or .xlsx)
out_folder	Optional string. Name of the save folder

enrich¶

arcgis.geoenrichment.enrich(study_areas, data_collections=None, analysis_variables=None, comparison_levels=None, add_derivative_variables=None, intersecting_geographies=None, return_geometry=True, gis=None)¶

Returns demographic and other requested information for the specified study areas. Study areas define the location of the point or area that you want to enrich with additional information or create reports about. If one or many points are input as a study area, the method will create a 1-mile ring buffer around the point to collect and append enrichment data. You can optionally change the ring buffer size or create drive-time service areas around the point.

You can create a buffer ring or drive-time service area around the points to aggregate data for the study areas. You can also return enrichment data for buffers around input line features.

Argument	Description
study_areas	Required list, FeatureSet or SpatiallyEnabledDataFrame containing the input areas to be enriched. study_areas can be a SpatiallyEnabledDataFrame, FeatureSet or a lists of the following types: * addresses, points of interest, place names or other supported locations as strings. * dicts such as [{“address”:{“Address”:”380 New York St.”, “Admin1”:”Redlands”,”Admin2”:”CA”,”Postal”:”92373”, “CountryCode”:”USA”}}] for multiple field addresses * arcgis.gis.Geometry instances * BufferStudyArea instances. By default, one-mile ring buffers are created around the points to collect and append enrichment data. You can use BufferStudyArea to change the ring buffer size or create drive-time service areas around the points. * NamedArea instances to support standard geography. They are obtained using Country.subgeographies()/search(). When the NamedArea instances should be combined together (union), a list of such NamedArea instances should constitute a study area in the list of requested study areas.
data_collections	Optional list. A Data Collection is a preassembled list of attributes that will be used to enrich the input features. Enrichment attributes can describe various types of information such as demographic characteristics and geographic context of the locations or areas submitted as input features in study_areas.
analysis_variables	Optional list. A Data Collection is a preassembled list of attributes that will be used to enrich the input features. With the analysis_variables parameter you can return a subset of variables enrichment attributes can describe various types of information such as demographic characteristics and geographic context of the locations or areas submitted as input features in study_areas.
add_derivative_variables	Optional list. This parameter is used to specify an array of string values that describe what derivative variables to include in the output. The list of accepted values includes: [‘percent’,’index’,’average’,’all’,’*’]
comparison_levels	Optional list of layer IDs for which the intersecting geographies should be geoenriched.
intersecting_geographies	Optional parameter to explicitly define the geographic layers used to provide geographic context during the enrichment process. For example, you can use this optional parameter to return the U.S. county and ZIP Code that each input study area intersects. You can intersect input features defined in the study_areas parameter with standard geography layers that are provided by the GeoEnrichment class for each country. You can also intersect features from a publicly available feature service.
return_geometry	Optional boolean. A parameter to request the output geometries in the response.
gis	Optional GIS. If None, the GIS object will be used from the arcgis.env.active_gis. This GIS object must be authenticated and have the ability to consume credits

Refer to https://developers.arcgis.com/rest/geoenrichment/api-reference/street-address-locations.htm for the format of intersection_geographies parameter.

Performance Tip: If you wish to speed up the operation and don’t care about the geometries, set return_geometry=False

Returns: Spatial DataFrame or Panda’s DataFrame with the requested information for the study areas

standard_geography_query¶

arcgis.geoenrichment.standard_geography_query(source_country=None, country_dataset=None, layers=None, ids=None, geoquery=None, return_sub_geography=False, sub_geography_layer=None, sub_geography_query=None, out_sr=4326, return_geometry=False, return_centroids=False, generalization_level=0, use_fuzzy_search=False, feature_limit=1000, as_featureset=False, gis=None)¶

This method allows you to search and query standard geography areas so that they can be used to obtain facts about the location using the enrich() method or create reports about.

GeoEnrichment uses the concept of a study area to define the location of the point or area that you want to enrich with additional information. Locations can also be passed as one or many named statistical areas. This form of a study area lets you define an area by the ID of a standard geographic statistical feature, such as a census or postal area. For example, to obtain enrichment information for a U.S. state, county or ZIP Code or a Canadian province or postal code, the Standard Geography Query helper method allows you to search and query standard geography areas so that they can be used in the GeoEnrichment method to obtain facts about the location. The most common workflow for this service is to find a FIPS (standard geography ID) for a geographic name. For example, you can use this service to find the FIPS for the county of San Diego which is 06073. You can then use this FIPS ID within the GeoEnrichment class study area definition to get geometry and optional demographic data for the county. This study area definition is passed as a parameter to the GeoEnrichment class to return data defined in the enrichment pack and optionally return geometry for the feature.

Argument	Description
source_country	Optional string. to specify the source country for the search. Use this parameter to limit the search and query of standard geographic features to one country. This parameter supports both the two-digit and three-digit country codes illustrated in the coverage table.
country_dataset	Optional string. parameter to specify a specific dataset within a defined country.
layers	Optional list/string. Parameter specifies which standard geography layers are being queried or searched. If this parameter is not provided, all layers within the defined country will be queried.
ids	Optional parameter to specify which IDs for the standard geography layers are being queried or searched. You can use this parameter to return attributes and/or geometry for standard geographic areas for administrative areas where you already know the ID, for example, if you know the Federal Information Processing Standard (FIPS) Codes for a U.S. state or county; or, in Canada, to return the geometry and attributes for a Forward Sortation Area (FSA). Example: Return the state of California where the layers parameter is set to layers=[‘US.States’] then set ids=[“06”]
geoquery	Optional string/list. This parameter specifies the text to query and search the standard geography layers specified. You can use this parameter to query and find standard geography features that meet an input term, for example, for a list of all the U.S. counties that contain the word “orange”. The geoquery parameter can be a string that contains one or more words.
return_sub_geography	Optional boolean. Use this optional parameter to return all the subgeographic areas that are within a parent geography. For example, you could return all the U.S. counties for a given U.S. state or you could return all the Canadian postal areas (FSAs) within a Census Metropolitan Area (city). When this parameter is set to true, the output features will be defined in the sub_geography_layer. The output geometries will be in the spatial reference system defined by out_sr.
sub_geography_layer	Optional string/list. Use this optional parameter to return all the subgeographic areas that are within a parent geography. For example, you could return all the U.S. counties within a given U.S. state or you could return all the Canadian postal areas (FSAs) within a Census Metropolitan Areas (city). When this parameter is set to true, the output features will be defined in the sub_geography_layer. The output geometries will be in the spatial reference system defined by out_sr.
sub_geography_query	Optional string.User this parameter to filter the results of the subgeography features that are returned by a search term. You can use this parameter to query and find subgeography features that meet an input term. This parameter is used to filter the list of subgeography features that are within a parent geography. For example, you may want a list of all the ZIP Codes that are within “San Diego County” and filter the results so that only ZIP Codes that start with “921” are included in the output response. The subgeography query is a string that contains one or more words.
out_sr	Optional integer Use this parameter to request the output geometries in a specified spatial reference system.
return_geometry	Optional boolean. Use this parameter to request the output geometries in the response. The return type will become a Spatial DataFrame instead of a Panda’s DataFrame.
return_centroids	Optional Boolean. Use this parameter to request the output geometry to return the center point for each feature.
generalization_level	Optional integer that specifies the level of generalization or detail in the area representations of the administrative boundary or standard geographic data layers. Values must be whole integers from 0 through 6, where 0 is most detailed and 6 is most generalized.
use_fuzzy_search	Optional Boolean parameter to define if text provided in the geoquery parameter should utilize fuzzy search logic. Fuzzy searches are based on the Levenshtein Distance or Edit Distance algorithm.
feature_limit	Optional integer value where you can limit the number of features that are returned from the geoquery.
as_featureset	Optional boolean. The default is False. If True, the result will be a arcgis.features.FeatureSet object instead of a SpatailDataFrame or Pandas’ DataFrame.
gis	Optional GIS. If None, the GIS object will be used from the arcgis.env.active_gis. This GIS object must be authenticated and have the ability to consume credits

Returns: Spatial or Pandas Dataframe on success, FeatureSet, or dictionary on failure.

service_limits¶

arcgis.geoenrichment.service_limits(gis=None)¶

Returns a Pandas’ DataFrame describing limitations for each input parameter.

Returns: Pandas DataFrame