API Reference


Locations

Location

class Location(**kwargs)[source]

Represents a specific location returned by the US Census Geocoder API.

classmethod from_address(*args, **kwargs)

Return data from an adddress, supplied either as a single one-line address or a parametrized address.

Parameters
  • one_line (str / None) – A single-line address, e.g. '4600 Silver Hill Rd, Washington, DC 20233'. Defaults to None.

  • street_1 (str / None) – A street address, e.g. '4600 Silver Hill Rd'. Defaults to None.

  • street_2 (str / None) – A secondary component of a street address, e.g. 'Floor 3'. Defaults to None.

  • street_3 (str / None) – A tertiary component of a street address, e.g. 'Apt. B'. Defaults to None.

  • city (str / None) – The city or town of a street address, e.g. 'Washington'. Defaults to None.

  • state (str / None) – The state or territory of a street address, e.g. 'DC'. Defaults to None.

  • zip_code (str / None) – The zip code (or zip code + 4) of a street address, e.g. '20233'. Defaults to None.

  • benchmark (str) –

    The name of the benchmark of data to return. The default value is determined by the CENSUS_GEOCODER_BENCHMARK environment variable, and if that is not set defaults to 'Current' which represents the current default benchmark, per the Census Geocoder API.

    Accepts the following values:

    • 'Current' (default)

    • 'Census2020'

  • vintage (str) –

    The vintage of Census data for which data should be returned. The default value is determined by the CENSUS_GEOCODER_VINTAGE environment variable, and if that is not set defaults to 'Current' which represents the default vintage per the Census Geocoder API.

    Acceptable values are dependent on the benchmark specified, as per the table below:

    BENCHMARKS

    Current

    Census2020

    VINTAGES

    Current

    Census2020

    Census2020

    Census2010

    ACS2019

    ACS2018

    ACS2017

    Census2010

  • layers (str) –

    The set of geographic layers to return for the request. The default value is determined by the CENSUS_GEOCODER_LAYERS environment variable, and if that is not set defaults to 'all'.

Note

If more than one address-related parameter are supplied, this method will assume that a parametrized address is provided.

Returns

A given geographic entity.

Return type

GeographicEntity

Raises
classmethod from_batch(*args, **kwargs)

Return geographic entities for a batch collection of inputs.

Parameters
  • file (str) –

    The name of a file in CSV, XLS/X, DAT, or TXT format. Expects the file to have the following columns without a header row:

    • Unique ID

    • Street Address

    • City

    • State

    • Zip Code

  • benchmark (str) –

    The name of the benchmark of data to return. The default value is determined by the CENSUS_GEOCODER_BENCHMARK environment variable, and if that is not set defaults to 'Current' which represents the current default benchmark, per the Census Geocoder API.

    Accepts the following values:

    • 'Current' (default)

    • 'Census2020'

  • vintage (str) –

    The vintage of Census data for which data should be returned. The default value is determined by the CENSUS_GEOCODER_VINTAGE environment variable, and if that is not set defaults to 'Current' which represents the default vintage per the Census Geocoder API.

    Acceptable values are dependent on the benchmark specified, as per the table below:

    BENCHMARKS

    Current

    Census2020

    VINTAGES

    Current

    Census2020

    Census2020

    Census2010

    ACS2019

    ACS2018

    ACS2017

    Census2010

  • layers (str) –

    The set of geographic layers to return for the request. The default value is determined by the CENSUS_GEOCODER_LAYERS environment variable, and if that is not set defaults to 'all'.

Returns

A collection of geographic entities.

Return type

list of GeographicEntity

Raises
classmethod from_coordinates(*args, **kwargs)

Return data from a pair of geographic coordinates (longitude and latitude).

Parameters
  • longitude (numeric) – The longitude coordinate.

  • latitude (numeric) – The latitude coordinate.

  • benchmark (str) –

    The name of the benchmark of data to return. The default value is determined by the CENSUS_GEOCODER_BENCHMARK environment variable, and if that is not set defaults to 'Current' which represents the current default benchmark, per the Census Geocoder API.

    Accepts the following values:

    • 'Current' (default)

    • 'Census2020'

  • vintage (str) –

    The vintage of Census data for which data should be returned. The default value is determined by the CENSUS_GEOCODER_VINTAGE environment variable, and if that is not set defaults to 'Current' which represents the default vintage per the Census Geocoder API.

    Acceptable values are dependent on the benchmark specified, as per the table below:

    BENCHMARKS

    Current

    Census2020

    VINTAGES

    Current

    Census2020

    Census2020

    Census2010

    ACS2019

    ACS2018

    ACS2017

    Census2010

  • layers (str) –

    The set of geographic layers to return for the request. The default value is determined by the CENSUS_GEOCODER_LAYERS environment variable, and if that is not set defaults to 'all'.

Note

If more than one address-related parameter are supplied, this method will assume that a parametrized address is provided.

Returns

A given geographic entity.

Return type

