repository·dev·Indexed 42 days ago
https://github.com/greenbuildingregistry/usaddress-scourgifyA Python library for cleaning and normalizing US addresses according to USPS pub 28 and RESO guidelines. It provides the normalize_address_record() function and NormalizeAddress class to standardize address components into uppercase dictionaries, with support for custom mapping, YAML-based configuration of address constants, and Google Geocoder integration.
Parsing single-string addresses can fail when multi-word street names or city names are also street types (e.g., 'Via Christina' or 'LA TORTOLA'). In these cases, the underlying usaddress parser may misidentify parts of the address.
Solution: To avoid parsing errors, provide the address as a dictionary instead of a single string. This allows you to explicitly define the city and street components before normalization.
Install the library using pip. Requires Python 3.x.
pip install usaddress-scourgifyYou can customize the abbreviation mappings and constants used by the library by creating an address_constants.yaml file.
Supported Keys:
DIRECTIONAL_REPLACEMENTSOCCUPANCY_TYPE_ABBREVIATIONSSTATE_ABBREVIATIONSSTREET_TYPE_ABBREVIATIONSKNOWN_ODDITIESPROBLEM_ST_TYPE_ABBRVSInsertion Method:
You can use the insertion_method key with values update (default) or replace to determine how your custom values are merged with existing constants.
Environment Variable:
Set ADDRESS_CONFIG_DIR to the full path of the directory containing your address_constants.yaml file.
insertion_method: update
KNOWN_ODDITIES:
'developed by HOST': ''
', UN ': ' UNIT '
OCCUPANCY_TYPE_ABBREVIATIONS:
'UN': 'UNIT'The get_geocoder_normalized_addr() function uses geocoder.google to parse an address string into a standard dictionary.
Important Notes:
Environment Variable:
Set GOOGLE_API_KEY to your Google API key to use this feature.
export GOOGLE_API_KEY=your_google_api_keyIf your input dictionary uses keys other than the standard address_line_1, address_line_2, city, state, and postal_code, use the addr_map parameter to provide a mapping in the format {standard_key: custom_key}.
# Example mapping for non-standard keys
addr_map = {
'address_line_1': 'Line1',
'address_line_2': 'Line2',
'city': 'City',
'state': 'State',
'postal_code': 'Zip'
}
# Use this map when calling normalization functions
# (Note: Implementation context implies passing this to the function/class)addtl_funcs parameter. This parameter accepts a list of callables. Each callable must take a string address as input and return a tuple of two strings: (line1, line2).The NormalizeAddress class provides an object-oriented way to standardize addresses. You can instantiate the class with an address string or dict and call the .normalize() method. You can also extend this class to customize normalization behavior by overriding its methods.
from scourgify import NormalizeAddress
# Standard normalization
NormalizeAddress('123 southwest Main street, Boring, or, 97203').normalize()
# Long hand normalization
NormalizeAddress('123 southwest Main street, Boring, or, 97203', long_hand=True).normalize()Use normalize_address_record() to clean and normalize US addresses following USPS pub 28 and RESO guidelines. It accepts an address string or a dict-like object and returns a dictionary with uppercase values mapped to standard keys: address_line_1, address_line_2, city, state, and postal_code.
By default, it abbreviates directionals, street types, and occupancy types. To receive full word versions instead, set long_hand=True.
from scourgify import normalize_address_record
# From a string
normalize_address_record('123 southwest Main street, Boring, or, 97203')
# From a dict
normalize_address_record({
'address_line_1': '123 southwest Main street',
'address_line_2': 'unit 2',
'city': 'Boring',
'state': 'or',
'postal_code': '97203'
})
# Using long_hand for full words
normalize_address_record('123 southwest Main street, Boring, or, 97203', long_hand=True)