us

What it is and what it does

The us package is a reference library for US state and territory data. It provides programmatic access to states and territories with their postal abbreviations, FIPS codes, capitals, statehood years, time zones, and geographic classifications (contiguous, continental). It includes a phonetic name lookup powered by jellyfish for fuzzy matching and generates URLs to 2010 Census Bureau shapefiles for various geographic regions (state, county, congressional district, census tract, block, etc.). The package also offers a command-line tool for quick lookups and a mapping function to generate dictionaries between any two state attributes.

It is designed for developers building applications that need authoritative US geographic metadata—data validation, address parsing, geographic analysis, or administrative dashboards. The library is pure Python with minimal dependencies, installs quickly, and has been maintained since its early releases with active support for modern Python versions. DC can optionally be included in state lists via an environment variable.

Use it for:

• Validate and normalize US state abbreviations or FIPS codes in address or form-processing pipelines.
• Build geographic dashboards or reports that need state capitals, time zones, or contiguity information.
• Download Census Bureau shapefiles for mapping or GIS analysis by state or region.
• Implement fuzzy state name matching in user-facing search or autocomplete features.
• Generate lookup tables mapping between FIPS codes, postal abbreviations, and state names for data integration.
• Query state metadata (statehood year, time zone, AP abbreviation) for reference or display purposes.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Provides structured access to US state and territory metadata including postal abbreviations, FIPS codes, capitals, time zones, and shapefile URLs for geographic regions.

Yes. The package is actively maintained, has low install friction, carries no known vulnerabilities, and solves a common reference-data problem with a clean API. The unclear license treatment is a minor concern—review the BSD text if you have strict compliance requirements—but poses no practical barrier for most projects. Install it if you need reliable US state metadata or geographic lookups.

Install

us on PyPI

pip install us

uv add us

poetry add us

Installing us

Before you install

Low friction installation with a single pure-Python runtime dependency (jellyfish). Actively maintained with recent commits and support for current Python versions (3.8–3.12).

License in practice

License treatment is unclear; the package carries a BSD-style license from Sunlight Labs but lacks an SPDX identifier. Review the full license text before use in proprietary or copyleft projects.

Quickstart

pip install us

import us
state = us.states.lookup('maryland')
print(state.fips, state.abbr, state.name)

Verify before relying

• Whether the unclear license treatment poses a practical barrier for your project's license compliance requirements.
• Whether phonetic matching accuracy via jellyfish meets your tolerance for fuzzy state name lookups.
• Total number of US states and territories covered by the package.

Package facts

Evidence: us-3.2.0-py3-none-any.whl

Tags

More Utilities packages