A package for easily working with US and state metadata.
As per usual:
pip install us
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>
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:
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'}
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
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
GitHub Actions are set up to automatically run unit tests against any new commits to the repo. To run these tests yourself:
pip install -e .[dev]
pytest .
region
parameter from shapefile_urls()
methodmapping()
no longer includes obsolete stateslookup()
and mapping()
lookup()
method