ANALYSIS TOOL BOX

Data Processing

GeocodeUSAddresses

Geocode U.S. addresses into latitude and longitude coordinates using the U.S. Census Bureau service.

data-processingcleaningtransformationwrangling

Introduction

A column of free-text addresses can't be mapped, joined to census boundaries, or used for proximity analysis until it's converted into coordinates. GeocodeUSAddresses answers "where, geographically, is this address?" by looking up each address against the U.S. Census Bureau's free geocoding service and returning latitude and longitude, with unmatched addresses cleanly represented as NaN rather than breaking the pipeline. Reach for it as a preprocessing step for any spatial analysis, heatmap, or logistics question involving U.S. addresses.

Teaching Note

The function is particularly useful for:

  • Creating geospatial visualizations (e.g., heatmaps or point maps)
  • Performing proximity analysis (calculating distances between points)
  • Regional market segmentation based on physical location
  • Enhancing customer data with geographic coordinates for logistics
  • Preparing data for spatial joins with census tracts or block groups
  • Validating and standardizing address information for U.S. locations

Parameters

ParameterTypeDefaultDescription
dataframerequired—The pandas DataFrame containing the U.S. addresses to be geocoded.
address_column_namerequired—The name of the column in the DataFrame that contains the full address strings (e.g., '1600 Amphitheatre Parkway, Mountain View, CA 94043').
latitude_column_name'Latitude'The name of the new column to be created for storing latitude values.
longitude_column_name'Longitude'The name of the new column to be created for storing longitude values.

Returns

The input DataFrame with two additional columns for latitude and longitude. Unmatched addresses result in NaN values in these columns.

Example

python
from analysistoolbox.data_processing import GeocodeUSAddresses
import pandas as pd

# Geocode a list of corporate headquarters
companies = pd.DataFrame({
    'name': ['Google', 'Apple', 'Microsoft'],
    'address': [
        '1600 Amphitheatre Pkwy, Mountain View, CA 94043',
        'One Apple Park Way, Cupertino, CA 95014',
        'One Microsoft Way, Redmond, WA 98052'
    ]
})
companies = GeocodeUSAddresses(companies, 'address')