{"id":18728785,"url":"https://github.com/rubyonworld/cities","last_synced_at":"2026-04-27T08:32:12.560Z","repository":{"id":174007888,"uuid":"542155621","full_name":"RubyOnWorld/cities","owner":"RubyOnWorld","description":"Provided under an MIT license by Joe Corcoran. Thanks to hexorx for the countries gem that brought this idea about.","archived":false,"fork":false,"pushed_at":"2022-09-27T16:59:41.000Z","size":92883,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-19T20:33:02.337Z","etag":null,"topics":["corcoran","country","gem","hexorx","mit","ruby"],"latest_commit_sha":null,"homepage":"","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/RubyOnWorld.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-09-27T15:24:20.000Z","updated_at":"2022-09-27T18:07:19.000Z","dependencies_parsed_at":null,"dependency_job_id":"8becd2a8-23a4-4df1-aea7-f1f1165b40b9","html_url":"https://github.com/RubyOnWorld/cities","commit_stats":null,"previous_names":["rubyonworld/cities"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/RubyOnWorld/cities","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RubyOnWorld%2Fcities","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RubyOnWorld%2Fcities/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RubyOnWorld%2Fcities/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RubyOnWorld%2Fcities/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RubyOnWorld","download_url":"https://codeload.github.com/RubyOnWorld/cities/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RubyOnWorld%2Fcities/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32329463,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T23:26:28.701Z","status":"online","status_checked_at":"2026-04-27T02:00:06.769Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["corcoran","country","gem","hexorx","mit","ruby"],"created_at":"2024-11-07T14:24:20.644Z","updated_at":"2026-04-27T08:32:12.528Z","avatar_url":"https://github.com/RubyOnWorld.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cities\n\n[![Build Status](https://travis-ci.org/joecorcoran/cities.png?branch=master)](https://travis-ci.org/joecorcoran/cities) [![Code Climate](https://codeclimate.com/github/joecorcoran/cities.png)](https://codeclimate.com/github/joecorcoran/cities)\n\nAll the cities of the world (according to the periodically updated MaxMind database).\n\n## Data\n\nTo use this gem, you'll need the JSON data.\n\nDownload it, extract it and connect it up as follows.\n\n```\n$ wget https://s3-us-west-2.amazonaws.com/cities-gem/cities.tar.gz\n$ tar -xzf cities.tar.gz\n```\n\n```ruby\nCities.data_path = '/path/to/cities'\n```\n\n## Usage\n\nCountries are identified by their [ISO 3166-1 alpha-2](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) codes.\n\n```ruby\ncities = Cities.cities_in_country('GB')\n  #=\u003e { \"abberley\"=\u003e #\u003cCity:0x000001049b9ba0\u003e, \"abberton\"=\u003e #\u003cCity:0x000001049b9b50\u003e, ... }\n\nmcr = cities['manchester']\n  #=\u003e #\u003cCity:0x00000102fb4ea8\u003e\n\nmcr.name\n  #=\u003e \"Manchester\"\n\nmcr.population\n  #=\u003e 395516\n\nmcr.latlong\n  #=\u003e [53,5, -2.216667]\n```\n\nThe database is exhaustive and certainly stretches the definition of the word \"city\".\n\n```ruby\nCities.cities_in_country('GB')['buchlyvie'].population\n  #=\u003e 448\n```\n\n## Countries\n\nThis gem was designed as an extension to the [Countries gem](https://github.com/hexorx/countries). Installing Cities adds two new instance methods to the `Country` class.\n\n```ruby\nus = Country.search('US')\n  #=\u003e #\u003cCountry:0x000001020cf5f0\u003e\n\nus.cities?\n  #=\u003e true\n\nus.cities\n  #=\u003e { \"abanda\" =\u003e #\u003cCities::City:0x00000114b34a38\u003e, ...  }\n```\n\n## Caching\n\nSometimes you may want to not constantly want to read and parse the same large JSON data files.  So by default we cache in memory the parsed JSON.  To turn this off simply set the cache_data flag to false\n\n```ruby\nCountry.cache_data = false\n```\n\n## Configuration options available are data_path and cache_data\n\n```ruby\nCountry.configure do |config|\n  config.data_path = '../data/cities'\n  config.cache_data = false\nend\n```\n\n## Specs\n\nThe default path for data is the following path\n\n```\nGEM_ROOT/data/cities\n```\n\nOr you can set the environment variable DATA_PATH\n\nTo run the specs bundle and run specs\n```\n=\u003e bundle\n=\u003e rake\n```\n\n## Credits\n\nProvided under an MIT license by [Joe Corcoran](http://blog.joecorcoran.co.uk). Thanks to [hexorx](https://github.com/hexorx) for the countries gem that brought this idea about.\n\nThis product includes data created by MaxMind, available from [http://www.maxmind.com](http://www.maxmind.com). All data \u0026copy; 2008 MaxMind Inc. Read the [MaxMind WorldCities open data license](http://download.maxmind.com/download/geoip/database/LICENSE_WC.txt) for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frubyonworld%2Fcities","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frubyonworld%2Fcities","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frubyonworld%2Fcities/lists"}