---
id: us
version: "3.2.0"
license: Copyright (c) 2014, Sunlight Labs All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: *… (full text in the JSON record)
license_treatment: unclear
maintenance: active
---

# us — US state meta information and other fun stuff

License: unclear · Maintenance: active · Downloads: 2.4M/mo

## 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 above — 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

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

- License: Copyright (c) 2014, Sunlight Labs All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: *… (full text in the JSON record) (unclear)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 2.4M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

us state metadata lookup, fips code state abbreviation, state information library, us territories postal codes, state shapefile urls, phonetic state name matching, state time zones, us geographic data, reference-data, us-geography, metadata

[View on SkillFed](https://skillfed.io/packages/us) · [View on PyPI](https://pypi.org/project/us/)