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() methodFAQs
US state meta information and other fun stuff
We found that us demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Fluent Assertions is facing backlash after dropping the Apache license for a commercial model, leaving users blindsided and questioning contributor rights.
Research
Security News
Socket researchers uncover the risks of a malicious Python package targeting Discord developers.
Security News
The UK is proposing a bold ban on ransomware payments by public entities to disrupt cybercrime, protect critical services, and lead global cybersecurity efforts.