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.
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
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"} }
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.
FipsLookup.fips_county(fips: "03000", return_nil: true) # => nilUsing 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"
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"
.csv files in your Rails appData 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
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 %>
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 %>
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.
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.
lib/fips_lookup.rb with usage examples in the test file: spec/fips_lookup_spec.rbBug 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.
The gem is available as open source under the terms of the MIT License.
Everyone interacting in the FipsLookup project's codebase, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.
FAQs
Unknown package
We found that fips_lookup 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
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.