US Census Geocoder

Required Extra

To use the CensusGeocoder connector, you will need to install parsons with the geocode extra. To do this, you will need to install it with pip install parsons[geocode] or pip install parsons[all]. For more information, see our Installation notes.

Overview

The US Census Geocoder leverages the US Census Geocoding service for single record and batch geocoding. The service enforces no limits and is free to US. More information can be found at the US Census website. For multiple records, it is recommended that you use the geocode_address_batch() method.

API

class parsons.geocode.census_geocoder.CensusGeocoder(benchmark='Public_AR_Current', vintage='Current_Current', timeout=None)[source]

Instantiate the CensusGecoder Class

Parameters:

  • benchmark – str The US Census benchmark file to utilize. By default the current benchmark is used, but other options can found here.

  • vintage – str The US Census vintage file to utilize. By default the current vintage is used, but other options can be found here.

  • timeout – float Seconds to wait for a response from the Census API before raising requests.exceptions.Timeout. Applies to every request this class makes. By default no timeout is set, and a request can block indefinitely.

geocode_onelineaddress(address, return_type='geographies')[source]

Geocode a single line address. Does not require parsing of city and zipcode field. Returns geocode as well as other census block data. If the service is unable to geocode the address it will return an empty list.

Parameters:

  • address – str A valid US address

  • return_type – str geographies will return information about the Census geographies while locations will information about the address.

Returns:

dict

geocode_address(address_line, city=None, state=None, zipcode=None, return_type='geographies')[source]

Geocode an address by specifying address fields. Returns the geocode as well as other census block data.

Parameters:

  • address_line – str A valid address line

  • city – str A valid city

  • state – str A valid two character state abbreviation (e.g. ‘IL’)

  • zipcode – int A valid five digit zipcode (e.g. 60622)

  • return_type – str geographies will return information about the Census geographies while locations will information about the address.

Returns:

dict

geocode_address_batch(table)[source]

Geocode multiple addresses from a parsons table.

The table must only include the following columns in the following order.

Column Names

id (must be unique)

street

city

state

zip
Parameters:

table – Parsons Table A Parsons table

Returns:

A Parsons table

get_coordinates_data(latitude: float, longitude: float) → GeographyResult[source]

Return census data on coordinates.

Parameters:

  • latitude (float) – A valid latitude in the United States

  • longitude (float) – A valid longitude in the United States

Return type:

GeographyResult