US State Meta Information

3.2.0 · active · verified Fri Apr 10

The 'us' library provides an easy way to work with US state and territory meta information, offering data such as names, abbreviations, FIPS codes, and contiguous status. It also includes functions for looking up states by various criteria. The current version is 3.2.0, and it generally follows an active release cadence, with updates for Python version compatibility and dependency upgrades.

Warnings

breaking Python 3.6 and 3.7 support has been officially dropped starting with 'us' version 3.2.0. Projects using these older Python versions must upgrade their Python interpreter or pin 'us' to a version prior to 3.2.0.
Fix: Upgrade your Python environment to 3.8 or newer. If unable to upgrade Python, pin 'us' to '<3.2.0' in your project's dependencies (e.g., `us<3.2.0`).
breaking The `jellyfish` dependency, used for fuzzy matching in functions like `us.states.match()`, was upgraded to `jellyfish` 1.x in 'us' version 3.2.0. If your project has a direct dependency on an older `jellyfish` version, this upgrade might introduce conflicts or require adjustments.
Fix: Ensure your project's `jellyfish` dependency is compatible with `jellyfish` 1.x. Review `jellyfish`'s changelog for any breaking changes if you directly use `jellyfish` functions.
gotcha Functions like `us.states.match()` return a list of potentially matching state objects, even if only one match is found. Always account for this when processing the results, as direct access (e.g., `[0]`) might lead to `IndexError` if no matches are found.
Fix: Always check if the returned list from `match()` or similar functions is not empty before accessing elements (e.g., `if matched_states: state = matched_states[0]`).
gotcha The `us.states.lookup()` function is more strict and returns `None` if no exact match is found (after an optional fuzzy search). Always check for `None` before accessing attributes of the returned object.
Fix: When using `us.states.lookup()`, always perform a `None` check (e.g., `state = us.states.lookup('NotAState'); if state: print(state.name)`).

Install

pip install us Install latest version

Imports

us
```
import us
```
Imports the main 'us' module, providing access to submodules like `us.states` and `us.territories`.
states
```
import us.states
```
Directly imports the `states` submodule for state-specific operations.
territories
```
import us.territories
```
Directly imports the `territories` submodule for territory-specific operations.

Quickstart

The quickstart demonstrates how to import the `us` library and access state and territory objects. It shows direct access by abbreviation, lookup by name, fuzzy matching, and accessing lists of all entities. It also includes accessing the `unitedstatesofamerica` object and its new `birthday` attribute.

import us

# Access state objects directly
california = us.states.CA
print(f"California FIPS: {california.fips}")

# Look up states by name, abbreviation, or FIPS code
new_york = us.states.lookup('New York')
print(f"New York abbr: {new_york.abbr}")

# Fuzzy matching (requires 'jellyfish' library)
matched_states = us.states.match('Kanzus')
if matched_states:
    print(f"Did you mean: {matched_states.name} ({matched_states.abbr})?")

# Access a list of all states and territories
print(f"Total states and territories: {len(us.states.all) + len(us.territories.all)}")

# Access special objects like 'unitedstatesofamerica'
usa = us.unitedstatesofamerica
print(f"USA name: {usa.name}, Birthday: {usa.birthday}")

view raw JSON →