GeographicEntity

Raises
classmethod from_csv_record(csv_record)[source]

Create an instance of the geographic entity from its CSV record.

Parameters

csv_record (list of str) – The list of columns for the CSV record.

Returns

An instance of the geographic entity.

Return type

GeographicEntity

classmethod from_dict(as_dict)[source]

Create an instance of the geographic entity from its dict representation.

Parameters

as_dict (dict) – The dict representation of the geographic entity.

Returns

An instance of the geographic entity.

Return type

GeographicEntity

classmethod from_json(as_json)

Create an instance of the geographic entity from its JSON representation.

Parameters

as_json (str, dict, or list) – The JSON representation of the geographic entity.

Returns

An instance of the geographic entity.

Return type

GeographicEntity

inspect(as_census_fields=False)[source]

Produce a list of the location’s properties that have values.

Parameters

as_census_fields (bool) – If True, return property names as they appear in Census databases or the output of the Census Geocoder API. If False, return properties as they are defined on the Census Geocoder objects. Defaults to False.

Return type

list of str

to_dict()[source]

Returns a dict representation of the geographic entity.

Note

The dict representation matches the JSON structure for the US Census Geocoder API. This is a not-very-pythonic dict structure, but at least this ensures idempotency.

Returns

dict representation of the entity.

Return type

dict

to_json()

Returns a JSON representation of the geographic entity.

Note

The JSON representation matches the JSON structure for the US Census Geocoder API. This is a not-very-pythonic structure, but at least this ensures idempotency.

Returns

str representation of the entity.

Return type

str

property benchmark

The short-hand value of the benchmark for which this Location was calculated.

Return type

str / None

property benchmark_description

The description of the benchmark for which this data was returned.

Return type

str

property benchmark_id

The name of the benchmark for which this data was returned.

Return type

str

property benchmark_is_default

If True, indicates that the default benchmark has been applied.

Return type

bool

property benchmark_name

The name of the benchmark for which this data was returned.

Return type

str

property entity_type

The type of geographic entity that the object represents. Supports either: locations or geographies.

Return type

str

property input_address

Returns a dict with the input address provided.

Return type

dict

property input_city

The city that was provided as input to get this Location.

Return type

str or None

property input_one_line

The one-line address that was provided as input to get this Location.

Return type

str or None

property input_state

The state that was provided as input to get this Location.

Return type

str or None

property input_street

The street address that was provided as input to get this Location.

Return type

str or None

property input_zip_code

The zip code that was provided as input to get this Location.

Return type

str or None

property matched_addresses

Collection of addresses that have been matched to the Location.

Return type

list of MatchedAddress / None

property vintage

The short-hand value of the vintage for which this Location was calculated.

Return type

str / None

property vintage_description

The description of the vintage for which this data was returned.

Return type

str

property vintage_id

The name of the vintage for which this data was returned.

Return type

str

property vintage_is_default

If True, indicates that the default vintage has been applied.

Return type

bool

property vintage_name

The name of the vintage for which this data was returned.

Return type

str


MatchedAddress

class MatchedAddress(**kwargs)[source]

Represents a matched address returned by the US Census GeoCoder API.

classmethod from_csv_record(csv_record)[source]

Create an instance of the geographic entity from its CSV record.

Parameters

csv_record (list of str) – The list of columns for the CSV record.

Returns

An instance of the geographic entity.

Return type

GeographicEntity

classmethod from_dict(as_dict)[source]

Create an instance of the geographic entity from its dict representation.

Parameters

as_dict (dict) – The dict representation of the geographic entity.

Returns

An instance of the geographic entity.

Return type

GeographicEntity

classmethod from_json(as_json)

Create an instance of the geographic entity from its JSON representation.

Parameters

as_json (str, dict, or list) – The JSON representation of the geographic entity.

Returns

An instance of the geographic entity.

Return type

GeographicEntity

inspect(as_census_fields=False)[source]

Produce a list of the matched address properties that have values.

Parameters

as_census_fields (bool) – If True, return property names as they appear in Census databases or the output of the Census Geocoder API. If False, return properties as they are defined on the Census Geocoder objects. Defaults to False.

Return type

list of str

to_dict()[source]

Returns a dict representation of the geographic entity.

Note

The dict representation matches the JSON structure for the US Census Geocoder API. This is a not-very-pythonic dict structure, but at least this ensures idempotency.

Returns

dict representation of the entity.

Return type

dict

to_json()

Returns a JSON representation of the geographic entity.

Note

The JSON representation matches the JSON structure for the US Census Geocoder API. This is a not-very-pythonic structure, but at least this ensures idempotency.

Returns

str representation of the entity.

Return type

str

property address

The canonical address that was matched for the Location.

Return type

str / None

property block

Census Block Code

Return type

str / None

property city

The canonical city name that was matched for the Location.

Rdirection

str / None

property county_fips_code

County FIPS Code

Return type

str

property entity_type

