World city data in Ruby
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib Adding configurtion module to the gem. Adding the ability to cache th… Mar 29, 2015
spec Adding configurtion module to the gem. Adding the ability to cache th… Mar 29, 2015
.gitignore Remove lock Oct 29, 2013
.travis.yml Actually add this in the right place Jan 24, 2016
CODE_OF_CONDUCT.md Add code of conduct from contributor-covenant.org Jan 24, 2016
Gemfile
LICENSE.txt Initial commit to cities. Sep 20, 2011
README.md Adding configurtion module to the gem. Adding the ability to cache th… Mar 29, 2015
Rakefile Add dirty Rake tasks for munging data Apr 24, 2014
cities.gemspec

README.md

Cities

Build Status Code Climate

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
Cities.data_path = '/path/to/cities'

Usage

Countries are identified by their ISO 3166-1 alpha-2 codes.

cities = Cities.cities_in_country('GB')
  #=> { "abberley"=> #<City:0x000001049b9ba0>, "abberton"=> #<City:0x000001049b9b50>, ... }

mcr = cities['manchester']
  #=> #<City:0x00000102fb4ea8>

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".

Cities.cities_in_country('GB')['buchlyvie'].population
  #=> 448

Countries

This gem was designed as an extension to the Countries gem. Installing Cities adds two new instance methods to the Country class.

us = Country.search('US')
  #=> #<Country:0x000001020cf5f0>

us.cities?
  #=> true

us.cities
  #=> { "abanda" => #<Cities::City:0x00000114b34a38>, ...  }

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

Country.cache_data = false

Configuration options available are data_path and cache_data

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. Thanks to hexorx for the countries gem that brought this idea about.

This product includes data created by MaxMind, available from http://www.maxmind.com. All data © 2008 MaxMind Inc. Read the MaxMind WorldCities open data license for more details.