FipsLookup

Overview

FipsLookup is a gem that functions as a lookup used to identify county and state FIPS codes.

What are FIPS codes? The United States Federal Communications Commission (FCC) says:

Federal Information Processing System (FIPS) Codes for States and Counties

FIPS codes are numbers which uniquely identify geographic areas. The number of digits in FIPS codes vary depending on the level of geography. State-level FIPS codes have two digits, county-level FIPS codes have five digits of which the first two are the FIPS code of the state to which the county belongs.

Note: FIPS codes are updated by the US census department they can be seen and accessed here.


Interesting challenge:
Multiple states can have the same county name — 16 states have a "Wayne County". This means a state & county pair is required to lookup and return the proper FIPS code. This gem utilizes memoization to increase lookup efficiency to csv files without adding complexity to your app.

Installation

Add this line to your application's Gemfile:

gem 'fips_lookup'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install fips_lookup

Usage


County info from lookup: .county(state_param: "state", county_name: "county name", return_nil: false)

Find County specific details using memoized hash state and county input. [ Returns state code, county fips, county name, and county class codes ]

Input the state name and county name and return the corresponding 5 digit FIPS code:

FipsLookup.county(state_param: "AL", county_name: "Autauga County") # => {:state_code=>"AL", :fips=>"01001", :name=>"Autauga County", :class_code=>"H1"}
  • state_param - (String) flexible - able to find the state using its' 2 letter abbreviation ("AL"), 2 digit FIPS number ("01"), state name ("Alabama"), or the state ANSI code ("01779775").
  • county_name - (String) must match spelling set by US Census Bureau, resource library — "Autauga County" can be found, "Autauga" can not be found.

  • return_nil - (Boolean) is an optional parameter that when used overrides any Errors from input and returns an empty hash {}.

    • Ex: FipsLookup.county(state_param: "AL", county_name: "Autauga", return_nil: true) # => {}
    • Ex: Access the [:fips] symbol after a lookup FipsLookup.county(state_param: "AL", county_name: "Autauga", return_nil: true)[:fips] # => nil


How does it work?:

Class attribute hash: @county_fips = { ["state_code", "county name"] => {:state_code, :fips, :name, :class_code} }

The county_fips hash is built of key value pairs that grows as the .county method is used. Calls to county first searches @county_fips attribute with [state_code, county_name] before opening .csv files. Therefore any duplicate calls made to county will return the value stored in @county_fips. Instance variable lasts the lifespan of the FipsLookup class.

FipsLookup.county_fips # => { ["AL", "Autauga County"] => {:state_code=>"AL", :fips=>"01001", :name=>"Autauga County", :class_code=>"H1"} }


State / County lookup using FIPS code .fips_county(fips: "fips", return_nil: return_nil=false)

Input the 5 digit FIPS code for a county and return the county name and state name in an Array:

FipsLookup.fips_county(fips: "01001") # => ["Autauga County", "AL"]
  • fips - (String) must be a 5 character string of numbers ex: "01001".
  • return_nil - (Boolean) is an optional parameter that when used overrides any Errors from input and returns nil.
    • Ex: FipsLookup.fips_county(fips: "03000", return_nil: true) # => nil


State info from lookup .state(state_param: "state", return_nil: false)

Using state information input return a dictionary of values for keys fips, state code, state name, state ansi code.

FipsLookup.state(state_param: "01") # => {:fips=>"01", :code=>"AL", :name=>"Alabama", :ansi=>"01779775"}
  • state_param - (String) flexible - able to find the state using its' 2 letter abbreviation ("AL"), 2 digit FIPS number ("01"), state name ("Alabama"), or the state ANSI code ("01779775").

  • return_nil - (Boolean) is an optional parameter that when used overrides any Errors from input and returns an empty hash {}.

  • .state functions similarly to the .county method in how it uses a memoized hash @state_fips to store state parameter lookups and return values before searching state.csv for more.

State code lookup hash STATE_CODES["state code"] # => "fips code" Can also be used for quick lookup translation between state 2-character abbreviations and state 2-digit FIPS code.

FipsLookup::STATE_CODES["AL"] #=> "01"
FipsLookup::STATE_CODES.key("01") # => "AL"


Finding state abbreviation with flexible input .find_state_code(state_param: "state", return_nil: false)

  • state_param - (String) flexible - able to find the state using its' 2 letter abbreviation ("AL"), 2 digit FIPS number ("01"), state name ("Alabama"), or the state ANSI code ("01779775").
  • return_nil - (Boolean) is an optional parameter that when used overrides any Errors from input and returns nil.
FipsLookup.find_state_code(state_param: "MicHiGan") # => "MI"


Accessing county and state .csv files in your Rails app

Data csv files are made accessible incase extra configuration is needed. Here is an example in a Rails application that displays the list of state and county names within a form. This is done by accessing the CSV files included in this gem, examples below are from Rails 7 app called Build With

Path to state.csv file .state_file

Display state codes in a select option dropdown by using CSV on the FipsLookup method accessing the state.csv file ( FipsLookup.state_file #=> "path/to/data/state.csv" )

# in controller.rb
@state_options = []
CSV.foreach(FipsLookup.state_file) do |state_row|
    @state_options << [state_row[2], state_row[1]]
end

# in html.erb (within `form_with do |form|` block)
<%= form.label :state, style: "display: block" %>
<%= form.select :state, @state_options %>

Path to state specific county csv files .county_file(state_code: "state param")

Display County name options in a select option dropdown by using CSV on the FipsLookup method accessing the county specific .csv file ( FipsLookup.county_file(state_code: "MI") #=> "path/to/data/county/MI.csv" )

  • state_param – strict parameter, must be string abbreviation of State code (suggested usage is to call .find_state_code above first)
# in controller.rb
state_code = address_params[:state] # or use find_state_code from user input
@county_options = []
CSV.foreach(FipsLookup.county_file(state_code:)) do |county_row|
    @county_options << county_row[3]
end

# in html.erb (within `form_with do |form|` block)
<%= form.label :county, style: "display: block" %>
<%= form.select :county, @county_options %>

Development

Download the repository locally, and from the directory run bin/setup to install gem dependencies.

Check installation and any changes by running rspec to run the tests.

Use bin/console to open IRB console with FipsLookup gem included and ready to use.

To install this gem onto your local machine, run bundle exec rake install.

To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

New to Ruby?

On Mac, follow steps 1 and 2 of this guide to install ruby with rbenv using brew.

For PC, consult official ruby language installation guides.

New to this gem?

  • The main working file is lib/fips_lookup.rb with usage examples in the test file: spec/fips_lookup_spec.rb
  • The first pull request contains more details to decisions and considerations when first launching gem.

Contributing

Bug reports and pull requests are welcome on GitHub at the FipsLookup repo. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the FipsLookup project's codebase, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.