The type of geographic entity that the object represents. Supports either: locations or geographies.

Return type

str

property from_address

The canonical lower-bound street number that was matched for the Location.

Rdirection

str / None

property geographies

Collection of geographical areas that this address is part of.

Return type

GeographyCollection / None

property latitude

The latitude coordinate for the location.

Return type

decimal

property longitude

The longitude coordinate for the location.

Return type

decimal

property pre_direction

The canonical pre-direction that was matched for the Location.

Rdirection

str / None

property pre_qualifier

The canonical pre-qualifier that was matched for the Location.

Rqualifier

str / None

property pre_type

The canonical pre-type that was matched for the Location.

Return type

str / None

property state

The canonical state that was matched for the Location.

Rdirection

str / None

property state_fips_code

State FIPS Code

Return type

str

property street

The canonical street name that was matched for the Location.

Rdirection

str / None

property suffix_direction

The canonical suffix-direction that was matched for the Location.

Rdirection

str / None

property suffix_qualifier

The canonical suffix-qualifier that was matched for the Location.

Rqualifier

str / None

property suffix_type

The canonical suffix-type that was matched for the Location.

Return type

str / None

property tigerline_id

The TigerLine ID for the matched address.

Return type

str / None

property tigerline_side

The TigerLine side of the street for the matched address. Accepts either ‘L’ or ‘R’.

Return type

str / None

property to_address

The canonical upper-bound street number that was matched for the Location.

Rdirection

str / None

property tract

Census Tract Code

Return type

str

property zip_code

The canonical zip code that was matched for the Location.

Rdirection

str / None


Geographies

GeographyCollection

class GeographyCollection(**kwargs)[source]

Collection of GeographicArea objects.

from_csv_record(csv_record)[source]

Create an instance of the geographic entity from its CSV record.

Parameters

csv_record (list of str) – The list of columns for the CSV record.

Returns

An instance of the geographic entity.

Return type

GeographicEntity

classmethod from_dict(as_dict)[source]

Create an instance of the geographic entity from its dict representation.

Parameters

as_dict (dict) – The dict representation of the geographic entity.

Returns

An instance of the geographic entity.

Return type

GeographicEntity

classmethod from_json(as_json)

Create an instance of the geographic entity from its JSON representation.

Parameters

as_json (str, dict, or list) – The JSON representation of the geographic entity.

Returns

An instance of the geographic entity.

Return type

GeographicEntity

to_dict()[source]

Returns a dict representation of the geographic entity.

Note

The dict representation matches the JSON structure for the US Census Geocoder API. This is a not-very-pythonic dict structure, but at least this ensures idempotency.

Returns

dict representation of the entity.

Return type

dict

to_json()

Returns a JSON representation of the geographic entity.

Note

The JSON representation matches the JSON structure for the US Census Geocoder API. This is a not-very-pythonic structure, but at least this ensures idempotency.

Returns

str representation of the entity.

Return type

str

property american_indian_joint_use_areas

American Indian Joint-Use Areas

Return type

list of AIJUA

property anrc

Alaska Native Regional Corporations

Return type

list of ANRC

property anvsa

Alaska Native Village Statistical Area

Return type

list of ANVSA

property block_groups

Census Block Groups

Return type

list of CensusBlockGroup

property blocks

Census Blocks

Return type

list of CensusBlock

property blocks_2020

2020 Census Blocks

Return type

list of CensusBlock_2020

property combined_nectas

Combined New England City and Town Areas

Return type

list of CombinedNECTA

property congressional_districts_111

111th Congressional Districts

Return type

list of CongressionalDistrict_111

property congressional_districts_113

113th Congressional Districts

Return type

list of CongressionalDistrict_113

property congressional_districts_115

115th Congressional Districts

Return type

list of CongressionalDistrict_115

property congressional_districts_116

116th Congressional Districts

Return type

list of CongressionalDistrict_116

property consolidated_cities

Consolidated Cities

Return type

list of ConsolidatedCity

property counties

Census Counties

Return type

list of County

property county_subdivisions

County Sub-division

Return type

list of CountySubDivision

property csa

Combined Statistical Areas

Return type

list of CombinedStatisticalArea

property divisions

Census Divisions

Return type

list of CensusDivision

property elementary_school_districts

Elementary School Districts

Return type

list of ElementarySchoolDistrict

property entity_type

The type of geographic entity that the object represents. Supports either: locations or geographies.

Return type

str

property estates

Estates

Return type

list of Estate

property federal_american_indian_reservations

Federal American Indian Reservations

Return type

list of FederalAmericanIndianReservation

property hawaiian_home_lands

Hawaiian Home Lands

Return type

list of HawaiianHomeLand

property incorporated_places

Incorporated Places

Return type

list of IncorporatedPlace

property metropolitan_divisions

Metropolitan Divisions

Return type

list of MetropolitanDivision

property metrpolitan_nectas

Metropolitan New England City and Town Areas

Return type

list of MetropolitanNECTA

