Install & Compatibility
Where this runs
tested against v0.7.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.204s · 28MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.0s · import 0.194s · 27MB
25MB installed
● package 25MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
normalize_address_record
✓ from scourgify import normalize_address_record
NormalizeAddress
✓ from scourgify import NormalizeAddress
Class for more advanced, customizable normalization behavior.
get_geocoder_normalized_addr
✓ from scourgify.normalize import get_geocoder_normalized_addr
Function to normalize using geocoder.google (requires API key) without additional internal cleaning.
This quickstart demonstrates how to use the `normalize_address_record` function to clean and standardize a US address string. It also shows how to request long-hand output and includes a commented-out example for `get_geocoder_normalized_addr` which requires a Google API key.
import os
from scourgify import normalize_address_record
address_str = '123 southwest Main street, Boring, OR 97009, UNIT 100'
# Normalize an address string
cleaned_address = normalize_address_record(address_str)
print(cleaned_address)
# To get long-hand output (e.g., 'Southwest' instead of 'SW')
long_hand_address = normalize_address_record(address_str, long_hand=True)
print(long_hand_address)
# Example with get_geocoder_normalized_addr (requires GOOGLE_API_KEY env var)
# from scourgify.normalize import get_geocoder_normalized_addr
# os.environ['GOOGLE_API_KEY'] = os.environ.get('GOOGLE_API_KEY', 'YOUR_GOOGLE_API_KEY')
# geocoded_address = get_geocoder_normalized_addr(address_str)
# print(geocoded_address)
Debug
Known issues
gotchausaddress-scourgify focuses solely on cleaning and normalization; it does not perform address validation (e.g., checking if an address actually exists).fixUse a separate address validation service or library if validation is required.
affects: All versions
gotchaThe `get_geocoder_normalized_addr` function relies on `geocoder.google` and requires the `GOOGLE_API_KEY` environment variable to be set. This function performs no additional internal cleaning, so addresses with stray or non-conforming elements may result in no output.fixEnsure `GOOGLE_API_KEY` is set. Pre-clean addresses manually or use `normalize_address_record` for internal cleaning before attempting geocoder-based normalization if initial string quality is low.
affects: All versions
gotchaBy default, the library abbreviates pre/post directionals, street types, and occupancy types (e.g., 'SW Main St' instead of 'Southwest Main Street').fixPass `long_hand=True` to `normalize_address_record` to receive output with full word directionals and street types.
affects: All versions
breakingCustom address constants can be defined using a YAML file specified by the `ADDRESS_CONFIG_DIR` environment variable. Changes to the internal constant structure in new library versions may break or alter the behavior of custom configurations.fixReview the `CHANGELOG.rst` and `address_constants.py` file in the library's source for structural changes to constants when updating. Test custom configurations thoroughly after any library upgrade.
affects: All versions (potential for break on major library updates)
gotchaParsing of PO Box addresses was problematic in versions prior to 0.6.0 due to how ambiguous labels were handled. While resolved in v0.6.0, complex PO Box formats might still require careful input formatting.fixUpgrade to version 0.6.0 or later. For older versions, ensure PO Box strings are consistently formatted to avoid parsing errors. Test edge cases with complex PO Box identifiers.
affects: <0.6.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'usaddress-scourgify'
Python module imports use underscores (`_`) instead of hyphens (`-`), even if the package name uses hyphens for `pip install`.
fixUse `usaddress_scourgify` for importing: `from usaddress_scourgify import standardize_address`
TypeError: expected string or bytes-like object
The `standardize_address` function requires a string input, but was called with a non-string type like `None`, an integer, or a list.
fixEnsure the input to `standardize_address` is always a string: `standardize_address('123 Main St')` TypeError: 'NoneType' object is not subscriptable
The `standardize_address` function returned `None` (indicating an inability to parse the address), and the code then attempted to access it like a dictionary.
fixAlways check if the result of `standardize_address` is not `None` before attempting to access its keys: `result = standardize_address(address_str); if result: print(result['Number'])`
TypeError: 'str' object is not iterable
The `components` argument of `standardize_address` expects an iterable (like a list or tuple) of component names, but was provided with a single string.
fixPass a list or tuple for the `components` argument, even if only specifying one component: `standardize_address('123 Main St', components=['StreetName'])` Upgrade
Version history
0.7.1latest on PyPI · released Aug 7, 2026
Audit
Dependencies
usaddressrequiredCore dependency for parsing unstructured address strings.
geocoderoptionalRequired only for the `get_geocoder_normalized_addr` function, which uses Google Geocoding API.
yaml-configrequiredUsed for loading custom address constants from YAML files, if the `ADDRESS_CONFIG_DIR` environment variable is set.