Ruby Geocoding 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:

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

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"
# }

Install the Ruby gem

gem install geocoder

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

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}"
Start your free trial

2,500 API requests per day.

No credit card required.