property micropolitan_nectas

Micropolitan New England City and Town Areas

Return type

list of MicropolitanNECTA

property msa

Metropolitan Statistical Area

Return type

list of MetropolitanStatisticalArea

property necta_divisions

New England City and Town Area Divisions

Return type

list of NECTADivision

property off_reservation_trust_lands

Off-Reservation Trust Lands

Return type

list of OffReservationTrustLand

property otsa

Oklahoma Tribal Statistical Areas

Return type

list of OTSA

property pumas

Public Use Microdata Areas

Return type

list of PUMA

property pumas_2010

2010 Census Public Use Microdata Areas

Return type

list of PUMA_2010

property regions

Census Regions

Return type

list of CensusRegion

property sdtsa

State Designated Tribal Statistical Areas

Return type

list of SDTSA

property secondary_school_districts

Secondary School Districts

Return type

list of SecondarySchoolDistrict

property state_american_indian_reservations

State American Indian Reservation

Return type

list of StateAmericanIndianReservation

property state_legislative_districts_lower

State Legislative Districts - Lower

Return type

list of StateLegislativeDistrictLower

property state_legislative_districts_lower_2010

2010 State Legislative Districts - Lower

Return type

list of StateLegislativeDistrictLower_2010

property state_legislative_districts_lower_2012

2012 State Legislative Districts - Lower

Return type

list of StateLegislativeDistrictLower_2012

property state_legislative_districts_lower_2016

2016 State Legislative Districts - Lower

Return type

list of StateLegislativeDistrictLower_2016

property state_legislative_districts_lower_2018

2018 State Legislative Districts - Lower

Return type

list of StateLegislativeDistrictLower_2018

property state_legislative_districts_upper

2010 State Legislative Districts - Upper

Return type

list of StateLegislativeDistrictUpper_2010

property state_legislative_districts_upper_2010

2010 State Legislative Districts - Upper

Return type

list of StateLegislativeDistrictUpper_2010

property state_legislative_districts_upper_2012

2012 State Legislative Districts - Upper

Return type

list of StateLegislativeDistrictUpper_2012

property state_legislative_districts_upper_2016

2016 State Legislative Districts - Upper

Return type

list of StateLegislativeDistrictUpper_2016

property state_legislative_districts_upper_2018

2018 State Legislative Districts - Upper

Return type

list of StateLegislativeDistrictUpper_2018

property states

States

Return type

list of State

property subbarrios

Sub-barrios

Return type

list of Subbarrio

property tdsa

Tribal Designated Statistical Areas

Return type

list of TDSA

property tracts

Census Tracts

Return type

list of CensusTract

property traffic_analysis_districts

Traffic Analysis Districts

Return type

list of TrafficAnalysisDistrict

property traffic_analysis_zones

Traffic Analysis Zones

Return type

list of TrafficAnalysisZone

property tribal_block_groups

Tribal Census Block Groups

Return type

list of TribalCensusBlockGroup

property tribal_subdivisions

Tribal Sub-divisions

Return type

list of TribalSubDivision

property tribal_tracts

Tribal Census Tracts

Return type

list of TribalCensusTract

property unified_school_districts

Unified School Districts

Return type

list of UnifiedSchoolDistrict

property urban_clusters

Urban Clusters

Return type

list of UrbanCluster

property urban_clusters_2010

2010 Census Urban Clusters

Return type

list of urban_clusters_2010

property urban_growth_areas

Urban Growth Areas

Return type

list of UrbanGrowthArea

property urbanized_areas

Urbanized Areas

Return type

list of UrbanizedArea

property urbanized_areas_2010

2010 Census Urbanized Areas

Return type

list of UrbanizedArea_2010

property voting_districts

Voting Districts

Return type

list of VotingDistrict

property zcta5

Zip Code Tabulation Area

Return type

list of ZCTA5

property zcta_2010

2010 Census ZIP Code Tabulation Areas

Return type

list of ZCTA_2010

property zcta_2020

2020 Census ZIP Code Tabulation Areas

Return type

list of ZCTA_2020


GeographicArea

class GeographicArea(**kwargs)[source]

Base class for a given geography as supported by the US government.

classmethod from_address(*args, **kwargs)

Return data from an adddress, supplied either as a single one-line address or a parametrized address.

