{"id":44453387,"url":"https://github.com/fancypixel/city-state","last_synced_at":"2026-02-12T17:04:50.028Z","repository":{"id":217295428,"uuid":"740901543","full_name":"FancyPixel/city-state","owner":"FancyPixel","description":null,"archived":false,"fork":false,"pushed_at":"2024-02-12T13:15:12.000Z","size":1317,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-03-15T23:54:10.946Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FancyPixel.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2024-01-09T09:55:03.000Z","updated_at":"2024-01-09T10:17:05.000Z","dependencies_parsed_at":"2024-02-12T12:27:41.174Z","dependency_job_id":null,"html_url":"https://github.com/FancyPixel/city-state","commit_stats":null,"previous_names":["fancypixel/city-state"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/FancyPixel/city-state","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FancyPixel%2Fcity-state","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FancyPixel%2Fcity-state/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FancyPixel%2Fcity-state/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FancyPixel%2Fcity-state/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FancyPixel","download_url":"https://codeload.github.com/FancyPixel/city-state/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FancyPixel%2Fcity-state/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29373837,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-12T08:51:36.827Z","status":"ssl_error","status_checked_at":"2026-02-12T08:51:26.849Z","response_time":55,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-12T17:04:48.199Z","updated_at":"2026-02-12T17:04:50.018Z","avatar_url":"https://github.com/FancyPixel.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# City-State Ruby Gem\n\nThe `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.\n\n## Installation\n\nAdd the gem to your Gemfile:\n\n```ruby\ngem 'city-state'\n```\n\nThen, run:\n\n```bash\n$ bundle install\n```\n\n## Listing States:\n\nRetrieve a list of states for a specified country:\n\n```ruby\nCS.states(:US)\n```\n**Note:** The gem is case-insensitive. You can use variations like `:US`, `:us`, `:Us`, `\"us\"`, and `\"US\"`.\n\n## Listing Cities:\n\nRetrieve a list of cities for a specified state and country:\n\n```ruby\nCS.cities(:AK, :US)\n```\n\nYou can also specify the country, though it's optional. The gem remembers the last country you used:\n\n```ruby\nCS.states(:BR)\n\nCS.cities(:TO)  # This will use Brazil (BR) as the country\n```\n\nMiscellaneous Notes:\n- The country is an optional argument. The gem always uses the last country that you used.\n\n## Listing Countries:\n\n```ruby\nCS.countries\n```\n\n## Missing cities and wrong names\nTo add missing cities or to rename wrong ones, create these files in your project folder:\n`db/cities-lookup.yml` and `db/states-lookup.yml` and `db/countries-lookup.yml`:\n\n### Renaming a country - `US` to `America`:\n\n```yaml\n# db/countries-lookup.yml\nUS: \"America\"\n```\n\n### Renaming a state - `California` to `Something Else`:\n\n```yaml\n# db/states-lookup.yml\nUS:\n  CA: Something Else\n```\n\n### Renaming a city:\n\n```yaml\n# db/cities-lookup.yml\nUS:\n  CA:\n    \"Burbank\": \"Bur Bank\"\n```\n\n### Adding a missing city:\n\n```yaml\n# db/cities-lookup.yml\nUS:\n  CA:\n    \"My Town\": \"My Town\"\n```\n\n### Suppressing a city (set it as a blank line):\n```yaml\n# db/cities-lookup.yml\nUS:\n  CA:\n    \"Burbank\": \"\"\n```\n\n### To use a different file instead of `db\\cities-lookup.yml`:\n\n```ruby\nCS.set_cities_lookup_file('new-city-names.yml')\n\nCS.set_states_lookup_file('new-state-names.yml')\n\nCS.set_countries_lookup_file('new-country-names.yml')\n```\n\n## Updating MaxMind database\nMaxMind update their databases weekly on Tuesdays.\n\nSince Dec 30, 2019, MaxMind requires a license key (for free) to get download updates.\n\nTo get the license key:\n1. Sign up for a MaxMind account: https://www.maxmind.com/en/geolite2/signup\n2. Create a license key: https://www.maxmind.com/en/accounts/current/license-key\n3. There's no need to download anything.\n\nTo update:\n\n```ruby\nCS.set_license_key('MY_KEY')\n\nCS.update\n```\n**Note:** Replace `MY_KEY` with your actual license key.\n\n## Manually setting a database file:\n\nYou can use an alternative database file instead of downloading from MaxMind servers:\n\n```ruby\nCS.set_maxmind_zip_url('/home/daniel/GeoLite2-City-CSV_20200324.zip')\n\nCS.update\n```\n\nor\n\n```ruby\nCS.set_maxmind_zip_url('https://example.com/GeoLite2-City-CSV_20200324.zip')\n\nCS.update\n```\n\nThe 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.\n\n## Changelog\nSee [CHANGELOG.md](CHANGELOG.md)\n\n## How this gem was created\nhttps://learnwithdaniel.com/2015/02/citystate-list-of-countries-cities-and-states-ruby/\n\n## CityState License\n**city-state** is a open source project by Daniel Loureiro with a MIT license. Also, it uses MaxMind open source database.\n\n## MaxMind License\nDatabase and Contents Copyright (c) 2020 MaxMind, Inc.\nThis 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/.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffancypixel%2Fcity-state","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffancypixel%2Fcity-state","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffancypixel%2Fcity-state/lists"}