us Python Package

You can install the us package using pip or uv.

pip install us
# or
uv add us

The lookup function is designed to be extensible via the fallback_func parameter. When lookup cannot find a match using its internal logic (FIPS, abbreviation, or Metaphone), it calls the provided fallback_func with the original, unmodified input.

This allows developers to implement custom matching logic (like prefix matching with startswith_fallback) without modifying the core lookup engine. Results from fallback functions are cached separately to prevent them from interfering with standard lookups.

from us.states import lookup, startswith_fallback

# If 'Cal' isn't a standard abbreviation or FIPS, 
# the fallback will catch it via prefix matching.
state = lookup("Cal", fallback_func=startswith_fallback)
print(state.name)  # Output: California

By default, Washington, DC is not included in us.STATES or related lists. To include DC automatically, set the DC_STATEHOOD environment variable to any truthy value before importing the us package.

export DC_STATEHOOD=1

A State object contains detailed geographic and administrative metadata. Key attributes include:

• fips: The Federal Information Processing Series code (string).
• name: Full name of the state.
• abbr: Two-letter postal abbreviation.
• is_territory: Boolean indicating if it is a territory.
• is_obsolete: Boolean indicating if the state is obsolete.
• is_contiguous: Boolean indicating if it is contiguous.
• is_continental: Boolean indicating if it is continental.
• statehood_year: The year the state joined the union.
• capital: Name of the state capital.
• capital_tz: IANA time zone of the capital.
• ap_abbr: Associated Press abbreviation.
• time_zones: List of IANA time zones used in the state.
• name_metaphone: Metaphone encoding of the name.
• counties: A list of County objects belonging to the state.

A County object represents a sub-division of a state and contains the following attributes:

• fips: The FIPS code for the county (string).
• ns_code: National Statistics code.
• name: The name of the county or equivalent subdivision.

Use us.states.mapping(from_field, to_field, states=None) to create a dictionary mapping one state attribute to another. By default, it uses us.STATES_AND_TERRITORIES as the source list.

import us

# Map FIPS to Abbreviation
fips_to_abbr = us.states.mapping('fips', 'abbr')

# Map Abbreviation to Name
abbr_to_name = us.states.mapping('abbr', 'name')

# Map with a specific subset of states
dc_mapping = us.states.mapping('fips', 'abbr', states=[us.states.DC])

The us.states.lookup() method accepts an optional fallback_func. This function is called if the built-in matching strategies fail. It receives the original lookup value and should return a State object or None. Fallback results are cached separately per fallback function.

import us

# Custom logic fallback
def my_fallback(val):
    return us.states.AK if val == 'the big one' else None

state = us.states.lookup('the big one', fallback_func=my_fallback)

# Using the built-in startswith_fallback for partial matches
state = us.states.lookup('calif', fallback_func=us.states.startswith_fallback)

The us package provides easy access to US states and territories. You can access specific states via attributes on us.states (e.g., us.states.MD) or use collection lists like us.STATES, us.STATES_AND_TERRITORIES, or us.STATES_AND_TERRITORIES.

import us

# Access specific state attributes
state = us.states.MD
print(state.fips)          # '24'
print(state.name)          # 'Maryland'
print(state.is_contiguous) # True

# Check if it is a territory
vi = us.states.VI
print(vi.is_territory)     # True

# Access collections
all_states = us.STATES
all_territories = us.STATES_AND_TERRITORIES
all_including_territories = us.STATES_AND_TERRITORIES

# Specialized lists
commonwealths = us.states.COMMONWEALTHS
obsolete_territories = us.states.OBSOLETE

The shapefile_urls() method on a State object returns a dictionary of URLs for 2010 Census shapefiles for various geographic regions.

import us

urls = us.states.MD.shapefile_urls()
# Available keys: 'block', 'blockgroup', 'cd', 'county', 'state', 'tract', 'zcta'

block_url = urls['block']

If your input is unpredictable (e.g., from user input), use us.states.clean_name() to strip punctuation, lowercase the text, and remove filler words like the, commonwealth, state, and of. Note that lookup() does not call this automatically; you must apply it manually.

import us

# Clean a messy string
clean = us.states.clean_name(' The state OF idaho ') # 'idaho'

# Use it with lookup
state = us.states.lookup(us.states.clean_name('The State of Maryland!'))