Parameters
  • one_line (str / None) – A single-line address, e.g. '4600 Silver Hill Rd, Washington, DC 20233'. Defaults to None.

  • street_1 (str / None) – A street address, e.g. '4600 Silver Hill Rd'. Defaults to None.

  • street_2 (str / None) – A secondary component of a street address, e.g. 'Floor 3'. Defaults to None.

  • street_3 (str / None) – A tertiary component of a street address, e.g. 'Apt. B'. Defaults to None.

  • city (str / None) – The city or town of a street address, e.g. 'Washington'. Defaults to None.

  • state (str / None) – The state or territory of a street address, e.g. 'DC'. Defaults to None.

  • zip_code (str / None) – The zip code (or zip code + 4) of a street address, e.g. '20233'. Defaults to None.

  • benchmark (str) –

    The name of the benchmark of data to return. The default value is determined by the CENSUS_GEOCODER_BENCHMARK environment variable, and if that is not set defaults to 'Current' which represents the current default benchmark, per the Census Geocoder API.

    Accepts the following values:

    • 'Current' (default)

    • 'Census2020'

  • vintage (str) –

    The vintage of Census data for which data should be returned. The default value is determined by the CENSUS_GEOCODER_VINTAGE environment variable, and if that is not set defaults to 'Current' which represents the default vintage per the Census Geocoder API.

    Acceptable values are dependent on the benchmark specified, as per the table below:

    BENCHMARKS

    Current

    Census2020

    VINTAGES

    Current

    Census2020

    Census2020

    Census2010

    ACS2019

    ACS2018

    ACS2017

    Census2010

  • layers (str) –

    The set of geographic layers to return for the request. The default value is determined by the CENSUS_GEOCODER_LAYERS environment variable, and if that is not set defaults to 'all'.

Note

If more than one address-related parameter are supplied, this method will assume that a parametrized address is provided.

Returns

A given geographic entity.

Return type

GeographicEntity

Raises
classmethod from_batch(*args, **kwargs)

Return geographic entities for a batch collection of inputs.

Parameters
  • file (str) –

    The name of a file in CSV, XLS/X, DAT, or TXT format. Expects the file to have the following columns without a header row:

    • Unique ID

    • Street Address

    • City

    • State

    • Zip Code

  • benchmark (str) –

    The name of the benchmark of data to return. The default value is determined by the CENSUS_GEOCODER_BENCHMARK environment variable, and if that is not set defaults to 'Current' which represents the current default benchmark, per the Census Geocoder API.

    Accepts the following values:

    • 'Current' (default)

    • 'Census2020'

  • vintage (str) –

    The vintage of Census data for which data should be returned. The default value is determined by the CENSUS_GEOCODER_VINTAGE environment variable, and if that is not set defaults to 'Current' which represents the default vintage per the Census Geocoder API.

    Acceptable values are dependent on the benchmark specified, as per the table below:

    BENCHMARKS

    Current

    Census2020

    VINTAGES

    Current

    Census2020

    Census2020

    Census2010

    ACS2019

    ACS2018

    ACS2017

    Census2010

  • layers (str) –

    The set of geographic layers to return for the request. The default value is determined by the CENSUS_GEOCODER_LAYERS environment variable, and if that is not set defaults to 'all'.

Returns

A collection of geographic entities.

Return type

list of GeographicEntity

Raises
classmethod from_coordinates(*args, **kwargs)

Return data from a pair of geographic coordinates (longitude and latitude).

Parameters
  • longitude (numeric) – The longitude coordinate.

  • latitude (numeric) – The latitude coordinate.

  • benchmark (str) –

    The name of the benchmark of data to return. The default value is determined by the CENSUS_GEOCODER_BENCHMARK environment variable, and if that is not set defaults to 'Current' which represents the current default benchmark, per the Census Geocoder API.

    Accepts the following values:

    • 'Current' (default)

    • 'Census2020'

  • vintage (str) –

    The vintage of Census data for which data should be returned. The default value is determined by the CENSUS_GEOCODER_VINTAGE environment variable, and if that is not set defaults to 'Current' which represents the default vintage per the Census Geocoder API.

    Acceptable values are dependent on the benchmark specified, as per the table below:

    BENCHMARKS

    Current

    Census2020

    VINTAGES

    Current

    Census2020

    Census2020

    Census2010

    ACS2019

    ACS2018

    ACS2017

    Census2010

  • layers (str) –

    The set of geographic layers to return for the request. The default value is determined by the CENSUS_GEOCODER_LAYERS environment variable, and if that is not set defaults to 'all'.

Note

If more than one address-related parameter are supplied, this method will assume that a parametrized address is provided.

Returns

A given geographic entity.

Return type

GeographicEntity

Raises
classmethod from_csv_record(csv_record)[source]

Create an instance of the geographic entity from its CSV record.

Parameters

csv_record (list of str) – The list of columns for the CSV record.

Returns

An instance of the geographic entity.

Return type

Geography

classmethod from_dict(as_dict)[source]

Create an instance of the geographic entity from its dict representation.

Parameters

as_dict (dict) – The dict representation of the geographic entity.

Returns

An instance of the geographic entity.

Return type

GeographicEntity

classmethod from_json(as_json)

Create an instance of the geographic entity from its JSON representation.

Parameters

as_json (str, dict, or list) – The JSON representation of the geographic entity.

Returns

An instance of the geographic entity.

Return type

GeographicEntity

inspect(as_census_fields=False)[source]

Produce a list of the geographic area’s properties that have values.

Parameters

