addfips 0.2.2

Installing

AddFIPS is a Python package, compatible with Python 2.7, Python 3, and pypy. It has no dependencies outside of Python’s standard libraries.

If you’ve used Python packages before:

pip install addfips
# or
pip install --user addfips

If you haven’t used Python packages before, get pip, then come back.

You can also clone the repo and install with python setup.py install.

Features

• Use full names or postal abbrevations for states

• Works with all states, territories, and the District of Columbia

• Slightly fuzzy matching allows for missing diacretic marks and different name formats (“Nye County” or “Nye’, “Saint Louis” or “St. Louis”, “Prince George’s” or “Prince Georges”)

• Includes up-to-date 2015 geographies (shout out to Kusilvak Census Area, AK, and Oglala Lakota Co., SD)

Note that some states have counties and county-equivalent independent cities with the same names (e.g. Baltimore city & County, MD, Richmond city & County, VA). AddFIPS’s behavior may pick the wrong geography if just the name (“Baltimore”) is passed.

Command line tool

usage: addfips [-h] [-V] [-d CHAR] (-s FIELD | -n NAME) [-c FIELD]
               [-v VINTAGE] [--no-header]
               [input]

AddFIPS codes to a CSV with state and/or county names

positional arguments:
  input                 Input file. default: stdin

optional arguments:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit
  -d CHAR, --delimiter CHAR
                        field delimiter. default: ,
  -s FIELD, --state-field FIELD
                        Read state name or FIPS code from this field
  -n NAME, --state-name NAME
                        Use this state for all rows
  -c FIELD, --county-field FIELD
                        Read county name from this field. If blank, only state
                        FIPS code will be added
  -v VINTAGE, --vintage VINTAGE
                        2000, 2010, or 2015. default: 2015
  --no-header           Input has no header now, interpret fields as integers
  -u, --err-unmatched   Print rows that addfips cannot match to stderr

Options and flags: * input: (positional argument) The name of the file. If blank, addfips reads from stdin. * --delimiter: Field delimiter, defaults to ‘,’. * --state-field: Name of the field containing state name * --state-name: Name, postal abbreviation or state FIPS code to use for all rows. * --county-field: Name of the field containing county name. If this is blank, the output will contain the two-character state FIPS code. * --vintage: Use earlier county names and FIPS codes. For instance, Clifton Forge city, VA, is not included in 2010 or later vintages. * --no-header: Indicates that the input file has no header. --state-field and --county-field are parsed as field indices. * --err-unmatched: Rows that addfips cannot match will be printed to stderr, rather than stdout

The output is a CSV with a new column, “fips”, appended to the front. When addfips cannot make a match, the fips column will have an empty value.

addfips data.csv --state-field fieldName > data_with_fips.csv

addfips data.csv --state-field fieldName --county-field countyName > data_with_fips.csv

addfips --no-header-row --state-field 1 --county-field 2 data_no_header.csv > data_no_header_fips.csv

addfips ny_data.csv -c county --state-name NY > ny_data_fips.csv
addfips ny_data.csv -c county --state-name 'New York' > ny_data_fips.csv
addfips ny_data.csv -c county --state-name 36 > ny_data_fips.csv

addfips -d'|' -s state pipe_delimited.dsv > result.csv
addfips -d';' -s state semicolon_delimited.dsv > result.csv

addfips --err-unmatched -s state state_data.csv > state_data_fips.csv 2> state_unmatched.csv
addfips -u -s STATE -c COUNTY county_data.csv > county_data_fips.csv 2> county_unmatched.csv

curl http://example.com/data.csv | addfips -s stateFieldName -c countyField > data_with_fips.csv
csvkit -c state,county,important huge_file.csv | addfips -s state -c county > small_file.csv

addfips culinary_data.csv -s stateFieldName -c countyField | grep -e "^17031" > culinary_data_cook_county.csv
addfips -s StateName -c CountyName data.csv | csvsort -c fips > sorted_by_fips.csv

API

AddFIPS is available for use in your Python scripts:

>>> import addfips
>>> af = addfips.AddFIPS()
>>> af.get_state_fips('Puerto Rico')
'72'
>>> af.get_county_fips('Nye', state_name='Nevada')
'32023'
>>> row = {'county': 'Cook County', 'state': 'IL'}
>>> af.add_county_fips(row, county_field="county", state_field="state")
{'county': 'Cook County', 'state': 'IL', 'fips': '17031'}

The results of AddFIPS.get_state_fips and AddFIPS.get_county_fips are strings, since FIPS codes may have leading zeros.