{"id":4317,"library":"usaddress-scourgify","title":"US Address Scourgify","description":"usaddress-scourgify is a Python library (current version 0.6.0) for cleaning and normalizing US addresses, adhering to USPS Publication 28 and RESO guidelines. Released on December 14, 2023, it provides functions to standardize address strings into a consistent format. The library is built on top of the `usaddress` parsing library. While active, its release cadence appears infrequent.","status":"active","version":"0.6.0","language":"en","source_language":"en","source_url":"https://github.com/GreenBuildingRegistry/usaddress-scourgify","tags":["address","normalization","USPS","RESO","cleaning","geocoding"],"install":[{"cmd":"pip install usaddress-scourgify","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core dependency for parsing unstructured address strings.","package":"usaddress","optional":false},{"reason":"Required only for the `get_geocoder_normalized_addr` function, which uses Google Geocoding API.","package":"geocoder","optional":true},{"reason":"Used for loading custom address constants from YAML files, if the `ADDRESS_CONFIG_DIR` environment variable is set.","package":"yaml-config","optional":false}],"imports":[{"symbol":"normalize_address_record","correct":"from scourgify import normalize_address_record"},{"note":"Class for more advanced, customizable normalization behavior.","symbol":"NormalizeAddress","correct":"from scourgify import NormalizeAddress"},{"note":"Function to normalize using geocoder.google (requires API key) without additional internal cleaning.","symbol":"get_geocoder_normalized_addr","correct":"from scourgify.normalize import get_geocoder_normalized_addr"}],"quickstart":{"code":"import os\nfrom scourgify import normalize_address_record\n\naddress_str = '123 southwest Main street, Boring, OR 97009, UNIT 100'\n\n# Normalize an address string\ncleaned_address = normalize_address_record(address_str)\nprint(cleaned_address)\n\n# To get long-hand output (e.g., 'Southwest' instead of 'SW')\nlong_hand_address = normalize_address_record(address_str, long_hand=True)\nprint(long_hand_address)\n\n# Example with get_geocoder_normalized_addr (requires GOOGLE_API_KEY env var)\n# from scourgify.normalize import get_geocoder_normalized_addr\n# os.environ['GOOGLE_API_KEY'] = os.environ.get('GOOGLE_API_KEY', 'YOUR_GOOGLE_API_KEY')\n# geocoded_address = get_geocoder_normalized_addr(address_str)\n# print(geocoded_address)","lang":"python","description":"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."},"warnings":[{"fix":"Use a separate address validation service or library if validation is required.","message":"usaddress-scourgify focuses solely on cleaning and normalization; it does not perform address validation (e.g., checking if an address actually exists).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure `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.","message":"The `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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Pass `long_hand=True` to `normalize_address_record` to receive output with full word directionals and street types.","message":"By default, the library abbreviates pre/post directionals, street types, and occupancy types (e.g., 'SW Main St' instead of 'Southwest Main Street').","severity":"gotcha","affected_versions":"All versions"},{"fix":"Review 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.","message":"Custom 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.","severity":"breaking","affected_versions":"All versions (potential for break on major library updates)"},{"fix":"Upgrade 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.","message":"Parsing 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.","severity":"gotcha","affected_versions":"<0.6.0"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}