us

us

NPM module of US states

Showing:

Popularity

Downloads/wk

16.1K

GitHub Stars

24

Maintenance

Last Commit

5yrs ago

Contributors

6

Package

Dependencies

0

Size (min+gzip)

3.9KB

License

Type Definitions

Tree-Shakeable

No?

Categories

Readme

javascript-us

NPM module of US state metadata. Heavily based on python-us

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

Installation

As per usual:

$ npm install us

Features

Easy access to state information:

> var us = require('us')
> us.states.MD
{ name: 'Maryland',
  metaphones: [ 'MRLNT' ],
  statehood_year: 1788,
  ap_abbr: 'Md.',
  is_territory: false,
  fips: '24',
  abbr: 'MD',
  capital: 'Annapolis',
  capital_tz: 'America/New_York',
  time_zones: [ 'America/New_York' ] }
> us.states.MD.fips
'24'
> us.states.MD.name
'Maryland'
>

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
[ { name: 'Alabama',
    ... },
  { name: 'Alaska',
    ... }, ...
> us.TERRITORIES
[ { name: 'American Samoa',
    ... },
  { name: 'Guam',
    ... }, ...

And the whole shebang, if you want it:

> us.STATES_AND_TERRITORIES
[ { name: 'Alabama',
    ... },
  { name: 'Alaska',
    ... }, ...
  { name: 'American Samoa',
    ... }, ...

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

> us.lookup('24')
{ name: 'Maryland',
  ... }
> us.lookup('MD')
{ name: 'Maryland',
  ... }
> us.lookup('md')
{ name: 'Maryland',
  ... }
> us.lookup('maryland')
{ name: 'Maryland',
  ... }
>

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

> us.lookup('misisipi')
{ name: 'Mississippi'
  ... }

Shapefiles

You want shapefiles too? Gotcha covered.

> us.states.MD.shapefile_urls()
{ tract: 'http://www2.census.gov/geo/tiger/TIGER2010/TRACT/2010/tl_2010_24_tract10.zip',
  cd: 'http://www2.census.gov/geo/tiger/TIGER2010/CD/111/tl_2010_24_cd111.zip',
  county: 'http://www2.census.gov/geo/tiger/TIGER2010/COUNTY/2010/tl_2010_24_county10.zip',
  state: 'http://www2.census.gov/geo/tiger/TIGER2010/STATE/2010/tl_2010_24_state10.zip',
  zcta: 'http://www2.census.gov/geo/tiger/TIGER2010/ZCTA5/2010/tl_2010_24_zcta510.zip',
  block: 'http://www2.census.gov/geo/tiger/TIGER2010/TABBLOCK/2010/tl_2010_24_tabblock10.zip',
  blockgroup: 'http://www2.census.gov/geo/tiger/TIGER2010/BG/2010/tl_2010_24_bg10.zip' }

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

  • state
  • county
  • congressional district
  • zcta
  • census tract

If you know what region you want, you can explicitly request it:

> us.states.MD.shapefile_urls('county')
'http://www2.census.gov/geo/tiger/TIGER2010/COUNTY/2010/tl_2010_24_county10.zip'

Mappings

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

> us.mapping('fips', 'abbr');
{ '10': 'DE',
  '11': 'DC', ...
> us.mapping('abbr', 'name')
{ AL: 'Alabama',
  AK: 'Alaska', ...

Contributing

Please fork on github and send a pull request. Your contributions are welcomed!

Credits

Contributors to javascript-us:

  • Andy Burke added testing and support for common miss-spellings
  • Patrick Way ported to javascript
  • rab added AMD module compatibility

Contributors to python-us:

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100