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 toNone
.street_1 (
str
/None
) – A street address, e.g.'4600 Silver Hill Rd'
. Defaults toNone
.street_2 (
str
/None
) – A secondary component of a street address, e.g.'Floor 3'
. Defaults toNone
.street_3 (
str
/None
) – A tertiary component of a street address, e.g.'Apt. B'
. Defaults toNone
.city (
str
/None
) – The city or town of a street address, e.g.'Washington'
. Defaults toNone
.state (
str
/None
) – The state or territory of a street address, e.g.'DC'
. Defaults toNone
.zip_code (
str
/None
) – The zip code (or zip code + 4) of a street address, e.g.'20233'
. Defaults toNone
.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
NoAddressError – if no address information is supplied
EntityNotFoundError – if no geographic entity was found matching the address supplied
UnrecognizedBenchmarkError – if the
benchmark
supplied is not recognizedUnrecognizedVintageError – if the
vintage
supplied is not recognized
- 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
ofGeographicEntity
- Raises
NoFileProvidedError – if no
file_
is providedFileNotFoundError – if
file_
does not exist on the filesystemBatchSizeTooLargeError – if
file_
contains more than 10,000 recordsEntityNotFoundError – if no geographic entity was found matching the address supplied
UnrecognizedBenchmarkError – if the
benchmark
supplied is not recognizedUnrecognizedVintageError – if the
vintage
supplied is not recognized
- 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
NoAddressError – if no address information is supplied
EntityNotFound – if no geographic entity was found matching the address supplied
UnrecognizedBenchmarkError – if the
benchmark
supplied is not recognizedUnrecognizedVintageError – if the
vintage
supplied is not recognized
- classmethod from_csv_record(csv_record)[source]¶
Create an instance of the geographic entity from its CSV record.
- classmethod from_dict(as_dict)[source]¶
Create an instance of the geographic entity from its
dict
representation.
- classmethod from_json(as_json)¶
Create an instance of the geographic entity from its JSON representation.
- inspect(as_census_fields=False)[source]¶
Produce a list of the location’s properties that have values.
- Parameters
as_census_fields (
bool
) – IfTrue
, return property names as they appear in Census databases or the output of the Census Geocoder API. IfFalse
, return properties as they are defined on the Census Geocoder objects. Defaults toFalse
.- Return type
- 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.
- property benchmark_description¶
The description of the benchmark for which this data was returned.
- Return type
- property benchmark_is_default¶
If
True
, indicates that the default benchmark has been applied.- Return type
- property entity_type¶
The type of geographic entity that the object represents. Supports either:
locations
orgeographies
.- Return type
- property matched_addresses¶
Collection of addresses that have been matched to the
Location
.- Return type
list
ofMatchedAddress
/None
- property vintage_description¶
The description of the vintage for which this data was returned.
- Return type
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.
- classmethod from_dict(as_dict)[source]¶
Create an instance of the geographic entity from its
dict
representation.
- classmethod from_json(as_json)¶
Create an instance of the geographic entity from its JSON representation.
- inspect(as_census_fields=False)[source]¶
Produce a list of the matched address properties that have values.
- Parameters
as_census_fields (
bool
) – IfTrue
, return property names as they appear in Census databases or the output of the Census Geocoder API. IfFalse
, return properties as they are defined on the Census Geocoder objects. Defaults toFalse
.- Return type
- 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.
- property entity_type¶
The type of geographic entity that the object represents. Supports either:
locations
orgeographies
.- Return type
- 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 tigerline_side¶
The TigerLine side of the street for the matched address. Accepts either ‘L’ or ‘R’.
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.
- classmethod from_dict(as_dict)[source]¶
Create an instance of the geographic entity from its
dict
representation.
- classmethod from_json(as_json)¶
Create an instance of the geographic entity from its JSON representation.
- 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.
- property block_groups¶
Census Block Groups
- Return type
- property blocks¶
Census Blocks
- Return type
list
ofCensusBlock
- property blocks_2020¶
2020 Census Blocks
- Return type
- property combined_nectas¶
Combined New England City and Town Areas
- Return type
- property congressional_districts_111¶
111th Congressional Districts
- Return type
- property congressional_districts_113¶
113th Congressional Districts
- Return type
- property congressional_districts_115¶
115th Congressional Districts
- Return type
- property congressional_districts_116¶
116th Congressional Districts
- Return type
- property consolidated_cities¶
Consolidated Cities
- Return type
- property county_subdivisions¶
County Sub-division
- Return type
- property csa¶
Combined Statistical Areas
- Return type
- property divisions¶
Census Divisions
- Return type
- property elementary_school_districts¶
Elementary School Districts
- Return type
- property entity_type¶
The type of geographic entity that the object represents. Supports either:
locations
orgeographies
.- Return type
- property federal_american_indian_reservations¶
Federal American Indian Reservations
- Return type
- property hawaiian_home_lands¶
Hawaiian Home Lands
- Return type
- property incorporated_places¶
Incorporated Places
- Return type
- property metropolitan_divisions¶
Metropolitan Divisions
- Return type
- property metrpolitan_nectas¶
Metropolitan New England City and Town Areas
- Return type
- property micropolitan_nectas¶
Micropolitan New England City and Town Areas
- Return type
- property msa¶
Metropolitan Statistical Area
- Return type
- property necta_divisions¶
New England City and Town Area Divisions
- Return type
- property off_reservation_trust_lands¶
Off-Reservation Trust Lands
- Return type
- property regions¶
Census Regions
- Return type
list
ofCensusRegion
- property secondary_school_districts¶
Secondary School Districts
- Return type
- property state_american_indian_reservations¶
State American Indian Reservation
- Return type
- property state_legislative_districts_lower¶
State Legislative Districts - Lower
- Return type
- property state_legislative_districts_lower_2010¶
2010 State Legislative Districts - Lower
- Return type
list
ofStateLegislativeDistrictLower_2010
- property state_legislative_districts_lower_2012¶
2012 State Legislative Districts - Lower
- Return type
list
ofStateLegislativeDistrictLower_2012
- property state_legislative_districts_lower_2016¶
2016 State Legislative Districts - Lower
- Return type
list
ofStateLegislativeDistrictLower_2016
- property state_legislative_districts_lower_2018¶
2018 State Legislative Districts - Lower
- Return type
list
ofStateLegislativeDistrictLower_2018
- property state_legislative_districts_upper¶
2010 State Legislative Districts - Upper
- Return type
list
ofStateLegislativeDistrictUpper_2010
- property state_legislative_districts_upper_2010¶
2010 State Legislative Districts - Upper
- Return type
list
ofStateLegislativeDistrictUpper_2010
- property state_legislative_districts_upper_2012¶
2012 State Legislative Districts - Upper
- Return type
list
ofStateLegislativeDistrictUpper_2012
- property state_legislative_districts_upper_2016¶
2016 State Legislative Districts - Upper
- Return type
list
ofStateLegislativeDistrictUpper_2016
- property state_legislative_districts_upper_2018¶
2018 State Legislative Districts - Upper
- Return type
list
ofStateLegislativeDistrictUpper_2018
- property tracts¶
Census Tracts
- Return type
list
ofCensusTract
- property traffic_analysis_districts¶
Traffic Analysis Districts
- Return type
- property traffic_analysis_zones¶
Traffic Analysis Zones
- Return type
- property tribal_block_groups¶
Tribal Census Block Groups
- Return type
- property tribal_subdivisions¶
Tribal Sub-divisions
- Return type
- property tribal_tracts¶
Tribal Census Tracts
- Return type
- property unified_school_districts¶
Unified School Districts
- Return type
- property urban_clusters¶
Urban Clusters
- Return type
list
ofUrbanCluster
- property urban_clusters_2010¶
2010 Census Urban Clusters
- Return type
- property urban_growth_areas¶
Urban Growth Areas
- Return type
- property urbanized_areas¶
Urbanized Areas
- Return type
- property urbanized_areas_2010¶
2010 Census Urbanized Areas
- Return type
- property voting_districts¶
Voting Districts
- Return type
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 toNone
.street_1 (
str
/None
) – A street address, e.g.'4600 Silver Hill Rd'
. Defaults toNone
.street_2 (
str
/None
) – A secondary component of a street address, e.g.'Floor 3'
. Defaults toNone
.street_3 (
str
/None
) – A tertiary component of a street address, e.g.'Apt. B'
. Defaults toNone
.city (
str
/None
) – The city or town of a street address, e.g.'Washington'
. Defaults toNone
.state (
str
/None
) – The state or territory of a street address, e.g.'DC'
. Defaults toNone
.zip_code (
str
/None
) – The zip code (or zip code + 4) of a street address, e.g.'20233'
. Defaults toNone
.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
NoAddressError – if no address information is supplied
EntityNotFoundError – if no geographic entity was found matching the address supplied
UnrecognizedBenchmarkError – if the
benchmark
supplied is not recognizedUnrecognizedVintageError – if the
vintage
supplied is not recognized
- 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
ofGeographicEntity
- Raises
NoFileProvidedError – if no
file_
is providedFileNotFoundError – if
file_
does not exist on the filesystemBatchSizeTooLargeError – if
file_
contains more than 10,000 recordsEntityNotFoundError – if no geographic entity was found matching the address supplied
UnrecognizedBenchmarkError – if the
benchmark
supplied is not recognizedUnrecognizedVintageError – if the
vintage
supplied is not recognized
- 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
NoAddressError – if no address information is supplied
EntityNotFound – if no geographic entity was found matching the address supplied
UnrecognizedBenchmarkError – if the
benchmark
supplied is not recognizedUnrecognizedVintageError – if the
vintage
supplied is not recognized
- classmethod from_csv_record(csv_record)[source]¶
Create an instance of the geographic entity from its CSV record.
- classmethod from_dict(as_dict)[source]¶
Create an instance of the geographic entity from its
dict
representation.
- classmethod from_json(as_json)¶
Create an instance of the geographic entity from its JSON representation.
- inspect(as_census_fields=False)[source]¶
Produce a list of the geographic area’s properties that have values.
- Parameters
as_census_fields (
bool
) – IfTrue
, return property names as they appear in Census databases or the output of the Census Geocoder API. IfFalse
, return properties as they are defined on the Census Geocoder objects. Defaults toFalse
.- Return type
- 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-pythonicdict
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 tonull
if serialized to JSON.
- 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.
- property entity_type¶
The type of geographic entity that the object represents. Supports either:
locations
orgeographies
.- Return type
- 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).
- property is_principal_city¶
If
True
, indicates that the geography is the principal city of its surrounding entity.- Return type
- property land_area¶
The area of the geography that is on solid land, expressed in square meters.
- property latitude¶
The centroid latitude for the geographic area.
- property latitude_internal_point¶
The internal point latitude for the geographic area.
- property longitude¶
The centroid longitude for the geographic area.
- property longitude_internal_point¶
The internal point longitude for the geographic area.
- property lsad_category¶
Indicates the category of the LSAD for the geography. Returns either:
Unspecified
Prefix
Suffix
Balance
- Return type
- 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.
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.
- abstract classmethod from_dict(as_dict)[source]¶
Create an instance of the geographic entity from its
dict
representation.
- classmethod from_json(as_json)[source]¶
Create an instance of the geographic entity from its JSON representation.
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 toNone
.street_1 (
str
/None
) – A street address, e.g.'4600 Silver Hill Rd'
. Defaults toNone
.street_2 (
str
/None
) – A secondary component of a street address, e.g.'Floor 3'
. Defaults toNone
.street_3 (
str
/None
) – A tertiary component of a street address, e.g.'Apt. B'
. Defaults toNone
.city (
str
/None
) – The city or town of a street address, e.g.'Washington'
. Defaults toNone
.state (
str
/None
) – The state or territory of a street address, e.g.'DC'
. Defaults toNone
.zip_code (
str
/None
) – The zip code (or zip code + 4) of a street address, e.g.'20233'
. Defaults toNone
.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
- Raises
NoAddressError – if no address information is supplied
EntityNotFoundError – if no geographic entity was found matching the address supplied
UnrecognizedBenchmarkError – if the
benchmark
supplied is not recognizedUnrecognizedVintageError – if the
vintage
supplied is not recognized
- 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
- Raises
NoFileProvidedError – if no
file_
is providedFileNotFoundError – if
file_
does not exist on the filesystemBatchSizeTooLargeError – if
file_
contains more than 10,000 recordsEntityNotFoundError – if no geographic entity was found matching the address supplied
UnrecognizedBenchmarkError – if the
benchmark
supplied is not recognizedUnrecognizedVintageError – if the
vintage
supplied is not recognized
- 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
- Raises
NoAddressError – if no address information is supplied
EntityNotFound – if no geographic entity was found matching the address supplied
UnrecognizedBenchmarkError – if the
benchmark
supplied is not recognizedUnrecognizedVintageError – if the
vintage
supplied is not recognized
- abstract classmethod from_csv_record(csv_record)¶
Create an instance of the geographic entity from its CSV record.
- abstract classmethod from_dict(as_dict)¶
Create an instance of the geographic entity from its
dict
representation.
- classmethod from_json(as_json)¶
Create an instance of the geographic entity from its JSON representation.
- inspect(as_census_fields=False)[source]¶
Produce a list of the entity’s properties that have values.
- Parameters
as_census_fields (
bool
) – IfTrue
, return property names as they appear in Census databases or the output of the Census Geocoder API. IfFalse
, return properties as they are defined on the Census Geocoder objects. Defaults toFalse
.- Return type
- 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.