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:
- Sign up for a MaxMind account: https://www.maxmind.com/en/geolite2/signup
- Create a license key: https://www.maxmind.com/en/accounts/current/license-key
- 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 https://creativecommons.org/licenses/by/3.0/.