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 that would be 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(dictdata, gis)¶

A country for which geoenrichment data is available. The Country class can be used to discover the data collections, sub-geographies and available reports for a country.

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 geometry¶

classmethod get(name)¶

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

Argument	Description
name	Required string. The country name or 2 letter/ISO3 code

Returns the country

property levels¶: Returns levels of geography in this country, for the current dataset

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¶

geoenrichment.get_countries()¶: Returns the countries for which there is GeoEnrichment data.

create_report¶

geoenrichment.create_report(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¶

geoenrichment.enrich(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 creare 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 SpatialDataFrame containing the input areas to be enriched. study_areas can be a SpatialDataFrame, 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

find_businesses¶

geoenrichment.find_businesses(feature_limit=1000, feature_offset=0, exact_match=False, search_string=None, spatial_filter=None, simple_search=False, dataset_id=None, full_error_message=False, out_sr=4326, return_geometry=False, as_featureset=False, gis=None)¶

The find_businesses method returns business points matching a given search criteria. Business points can be selected using any combination of three search criteria: search string, spatial filter and business type. A business point will be selected if it matches all search criteria specified.

Argument	Description
type_filters	Optional list. List of business type filters restricting the search. For USA, either the NAICS or SIC filter is useful as a business type filter. If both filters are specified in the type_filters parameter value, selected business points will match both of them.
feature_limit	Optional integer. The limit of returned business points.
feature_offset	Optional integer. Start the results on the number of the record specified.
exact_match	Optional boolean. True value of the parameter means the exact match of the string to search.
search_string	Optional string. A string of characters which is used in the search query.
spatial_filter	Optional SpatialFilter. A spatial filter restricting the search.
simple_search	Optional boolean. A spatial filter restricting the search. True value of the parameter means a simple search (e.g., in company names only).
dataset_id	Optional string. ID of the active dataset.
full_error_message	Optional boolean. Parameter for composing error message.
out_sr	Optional integer. Parameter specifying the spatial reference to return the output dataframe.
return_geometry	Optional boolean. When true, geometries are returned with the response.
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: DataFrame (Spatial or Pandas), FeatureSet, or dictionary on error.

standard_geography_query¶

geoenrichment.standard_geography_query(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.