• Stars
    star
    479
  • Rank 91,752 (Top 2 %)
  • Language
    Python
  • License
    BSD 3-Clause "New...
  • Created over 12 years ago
  • Updated 4 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A package for easily working with US and state metadata

US: The Greatest Package in the World

A package for easily working with US and state metadata.

  • all US states and territories
  • postal abbreviations
  • Associated Press style abbreviations
  • FIPS codes
  • capitals
  • years of statehood
  • time zones
  • phonetic state name lookup
  • is contiguous or continental
  • URLs to shapefiles for state, census, congressional districts, counties, and census tracts

Installation

As per usual:

pip install us

Features

Easy access to state information:

>>> import us
>>> us.states.MD
<State:Maryland>
>>> us.states.MD.fips
'24'
>>> us.states.MD.name
'Maryland'
>>> us.states.MD.is_contiguous
True

Includes territories too:

>>> us.states.VI.name
'Virgin Islands'
>>> us.states.VI.is_territory
True
>>> us.states.MD.is_territory
False

List of all (actual) states:

>>> us.states.STATES
[<State:Alabama>, <State:Alaska>, <State:Arizona>, <State:Arkansas>, ...
>>> us.states.TERRITORIES
[<State:American Samoa>, <State:Guam>, <State:Northern Mariana Islands>, ...

And the whole shebang, if you want it:

>>> us.states.STATES_AND_TERRITORIES
[<State:Alabama>, <State:Alaska>, <State:American Samoa>, ...

For convenience, STATES, TERRITORIES, and STATES_AND_TERRITORIES can be accessed directly from the us module:

>>> us.states.STATES
[<State:Alabama>, <State:Alaska>, <State:Arizona>, <State:Arkansas>, ...
>>> us.STATES
[<State:Alabama>, <State:Alaska>, <State:Arizona>, <State:Arkansas>, ...

Some states like to be fancy and call themselves commonwealths:

>>> us.states.COMMONWEALTHS
[<State:Kentucky>, <State:Massachusetts>, <State:Pennsylvania>, <State:Virginia>]

There's also a list of obsolete territories:

>>> us.states.OBSOLETE
[<State:Dakota>, <State:Orleans>, <State:Philippine Islands>]

The state lookup method allows matching by FIPS code, abbreviation, and name:

>>> us.states.lookup('24')
<State:Maryland>
>>> us.states.lookup('MD')
<State:Maryland>
>>> us.states.lookup('md')
<State:Maryland>
>>> us.states.lookup('maryland')
<State:Maryland>

Get useful information:

>>> state = us.states.lookup('maryland')
>>> state.abbr
'MD'

And for those days that you just can't remember how to spell Mississippi, we've got phonetic name matching too:

>>> us.states.lookup('misisipi')
<State:Mississippi>

Shapefiles

You want shapefiles too? As long as you want 2010 shapefiles, we've gotcha covered.

>>> urls = us.states.MD.shapefile_urls()
>>> sorted(urls.keys())
['block', 'blockgroup', 'cd', 'county', 'state', 'tract', 'zcta']
>>> urls['block']
'https://www2.census.gov/geo/tiger/TIGER2010/TABBLOCK/2010/tl_2010_24_tabblock10.zip'

The shapefile_urls() method on the State object generates shapefile URLs for the following regions:

  • block
  • blockgroup
  • census tract (tract)
  • congressional district (cd)
  • county
  • state
  • zcta

Mappings

Mappings between various state attributes are a common need. The mapping() method will generate a lookup between two specified fields.

>>> us.states.mapping('fips', 'abbr')
{'01': 'AL', '02': 'AK', '04': 'AZ', '05': 'AR', '06': 'CA', ...
>>> us.states.mapping('abbr', 'name')
{'AL': 'Alabama', 'AK': 'Alaska', 'AZ': 'Arizona', 'AR': 'Arkansas', ...

This method uses us.STATES_AND_TERRITORIES as the default list of states it will create a mapping for, but this can be overridden by passing an additional states argument:

>>> us.states.mapping('fips', 'abbr', states=[us.states.DC])
{'11': 'DC'}

DC should be granted statehood

Washington, DC does not appear in us.STATES or any of the related state lists, but is often treated as a state in practice and should be granted statehood anyway. DC can be automatically included in these lists by setting a DC_STATEHOOD environment variable to any truthy value before importing this package.

DC_STATEHOOD=1

CLI

When you need to know state information RIGHT AWAY, there's the states script.

$ states md

*** The great state of Maryland (MD) ***

  FIPS code: 24

  other attributes:
    ap_abbr: Md.
    capital: Annapolis
    capital_tz: America/New_York
    is_contiguous: True
    is_continental: True
    is_obsolete: False
    name_metaphone: MRLNT
    statehood_year: 1788
    time_zones: America/New_York

  shapefiles:
    tract: https://www2.census.gov/geo/tiger/TIGER2010/TRACT/2010/tl_2010_24_tract10.zip
    cd: https://www2.census.gov/geo/tiger/TIGER2010/CD/111/tl_2010_24_cd111.zip
    county: https://www2.census.gov/geo/tiger/TIGER2010/COUNTY/2010/tl_2010_24_county10.zip
    state: https://www2.census.gov/geo/tiger/TIGER2010/STATE/2010/tl_2010_24_state10.zip
    zcta: https://www2.census.gov/geo/tiger/TIGER2010/ZCTA5/2010/tl_2010_24_zcta510.zip
    block: https://www2.census.gov/geo/tiger/TIGER2010/TABBLOCK/2010/tl_2010_24_tabblock10.zip
    blockgroup: https://www2.census.gov/geo/tiger/TIGER2010/BG/2010/tl_2010_24_bg10.zip

Running Tests

GitHub Actions are set up to automatically run unit tests against any new commits to the repo. To run these tests yourself:

pipenv install --dev
pipenv run pytest

Changelog

3.1.1

  • add support for Python 3.11
  • upgrade to jellyfish 0.11.2

3.0.0

  • upgrade to jellyfish 0.7.2
  • drop support for Python 2.7
  • add us.states.COMMONWEALTHS list of states that call themselves commonwealths 🎩
  • add DC to STATES, STATES_AND_TERRITORIES, STATES_CONTIGUOUS, or STATES_CONTINENTAL when DC_STATEHOOD environment variable is set
  • remove region parameter from shapefile_urls() method
  • mapping() no longer includes obsolete states
  • added type annotations

2.0.2

  • restore DC in lookup() and mapping()

2.0.1

  • fix Python 2.7 tests that ran with Python 3
  • revert to jellyfish 0.6.1 to support Python 2.7

2.0.0

  • add support for Python 3.7 and 3.8
  • remove support for Python 3.4 and 3.5
  • remove pickled objects and database in favor of pure Python code
  • upgrade jellyfish to 0.7.2 to fix metaphone bug
  • fixes for IN, KY, ND, and NM timezones
  • set AZ timezone to America/Phoenix
  • obsolete entries are no longer included in STATES_AND_TERRITORIES
  • DC is no longer included in STATES, STATES_AND_TERRITORIES, STATES_CONTIGUOUS, or STATES_CONTINENTAL

1.0.0

  • full Python 3.6 support
  • use pytest

0.10.0

  • upgrade jellyfish to 0.5.3 to fix metaphone bug

0.9.0

  • add information on whether a state is contiguous and/or continental, thanks to chebee7i

0.8.0

0.7.1

  • upgrade to jellyfish 0.5.1 to fix metaphone case bug

0.7

0.6

  • add AP-style state abbreviations
  • use jellyfish instead of Metaphone package
  • update to requests v1.0.4 for tests
  • Python 3.3 compatibility

0.5

  • fix state abbreviation for Nebraska

0.4

  • add state capitals
  • add years of statehood

0.3

  • add mapping method to generate dicts of arbitrary fields

0.2

  • add command line script for quick access to state data

0.1

  • initial release
  • state names and abbreviations
  • FIPS codes
  • lookup() method
  • shapefile URLs for various regions

More Repositories

1

congress-legislators

Members of the United States Congress, 1789-Present, in YAML/JSON/CSV, as well as committees, presidents, and vice presidents.
Python
1,927
star
2

congress

Public domain data collectors for the work of Congress, including legislation, amendments, and votes.
Python
847
star
3

contact-congress

Sending electronic written messages to members of Congress by reverse engineering their contact forms.
Python
630
star
4

districts

GeoJSON and other shape files for the federal legislative districts of the US.
260
star
5

citation

Legal citation extractor, via command line, JavaScript, or HTTP. See a live example at:
JavaScript
213
star
6

images

Public domain photos of Members of the United States Congress
Python
173
star
7

congressional-record

A parser for the Congressional Record.
HTML
119
star
8

inspectors-general

Collecting reports from Inspectors General across the US federal government.
Python
104
star
9

uscode

A working parser for the US Code's hierarchy, and a work-in-progress parser for the full content.
Python
101
star
10

APIs

A Hub of US Government APIs
CSS
59
star
11

bill-nicknames

Table of popular nicknames and keywords for bills, curated manually.
56
star
12

uslaw.link

A legal citation resolver.
JavaScript
54
star
13

unitedstates.github.io

Simple homepage for this organization.
CSS
50
star
14

glossary

A glossary for the United States.
Ruby
42
star
15

acronym

A library of government acronyms
39
star
16

orgchart

An organization chart for the government of the United States.
37
star
17

federal_spending

Importer for US Spending data
Python
34
star
18

congress-votes-servo

Tracking changes to the official U.S. House and Senate roll call votes XML data files. Monitored hourly-ish by @GovTrack/@JoshData.
HTML
33
star
19

data-seal

Data Seal is a lightweight, UELMA-compliant data authentication service.
HTML
32
star
20

licensing

Best practices language for making open government data "license-free".
HTML
27
star
21

rtyaml

All the annoying stuff we had to do to make YAML usable.
Python
27
star
22

congress-data

Legislative data from the congress repository
19
star
23

complaints

An index of formal complaint systems
17
star
24

wish-list

A wish list for this organization, open an Issue to discuss what we can add. Derived from a News Foo session.
16
star
25

domains

Organizing and publishing the web domains of the US federal government
16
star
26

petitions

White House petition crawler.
Python
15
star
27

data-releases

A listing of public data releases by federal agencies
15
star
28

BillMap

Utilities and applications for the FlatGov project by Demand Progress
JavaScript
14
star
29

legisworks-historical-statutes

Metadata and per-statute PDFs for the U.S. Statutes at Large through volume 64 (1789-1951).
Python
14
star
30

am_mem_law

Documentation & data for the Library of Congress American Memory Century of Lawmaking collection.
Python
12
star
31

agency-regions

A collection of data about how federal agencies divide their agency coverage geospatially
11
star
32

scotus-bound-volumes

11
star
33

chaplains

Text of prayers delivered by guest chaplains to House
Python
11
star
34

reports

Storage space for public US reports which need a place to go.
HTML
10
star
35

statements-of-administration-policy

An archive and scraper of White House Statements of Administration Policy
Python
9
star
36

nabors

Bill numbers for early American statutes based on Nabors's Legislative Reference Checklist book.
Python
8
star
37

congress-publish

Script to publish bill and amendment data as a JSON API.
Python
8
star
38

congress-calendar

A calendar of Congressional events, like committee meetings and votes
6
star
39

data-issues

(NO LONGER USED.)
3
star