FIPS Lookup

fips_lookup provides lookups for U.S. states, counties, and county subdivisions using Census FIPS identifiers and names. Results are hashes containing the fields for the requested geography.

Add the gem to your application's Gemfile:

gem "fips_lookup"

Then run bundle install.

Require the gem if your application does not use Bundler's automatic loading:

require "fips"

FIPS.lookup dispatches to the state, county, or subdivision lookup based on the supplied identifiers:

FIPS.lookup(fips: "02")
# => { fips: "02", abbr: "AK", name: "Alaska", ansi: "01785533" }

FIPS.lookup(fips: "02060")
# => county record for Bristol Bay Borough

FIPS.lookup(fips: "0206009050")
# => subdivision record for Bristol Bay census subarea

FIPS.lookup(state: "Alaska", county: "Bristol Bay Borough")
# => county record for Bristol Bay Borough

FIPS.lookup(state: "Alaska", county: "Bristol Bay Borough",
            subdivision: "Bristol Bay census subarea")
# => subdivision record for Bristol Bay census subarea

FIPS codes must be strings so leading zeroes are preserved. The general dispatcher supports state FIPS (2 digits), county FIPS (5 digits), and full subdivision FIPS (10 digits). Contextual forms are also available through the specific lookup methods below.

FIPS::State.lookup(fips: "02")
FIPS::State.lookup(state: "AK")
FIPS::State.lookup(state: "Alaska")
FIPS::State.lookup(state: "01785533") # ANSI code

The returned state hash has :fips, :abbr, :name, and :ansi keys. FIPS::State.all returns all state records in the same format:

FIPS::State.all.map { |state| [state[:name], state[:abbr]] }

FIPS::County.lookup(fips: "02060")
FIPS::County.lookup(fips: "060", state: "AK")
FIPS::County.lookup(fips: "02", county: "Bristol Bay Borough")
FIPS::County.lookup(state: "Alaska", county: "Bristol Bay Borough")

The returned county hash has :state_abbr, :fips, :gnis, :name, :class_code, and :status keys. State identifiers may be an abbreviation, name, FIPS code, or ANSI code.

To list counties in a state, use FIPS::County.all:

counties = FIPS::County.all(state: "AK")
county_names = counties.map { |county| county[:name] }

FIPS::Subdivision.lookup(fips: "0206009050")
FIPS::Subdivision.lookup(fips: "09050", state: "AK")
FIPS::Subdivision.lookup(fips: "02060", subdivision: "Bristol Bay census subarea")
FIPS::Subdivision.lookup(fips: "060", state: "AK",
                         subdivision: "Bristol Bay census subarea")
FIPS::Subdivision.lookup(state: "Alaska", county: "Bristol Bay Borough",
                         subdivision: "Bristol Bay census subarea")

The returned subdivision hash has :state_abbr, :fips, :county_name, :gnis, :name, :class_code, and :status keys. To retrieve subdivision records for a state, optionally filtered by county:

FIPS::Subdivision.all(state: "AK")
FIPS::Subdivision.all(state: "AK", county: "Bristol Bay Borough")

County and subdivision name matching is case-insensitive. State identifiers accept abbreviations, names, FIPS codes, and ANSI codes.

The file helpers return paths to the bundled CSV data when direct access is needed:

FIPS::State.file
FIPS::County.file("AK")
FIPS::Subdivision.file("AK")

For normal listing and lookup workflows, prefer the all and lookup methods, which return formatted records without requiring callers to parse CSV rows.

Malformed or insufficient inputs raise ArgumentError. Validly formatted identifiers that do not match a record raise FIPS::NotFoundError, a subclass of StandardError:

begin
  FIPS::County.lookup(fips: "02999")
rescue FIPS::NotFoundError => error
  warn error.message
end

Install dependencies with bin/setup. Run tests and lint with:

bundle exec rspec
bundle exec rubocop

Open an IRB console with bin/console. Install locally with bundle exec rake install.

Bug reports and pull requests are welcome in the FIPS repository. Contributors are expected to follow the Code of Conduct.

This gem is available under the terms of the MIT License. See LICENSE.txt.