city-state Ruby Gem

You can rename, add, or suppress geographic entities by creating lookup files in your project. By default, the gem looks for db/cities-lookup.yml, db/states-lookup.yml, and db/countries-lookup.yml.

Renaming a country

In db/countries-lookup.yml:

US: "America"

Renaming a state

In db/states-lookup.yml (nested under the country code):

US:
  CA: Something Else

Managing cities

In db/cities-lookup.yml (nested under country and state):

• Rename: "Burbank": "Bur Bank"
• Add missing: "My Town": "My Town"
• Suppress (hide): "Burbank": "" (set to a blank line)

# db/countries-lookup.yml
US: "America"

# db/states-lookup.yml
US:
  CA: Something Else

# db/cities-lookup.yml
US:
  CA:
    "Burbank": "Bur Bank"
    "My Town": "My Town"
    "Hidden City": ""

Add city-state to your Gemfile and run bundle install to install the gem. This gem requires Ruby 3 or higher for the main branch. For Ruby 2 support, use the v0 branch.

gem 'city-state'

$ bundle install

The gem uses MaxMind data, which updates weekly on Tuesdays. Since 2019, a MaxMind license key is required to download updates.

1. Sign up at MaxMind.
2. Create a license key at MaxMind Accounts.
3. Use CS.set_license_key followed by CS.update to refresh the data.

CS.set_license_key('MY_KEY')
CS.update

The CS module manages geographic data through a tiered loading process:

1. MaxMind CSV: The source of truth for raw geographic data.
2. Local YAML Cache: Once CS.install(country) is called, data is parsed from the CSV and saved as states.{country}.yml and cities.{country}.yml in the db/ folder for faster subsequent access.
3. Lookup Tables: If configured via set_..._lookup_file, the gem applies transformations (renaming or deleting entries) to the cached data before returning it to the user.

This allows you to maintain a lightweight local cache while still having the ability to override data names without modifying the underlying MaxMind source.

If you do not want to use the default db/*.yml files, you can specify alternative paths using the following methods:

CS.set_cities_lookup_file('new-city-names.yml')
CS.set_states_lookup_file('new-state-names.yml')
CS.set_countries_lookup_file('new-country-names.yml')

Retrieve a list of cities for a specific state and country using CS.cities(state_code, country_code).

Note on Country Persistence: The country argument is optional. The gem remembers the last country used. If you omit the country, it will default to the last specified country.

# List cities for Alaska in the US
CS.cities(:AK, :US)

# Using the last used country (e.g., Brazil)
CS.states(:BR)
CS.cities(:TO) # This will use Brazil (BR) as the country

Instead of downloading from MaxMind servers, you can provide a local path or a URL to a ZIP file. The ZIP must contain a CSV file named GeoLite2-City-Locations-en.csv in the MaxMind GeoLite2 City format.

# From a local path
CS.set_maxmind_zip_url('/home/daniel/GeoLite2-City-CSV_20200324.zip')
CS.update

# From a URL
CS.set_maxmind_zip_url('https://example.com/GeoLite2-City-CSV_20200324.zip')
CS.update

If you need to rename or filter countries, states, or cities (e.g., mapping US to America), you can provide custom YAML lookup files. These files are applied to the data after it is loaded from the database.

require 'city-state'

# Set custom lookup files
CS.set_countries_lookup_file('path/to/my_countries.yml')
CS.set_states_lookup_file('path/to/my_states.yml')
CS.set_cities_lookup_file('path/to/my_cities.yml')

Use the CS module to retrieve geographic data. The gem is case-insensitive for country and state identifiers.

• CS.countries: Returns a list of all countries.
• CS.states(country_code): Returns a list of states for the specified country (e.g., :US, :us, `

Use CS.cities(state, country) to get an alphabetically sorted array of city names for a specific state within a country. The state argument is converted to an uppercase symbol.

require 'city-state'

# Returns an array like ["Austin", "Dallas", "Houston"]
texas_cities = CS.cities(:TX, :US)

Use CS.countries to get a sorted hash of all countries. The keys are ISO country codes (as symbols, e.g., :US) and the values are the full country names (strings). If the data doesn't exist, the gem will attempt to extract it from the MaxMind database.

require 'city-state'

# Returns a hash like { :US => "United States", :BR => "Brazil" }
all_countries = CS.countries

The CS.get method provides a unified interface for retrieving geographic data based on the number of arguments provided:

• CS.get (no args): Returns all countries.
• CS.get(country): Returns states for that country.
• CS.get(country, state): Returns cities for that state.

require 'city-state'

CS.get              # => { :US => "United States", ... }
CS.get(:US)         # => { :CA => "California", ... }
CS.get(:US, :TX)    # => ["Austin", "Dallas", ...]