as_census_fields (bool) – If True, return property names as they appear in Census databases or the output of the Census Geocoder API. If False, return properties as they are defined on the Census Geocoder objects. Defaults to False.

Return type

list of str

to_dict()[source]

Returns a dict representation of the geographic entity.

Note

The dict representation matches the JSON structure for the US Census Geocoder API. This is a not-very-pythonic dict structure, but at least this ensures idempotency.

Warning

Note that certain geography types only use a subset of the properties returned. Unused or unavailable properties will be returned as None which will be converted to null if serialized to JSON.

Returns

dict representation of the entity.

Return type

dict

to_json()

Returns a JSON representation of the geographic entity.

Note

The JSON representation matches the JSON structure for the US Census Geocoder API. This is a not-very-pythonic structure, but at least this ensures idempotency.

Returns

str representation of the entity.

Return type

str

property basename

The human-readable basename of the geography.

Return type

str / None

property block

Census Block Code

Return type

str / None

property block_group

Census Block Group Code

Return type

str

property cbsa

Census CBSA Code

Return type

str / None

property cbsa_pci

CBSA Principal City Indciator

Return type

str / None

property congressional_session_code

Congressional Session Code

Return type

str / None

property county_cc

County Class Code

Return type

str / None

property county_fips_code

County FIPS Code

Return type

str

property county_ns

County ANSI Feature Code

Return type

str / None

property csa

Census CSA Code

Return type

str / None

property division_fips_code

State FIPS Code

Return type

str

property entity_type

The type of geographic entity that the object represents. Supports either: locations or geographies.

Return type

str

property funcstat

The functional status code of the geography.

Return type

str

property functional_status

The functional status of the geography.

Return type

str

property geography_type

Returns the Geography Type for the given geography.

property geoid

The Geographic Identifier.

Note

Fully concatenated geographic code (State FIPS and component numbers).

Return type

str / None

property high_school_grade

School District - Highest Grade

Return type

str / None

property is_principal_city

If True, indicates that the geography is the principal city of its surrounding entity.

Return type

bool

property land_area

The area of the geography that is on solid land, expressed in square meters.

Return type

int / None

property latitude

The centroid latitude for the geographic area.

Return type

Decimal / None

property latitude_internal_point

The internal point latitude for the geographic area.

Return type

Decimal / None

property legal_statistical_area

Legal/Statistical Area Descriptor

Return type

str / None

property legislative_session_year

Legislative Session Year (LSY)

Return type

str / None

property longitude

The centroid longitude for the geographic area.

Return type

Decimal / None

property longitude_internal_point

The internal point longitude for the geographic area.

Return type

Decimal / None

property low_school_grade

School District - Lowest Grade

Return type

str / None

property lsad

Legal/Statisical Area Descriptor (LSAD) Code

Return type

str / None

property lsad_category

Indicates the category of the LSAD for the geography. Returns either:

  • Unspecified

  • Prefix

  • Suffix

  • Balance

Return type

str

property name

The human-readable name of the geography.

Return type

str / None

property necta_pci

NECTA Principal City Indciator

Return type

str / None

property object_id

The Object Identifier.

Return type

str / None

property oid

The OID.

Return type

str / None

property place

Census Place Code

Return type

str / None

property place_cc

Place Class Code

Return type

str / None

property place_ns

Place ANSI Feature Code

Return type

str / None

property region_fips_code

Region FIPS Code

Return type

str

property school_district_type

School District Type

Return type

str / None

property state_abbreviation

State Abbreviation

Return type

str

property state_fips_code

State FIPS Code

Return type

str

property state_ns

State ANSI Feature Code

Return type

str

property tract

Census Tract Code

Return type

str

property water_area

The area of the geography that is covered in water, expressed in square meters.

Note

Water area calculations in this table include only perennial water. All other water (intermittent, glacier, and marsh/swamp) is included in this table as part of land_area calculations.

Return type

int / None

property zcta5

ZCTA-5 Zip Code Value

Return type

str / None

property zcta5_cc

ZCTA5 Class Code

Return type

str / None



Census Block Group

class CensusBlockGroup(**kwargs)[source]

Census Block Group


Tribal Census Block Group

class TribalCensusBlockGroup(**kwargs)[source]

Tribal Census Block Group


Census Tract

class CensusTract(**kwargs)[source]

Census Tract


Tribal Census Tract

class TribalCensusTract(**kwargs)[source]

Tribal Census Tract



State

class State(**kwargs)[source]





Voting District

class VotingDistrict(**kwargs)[source]

Voting District


Metropolitan Division

class MetropolitanDivision(**kwargs)[source]

Metropolitan Division


Combined Statistical Area

class CombinedStatisticalArea(**kwargs)[source]

Combined Statistical Area


Tribal Subdivision

class TribalSubDivision(**kwargs)[source]

Tribal Sub-division


Census Designated Place

class CensusDesignatedPlace(**kwargs)[source]

Census Designated Place


Division

class CensusDivision(**kwargs)[source]

Census Division



Region

