https://github.com/rubyonworld/cities
Provided under an MIT license by Joe Corcoran. Thanks to hexorx for the countries gem that brought this idea about.
https://github.com/rubyonworld/cities
corcoran country gem hexorx mit ruby
Last synced: about 1 month ago
JSON representation
Provided under an MIT license by Joe Corcoran. Thanks to hexorx for the countries gem that brought this idea about.
- Host: GitHub
- URL: https://github.com/rubyonworld/cities
- Owner: RubyOnWorld
- License: mit
- Created: 2022-09-27T15:24:20.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2022-09-27T16:59:41.000Z (over 3 years ago)
- Last Synced: 2025-05-19T20:33:02.337Z (about 1 year ago)
- Topics: corcoran, country, gem, hexorx, mit, ruby
- Language: Ruby
- Homepage:
- Size: 88.6 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Cities
[](https://travis-ci.org/joecorcoran/cities) [](https://codeclimate.com/github/joecorcoran/cities)
All the cities of the world (according to the periodically updated MaxMind database).
## Data
To use this gem, you'll need the JSON data.
Download it, extract it and connect it up as follows.
```
$ wget https://s3-us-west-2.amazonaws.com/cities-gem/cities.tar.gz
$ tar -xzf cities.tar.gz
```
```ruby
Cities.data_path = '/path/to/cities'
```
## Usage
Countries are identified by their [ISO 3166-1 alpha-2](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) codes.
```ruby
cities = Cities.cities_in_country('GB')
#=> { "abberley"=> #, "abberton"=> #, ... }
mcr = cities['manchester']
#=> #
mcr.name
#=> "Manchester"
mcr.population
#=> 395516
mcr.latlong
#=> [53,5, -2.216667]
```
The database is exhaustive and certainly stretches the definition of the word "city".
```ruby
Cities.cities_in_country('GB')['buchlyvie'].population
#=> 448
```
## Countries
This 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.
```ruby
us = Country.search('US')
#=> #
us.cities?
#=> true
us.cities
#=> { "abanda" => #, ... }
```
## Caching
Sometimes 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
```ruby
Country.cache_data = false
```
## Configuration options available are data_path and cache_data
```ruby
Country.configure do |config|
config.data_path = '../data/cities'
config.cache_data = false
end
```
## Specs
The default path for data is the following path
```
GEM_ROOT/data/cities
```
Or you can set the environment variable DATA_PATH
To run the specs bundle and run specs
```
=> bundle
=> rake
```
## Credits
Provided 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.
This product includes data created by MaxMind, available from [http://www.maxmind.com](http://www.maxmind.com). All data © 2008 MaxMind Inc. Read the [MaxMind WorldCities open data license](http://download.maxmind.com/download/geoip/database/LICENSE_WC.txt) for more details.