US Census Geocoder Wrapper

0.5.3 · active · verified Fri Apr 17

censusgeocode is a thin Python wrapper for the US Census Geocoder API, providing an easy-to-use interface to access its geocoding services. It allows users to geocode single addresses or batches of addresses programmatically. The current version is 0.5.3, with releases typically driven by bug fixes, upstream API changes, or minor feature enhancements.

Common errors

```
urllib.error.URLError: <urlopen error [Errno 111] Connection refused>
```
cause Older versions of `censusgeocode` (prior to 0.5.3) could encounter `urllib.error.URLError` or similar connection issues due to underlying HTTP library usage, especially in specific network environments or with certain TLS/SSL configurations.

fix Upgrade `censusgeocode` to version 0.5.3 or newer to benefit from fixes addressing these connection stability issues: `pip install --upgrade censusgeocode`.
```
TypeError: 'NoneType' object is not subscriptable
```
cause Users of `censusgeocode` versions older than `0.4.3.post1` might encounter `TypeError` when attempting to process results from `addressbatch` calls, particularly in certain Python versions, due to a bug in parsing malformed or empty responses.

fix Upgrade `censusgeocode` to version `0.4.3.post1` or newer: `pip install --upgrade censusgeocode`. This version includes a fix for parsing `addressbatch` results.

Warnings

gotcha The `address()` method returns an empty list (`[]`) if no match is found for the given address, rather than `None` or raising an error. Users should explicitly check for an empty list to determine if an address was successfully geocoded.
Fix: Always check if the returned list is empty: `result = cg.address(...); if not result: print('No match found'); else: print(result[0])`.
gotcha Attempting to geocode more than 10,000 addresses in a single `addressbatch` call will result in a warning from the library and the Census API may reject the request or return partial results. This is a limit of the Census API.
Fix: Split large batches into smaller chunks, each containing 10,000 records or fewer, and process them sequentially.

Install

pip install censusgeocode Install stable version

Imports

CensusGeocode
```
from censusgeocode import CensusGeocode
```

geocode

import censusgeocode
censusgeocode.geocode(...)

Quickstart

This example demonstrates how to initialize the `CensusGeocode` client and perform both single address and batch geocoding. The US Census Geocoder API typically does not require an API key for public use.

import censusgeocode

# Initialize the geocoder client
cg = censusgeocode.CensusGeocode()

# Geocode a single address
single_address_result = cg.address(
    street="123 Main St", 
    city="Anytown", 
    state="CA", 
    zipcode="90210"
)
print(f"Single address result: {single_address_result}")

# Prepare addresses for batch geocoding
# The Census Geocoder public API generally does not require an API key.
batch_addresses = [
    {"id": 1, "street": "123 Main St", "city": "Anytown", "state": "CA", "zipcode": "90210"},
    {"id": 2, "street": "456 Oak Ave", "city": "Someville", "state": "NY", "zipcode": "10001"}
]

# Geocode a batch of addresses
batch_result = cg.addressbatch(batch_addresses)
print(f"Batch address result: {batch_result}")

view raw JSON →