class CensusRegion(**kwargs)[source]

Census Region


Metropolitan Statistical Area

class MetropolitanStatisticalArea(**kwargs)[source]

Metropolitan Statistical Area


Micropolitan Statistical Area

class MicropolitanStatisticalArea(**kwargs)[source]

Micropolitan Statistical Area


Estate

class Estate(**kwargs)[source]

Subbarrio

class Subbarrio(**kwargs)[source]

Consolidated City

class ConsolidatedCity(**kwargs)[source]

Consolidated City


Incorporated Place

class IncorporatedPlace(**kwargs)[source]

Incorporated Place


Alaska Native Regional Corporation

class ANRC(**kwargs)[source]

Alaska Native Regional Corporation


Federal American Indian Reservation

class FederalAmericanIndianReservation(**kwargs)[source]

Federal American Indian Reservation


Off-Reservation Trust Land

class OffReservationTrustLand(**kwargs)[source]

Off-Reservation Trust Land


State American Indian Reservation

class StateAmericanIndianReservation(**kwargs)[source]

State American Indian Reservation


Hawaiian Home Land

class HawaiianHomeLand(**kwargs)[source]

Hawaiian Home Land


Alaska Native Village Statistical Area

class ANVSA(**kwargs)[source]

Alaska Native Village Statistical Area


Oklahoma Tribal Statistical Areas

class OTSA(**kwargs)[source]

Oklahoma Tribal Statistical Area


State Designated Tribal Statistical Areas

class SDTSA(**kwargs)[source]

State Designated Tribal Statistical Areas


Tribal Designated Statistical Areas

class TDSA(**kwargs)[source]

Tribal Designated Statistical Area


American Indian Joint-Use Areas

class AIJUA(**kwargs)[source]

American Indian Joint-Use Area




Census Geocoder Internals

Base Entity

class BaseEntity[source]

Abstract base clase for geographic entities that may or may not be supported by the API.

abstract classmethod from_csv_record(csv_record)[source]

Create an instance of the geographic entity from its CSV record.

Parameters

csv_record (list of str) – The list of columns for the CSV record.

Returns

An instance of the geographic entity.

Return type

GeographicEntity

abstract classmethod from_dict(as_dict)[source]

Create an instance of the geographic entity from its dict representation.

Parameters

as_dict (dict) – The dict representation of the geographic entity.

Returns

An instance of the geographic entity.

Return type

GeographicEntity

classmethod from_json(as_json)[source]

Create an instance of the geographic entity from its JSON representation.

Parameters

as_json (str, dict, or list) – The JSON representation of the geographic entity.

Returns

An instance of the geographic entity.

Return type

GeographicEntity

abstract to_dict()[source]

Returns a dict representation of the geographic entity.

Note

The dict representation matches the JSON structure for the US Census Geocoder API. This is a not-very-pythonic dict structure, but at least this ensures idempotency.

Returns

dict representation of the entity.

Return type

dict

to_json()[source]

Returns a JSON representation of the geographic entity.

Note

The JSON representation matches the JSON structure for the US Census Geocoder API. This is a not-very-pythonic structure, but at least this ensures idempotency.

Returns

str representation of the entity.

Return type

str

abstract property entity_type

The type of geographic entity that the object represents. Supports either: locations or geographies.

Return type

str

Geographic Entity

class GeographicEntity[source]

Abstract base class for geographic entities that are supported by the API.

classmethod from_address(*args, **kwargs)[source]

Return data from an adddress, supplied either as a single one-line address or a parametrized address.

Parameters
  • one_line (str / None) – A single-line address, e.g. '4600 Silver Hill Rd, Washington, DC 20233'. Defaults to None.

  • street_1 (str / None) – A street address, e.g. '4600 Silver Hill Rd'. Defaults to None.

  • street_2 (str / None) – A secondary component of a street address, e.g. 'Floor 3'. Defaults to None.

  • street_3 (str / None) – A tertiary component of a street address, e.g. 'Apt. B'. Defaults to None.

  • city (str / None) – The city or town of a street address, e.g. 'Washington'. Defaults to None.

  • state (str / None) – The state or territory of a street address, e.g. 'DC'. Defaults to None.

  • zip_code (str / None) – The zip code (or zip code + 4) of a street address, e.g. '20233'. Defaults to None.

  • benchmark (str) –

    The name of the benchmark of data to return. The default value is determined by the CENSUS_GEOCODER_BENCHMARK environment variable, and if that is not set defaults to 'Current' which represents the current default benchmark, per the Census Geocoder API.

    Accepts the following values:

    • 'Current' (default)

    • 'Census2020'

  • vintage (str) –

    The vintage of Census data for which data should be returned. The default value is determined by the CENSUS_GEOCODER_VINTAGE environment variable, and if that is not set defaults to 'Current' which represents the default vintage per the Census Geocoder API.

    Acceptable values are dependent on the benchmark specified, as per the table below:

    BENCHMARKS

    Current

    Census2020

    VINTAGES

    Current

    Census2020

    Census2020

    Census2010

    ACS2019

    ACS2018

    ACS2017

    Census2010

  • layers (str) –

    The set of geographic layers to return for the request. The default value is determined by the CENSUS_GEOCODER_LAYERS environment variable, and if that is not set defaults to 'all'.

