Gnlookup integrates free geolocation data from geonames.org to your Ruby on Rails application.
Take the following steps to configure your Rails application to use Gnlookup.
Add this line to your Gemfile:
gem 'gnlookup', :git => 'https://github.com/lw292/gnlookup.git'
At this point, if you are running Rails 4.x, you will need this line too in the Gemfile:
gem 'protected_attributes'
Then run the bundle command to install:
bundle install
Now create or modify the database structure:
rake gnlookup:install:migrations rake db:migrate
This will add three tables to the database:
gnlookup_cities gnlookup_regions gnlookup_countries
If for some reason you already have tables in your database by the same names, you should resolve the namespace conflicts before running the database migration commands.
Geolocation data for countries, regions and cities can be downloaded for free from the geonames gazetteer data download page. For Gnlookup to work, you will need at least three files:
countryInfo.txt cities5000.zip # Or cities1000.zip or cities15000.zip. More information below. admin1CodesASCII.txt
You will also need to download free US zipcode data from the geonames postal code data download page. You will need this file:
US.zip
Download (unzip if necessary) and copy the data files (.txt files) to your Rails application’s db/geonames directory (create that directory if necessary). You should end up having these files:
db/geonames/countryInfo.txt db/geonames/cities5000.txt # Or cities1000.txt or cities15000.txt. More information below. db/geonames/admin1CodesASCII.txt db/geonames/US.txt
Once you’ve saved the data to your application, you can import the data to your database with this rake task:
rake gnlookup:import
Because it takes a long time to import cities data, by default the system chooses the cities5000.txt file, which includes information about cities with a population larger than 5000.
Alternatively, you can also choose to import the cities1000.txt or the cities15000.txt files instead of the cities5000.txt file:
rake gnlookup:import CITIES=cities1000 rake gnlookup:import CITIES=cities15000
The former file will take significantly longer to import. It may also affect the database’s performance, and the query results may also be harder to disambiguate. The latter will take much less time to import, but it only contains information about cities with a population larger than 15000.
Here are some examples of how to query the database in your code:
query = "new haven" cities = Gnlookup::City.where("name =?", query.split.map(&:capitalize).join(' ')) # => [#<Gnlookup::City id: 42035, geoname_id: 4839366, region_id: 3611, name: "New Haven", name_ascii: "New Haven", lat: "41.30815", lng: "-72.92816", created_at: "2014-02-07 19:47:12", updated_at: "2014-02-07 19:47:12">, #<Gnlookup::City id: 42499, geoname_id: 4924104, region_id: 3614, name: "New Haven", name_ascii: "New Haven", lat: "41.0706", lng: "-85.01441", created_at: "2014-02-07 19:47:19", updated_at: "2014-02-07 19:47:19">, #<Gnlookup::City id: 42888, geoname_id: 5003384, region_id: 3616, name: "New Haven", name_ascii: "New Haven", lat: "43.09364", lng: "-84.15331", created_at: "2014-02-07 19:47:24", updated_at: "2014-02-07 19:47:24">] cities[0].name # => "New Haven" cities[0].region.name # => "Connecticut" cities[0].country.name # => "United States" cities[0].lat # => "41.30815" cities[0].lng # => "-72.92816"
Sometimes the Census-Designated Place (CDP) names or the administrative level for some towns and cities may be different from what people commonly know. For example, “Amherst, Massachusetts” itself cannot be found as city in the geonames data, but the following places exist:
Amherst Center, Massachusetts North Amherst, Massachusetts South Amherst, Massachusetts
This will cause problems if your code tries to map these place names to cities. Your code either should be flexible enough to accomodate these issues, or you may want to manually add “dummy” records for such cities to your database.
This project rocks and uses MIT-LICENSE. Gnlookup was inspired by and partly adapted from the work of Resistor Software.