The city-state gem offers a straightforward way to retrieve lists of states for any given country and cities for any state. It's built on the MaxMind database, making it a reliable source for such data.

This branch (main) is compatible with Ruby 3 and higher. If you are using Ruby 2, please refer to the v0 branch.

• This is the primary development branch.
• New features and improvements will be added here.
• Ensure you have Ruby 3 or higher to use the versions from this branch.

• For Ruby 2 support, please refer to the v0 branch.
• The v0 branch is in maintenance mode, which means it will only receive bug fixes and will not get any new features.

Add the gem to your Gemfile:

gem 'city-state'

Then, run:

$ bundle install

Retrieve a list of states for a specified country:

CS.states(:US)

Note: The gem is case-insensitive. You can use variations like :US, :us, :Us, "us", and "US".

Retrieve a list of cities for a specified state and country:

CS.cities(:AK, :US)

You can also specify the country, though it's optional. The gem remembers the last country you used:

CS.states(:BR)

CS.cities(:TO)  # This will use Brazil (BR) as the country

Miscellaneous Notes:

• The country is an optional argument. The gem always uses the last country that you used.

CS.countries

To add missing cities or to rename wrong ones, create these files in your project folder: db/cities-lookup.yml and db/states-lookup.yml and db/countries-lookup.yml:

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

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

# db/cities-lookup.yml
US:
  CA:
    "Burbank": "Bur Bank"

# db/cities-lookup.yml
US:
  CA:
    "My Town": "My Town"

# db/cities-lookup.yml
US:
  CA:
    "Burbank": ""

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')

MaxMind update their databases weekly on Tuesdays.

Since Dec 30, 2019, MaxMind requires a license key (for free) to get download updates.

To get the license key:

1. Sign up for a MaxMind account: https://www.maxmind.com/en/geolite2/signup
2. Create a license key: https://www.maxmind.com/en/accounts/current/license-key
3. There's no need to download anything.

To update:

CS.set_license_key('MY_KEY')

CS.update

Note: Replace MY_KEY with your actual license key.

You can use an alternative database file instead of downloading from MaxMind servers:

CS.set_maxmind_zip_url('/home/daniel/GeoLite2-City-CSV_20200324.zip')

CS.update

or

CS.set_maxmind_zip_url('https://example.com/GeoLite2-City-CSV_20200324.zip')

CS.update

The file has to be a ZIP file. And it has to contain a CVS file named GeoLite2-City-Locations-en.csv. This file must be in MaxMind's GeoLite2 City's format.

See CHANGELOG.md

https://learnwithdaniel.com/2015/02/citystate-list-of-countries-cities-and-states-ruby/

city-state is a open source project by Daniel Loureiro with a MIT license. Also, it uses MaxMind open source database.

Database and Contents Copyright (c) 2020 MaxMind, Inc. This work is licensed under the Creative Commons Attribution 3.0 Unported License. To view a copy of this license, visit http://creativecommons.org/licenses/by/3.0/.