Note

If more than one address-related parameter are supplied, this method will assume that a parametrized address is provided.

Returns

A given geographic entity.

Return type

GeographicEntity

Raises
classmethod from_batch(*args, **kwargs)[source]

Return geographic entities for a batch collection of inputs.

Parameters
  • file (str) –

    The name of a file in CSV, XLS/X, DAT, or TXT format. Expects the file to have the following columns without a header row:

    • Unique ID

    • Street Address

    • City

    • State

    • Zip Code

  • benchmark (str) –

    The name of the benchmark of data to return. The default value is determined by the CENSUS_GEOCODER_BENCHMARK environment variable, and if that is not set defaults to 'Current' which represents the current default benchmark, per the Census Geocoder API.

    Accepts the following values:

    • 'Current' (default)

    • 'Census2020'

  • vintage (str) –

    The vintage of Census data for which data should be returned. The default value is determined by the CENSUS_GEOCODER_VINTAGE environment variable, and if that is not set defaults to 'Current' which represents the default vintage per the Census Geocoder API.

    Acceptable values are dependent on the benchmark specified, as per the table below:

    BENCHMARKS

    Current

    Census2020

    VINTAGES

    Current

    Census2020

    Census2020

    Census2010

    ACS2019

    ACS2018

    ACS2017

    Census2010

  • layers (str) –

    The set of geographic layers to return for the request. The default value is determined by the CENSUS_GEOCODER_LAYERS environment variable, and if that is not set defaults to 'all'.

Returns

A collection of geographic entities.

Return type

list of GeographicEntity

Raises
classmethod from_coordinates(*args, **kwargs)[source]

Return data from a pair of geographic coordinates (longitude and latitude).

Parameters
  • longitude (numeric) – The longitude coordinate.

  • latitude (numeric) – The latitude coordinate.

  • benchmark (str) –

    The name of the benchmark of data to return. The default value is determined by the CENSUS_GEOCODER_BENCHMARK environment variable, and if that is not set defaults to 'Current' which represents the current default benchmark, per the Census Geocoder API.

    Accepts the following values:

    • 'Current' (default)

    • 'Census2020'

  • vintage (str) –

    The vintage of Census data for which data should be returned. The default value is determined by the CENSUS_GEOCODER_VINTAGE environment variable, and if that is not set defaults to 'Current' which represents the default vintage per the Census Geocoder API.

    Acceptable values are dependent on the benchmark specified, as per the table below:

    BENCHMARKS

    Current

    Census2020

    VINTAGES

    Current

    Census2020

    Census2020

    Census2010

    ACS2019

    ACS2018

    ACS2017

    Census2010

  • layers (str) –

    The set of geographic layers to return for the request. The default value is determined by the CENSUS_GEOCODER_LAYERS environment variable, and if that is not set defaults to 'all'.

Note

If more than one address-related parameter are supplied, this method will assume that a parametrized address is provided.

Returns

A given geographic entity.

Return type

GeographicEntity

Raises
abstract classmethod from_csv_record(csv_record)

Create an instance of the geographic entity from its CSV record.

Parameters

csv_record (list of str) – The list of columns for the CSV record.

Returns

An instance of the geographic entity.

Return type

GeographicEntity

abstract classmethod from_dict(as_dict)

Create an instance of the geographic entity from its dict representation.

Parameters

as_dict (dict) – The dict representation of the geographic entity.

Returns

An instance of the geographic entity.

Return type

GeographicEntity

classmethod from_json(as_json)

Create an instance of the geographic entity from its JSON representation.

Parameters

as_json (str, dict, or list) – The JSON representation of the geographic entity.

Returns

An instance of the geographic entity.

Return type

GeographicEntity

inspect(as_census_fields=False)[source]

Produce a list of the entity’s properties that have values.

Parameters

as_census_fields (bool) – If True, return property names as they appear in Census databases or the output of the Census Geocoder API. If False, return properties as they are defined on the Census Geocoder objects. Defaults to False.

Return type

list of str

abstract to_dict()

Returns a dict representation of the geographic entity.

Note

The dict representation matches the JSON structure for the US Census Geocoder API. This is a not-very-pythonic dict structure, but at least this ensures idempotency.

Returns

dict representation of the entity.

Return type

dict

to_json()

Returns a JSON representation of the geographic entity.

Note

The JSON representation matches the JSON structure for the US Census Geocoder API. This is a not-very-pythonic structure, but at least this ensures idempotency.

Returns

str representation of the entity.

Return type

str

abstract property entity_type

The type of geographic entity that the object represents. Supports either: locations or geographies.

Return type

str