OpenCage Geocoder Ruby Tutorial

Before we dive in to the tutorial ...

This is a tutorial for using the OpenCage Geocoding API in Ruby. Before you can query the API you will need to sign up for an OpenCage API key.

Once you've done that we recommend you spend five minutes on:

playing with the demo page, so that you see the actual response the API returns.
browsing the API documentation, so you understand the various optional parameters, possible response codes, and the rate limiting on free trial accounts

Ok, ready?

Ruby gems for accessing the OpenCage Geocoding API

There are three Ruby gems you can use:

Install the Ruby gem

gem install opencage-geocoder

opencage-geocoder on github

Or in your Gemfile:

source 'https://rubygems.org'
gem 'opencage-geocoder'

Convert latitude, longitude to an address

require 'opencage/geocoder'

geocoder = OpenCage::Geocoder.new(api_key: 'YOUR-API-KEY')

result = geocoder.reverse_geocode(51.5019951, -0.0698806)
p result.address
# output is 'Reeds Wharf, 33 Mill Street, London SE15, United Kingdom'

Geocode an address or place name

results = geocoder.geocode('82 Clerkenwell Road, London')
p results.first.coordinates
# [ 51.5221558691, -0.100838524406 ]

results = geocoder.geocode('Manchester')
results.each { |res| p res.address }
# "Manchester, Greater Manchester, England, United Kingdom"
# "Manchester, NH, United States of America"
# "Manchester, Jamaica"
# "Manchester, CT 06042, United States of America"
# ...

# We want the city in Canada and results in Japanease
results = geocoder.geocode('Manchester', country_code: 'CA', language: 'ja')
p results.first.address
# "Manchester, ノバスコシア州, カナダ"
p results.first.components
# {
#   "_type" => "city",
#   "city" => "Manchester",
#   "county" => "Guysborough County",
#   "state" => "ノバスコシア州",
#   "state_code" => "NS",
#   "country" => "カナダ",
#   "country_code" => "ca",
#   "ISO_3166-1_alpha-2" => "CA",
#   "ISO_3166-1_alpha-3" => "CAN"
# }

Bulk-geocode places

Fill a text file queries.txt with queries:

24.77701,121.02189
31.79261,35.21785
9.54828,44.07715
59.92903,30.32989

Then loop through the file:

results = []
File.foreach('queries.txt') do |line|
  lat, lng = line.chomp.split(',')

  # Use Float() rather than #to_f because it will throw an ArgumentError if
  # there is an invalid line in the queries.txt file
  result = geocoder.reverse_geocode(Float(lat), Float(lng))
  results.push(result)
rescue ArgumentError, OpenCage::Geocoder::GeocodingError => error
  # Stop looping through the queries if there is an error
  puts 'Error: ' + error.message
  break
end

results.each do |r|
  p r.address)
end
# 韓國館, 金山十一街, 金山里, Hsinchu 30082, Taiwan
# David Hazan 11, NO Jerusalem, Israel
# هرجيسا, Jameeco Weyn, Hargeisa, Somalia
# Китайское бистро, Apraksin Yard, Михайловский проезд ...

Install the Ruby gem

gem install geocoder

geocoder on github rubygeocoder.com

Or in your Gemfile:

source 'https://rubygems.org'
gem 'geocoder'

Geocode an address

#!/usr/bin/env ruby

require 'geocoder'

Geocoder.configure(lookup: :opencagedata, api_key: "YOUR-API-KEY")

results = Geocoder.search("57 Erb Street West Waterloo, ON, Canada N2L 6C2")

result = results.first

puts "#{result.latitude}, #{result.longitude}"   
# output is 43.463796, -80.52608

Geocode coordinates

#!/usr/bin/env ruby

require 'geocoder'

Geocoder.configure(lookup: :opencagedata, api_key: "YOUR-API-KEY")

results = Geocoder.search([43.463796, -80.52608], reverse_geocode: true)

result = results.first

puts result.address
# output is "63 Erb Street West, Waterloo, ON N2L 1V4, Canada"

Install the Ruby gem

gem install geokit

geokit on github

Or in your Gemfile:

source 'https://rubygems.org'
gem 'geokit'

Geocode coordinates

require 'geokit'

Geokit::Geocoders::OpencageGeocoder.key = 'YOUR-API-KEY'

Geokit::Geocoders::provider_order = [:opencage]

result = Geokit::Geocoders::MultiGeocoder.geocode("51.2157153, 1.3903743")

puts "#{result.provider}: #{result.full_address}"
# Output is "opencage: Mill Road, South East, Kent, England, CT14 9BD, GB"

Geocode an address

#!/usr/bin/env ruby

require 'geokit'

Geokit::Geocoders::OpencageGeocoder.key = 'YOUR-API-KEY'

Geokit::Geocoders::provider_order = [:opencage]

result = Geokit::Geocoders::MultiGeocoder.geocode("900 Sycamore Drive")

puts "#{result.provider}: #{result.latitude}, #{result.longitude}"