Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

OpenCage Geocoder

A Ruby client for the OpenCage geocoding API.

Build status / Code quality / etc

Build Status Gem Version Mastodon Follow


gem install opencage-geocoder

Or in your Gemfile:

source ''
gem 'opencage-geocoder'


You can find a comprehensive tutorial for using this module on the OpenCage site.

API Documentation

Complete documentation for the OpenCage geocoding API can be found at


Create an instance of the geocoder, passing a valid OpenCage Geocoder API key:

require 'opencage/geocoder'

geocoder = 'your-api-key-here')

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 Japanese
results = geocoder.geocode('Manchester', countrycode: '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"
# }
p results.first.geometry # might be empty for some results 
p results.first.bounds # might be empty for some results 

Convert latitude, longitude to an address

result = geocoder.reverse_geocode(51.5019951, -0.0698806)
p result.address
# 'Bermondsey Wall West, Bermondsey, London Boro ...


See the API documentation for a complete list of annotations.

result = geocoder.reverse_geocode(-22.6792, 14.5272)
p result.annotations['geohash']
# "k7fqfx6h5jbq5tn8tnpn"
p result.annotations['timezone']
# {"timezone"=>{"name"=>"Africa/Windhoek", "now_in_dst"=>0, "offset_sec"=>7200, "offset_string"=>200, "short_name"=>"CAT"}}

Error handling

The geocoder will return an OpenCage::Error subclass if there is a problem with either input or response, for example:

  # Invalid API key
  geocoder = 'invalid-api-key')
rescue OpenCage::Geocoder::AuthenticationError => e
  p 'invalid apikey'
rescue OpenCage::Geocoder::QuotaExceeded => e
  p 'over quota'
rescue StandardError => e
  p 'other error: ' + e.message

# Using strings instead of numbers for reverse geocoding
geocoder.reverse_geocode('51.5019951', '-0.0698806')
# raises OpenCage::Geocoder::InvalidRequest (not valid numeric coordinates: "51.5019951", "-0.0698806")


Batch geocoding

Fill a text file queries.txt with queries:


Then loop through the file:

geocoder = 'your-api-key-here')

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))
rescue ArgumentError, OpenCage::Geocoder::GeocodingError => error
  # Stop looping through the queries if there is an error
  puts "Error: #{error.message}"

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

Upgrading to version 3.0

  • Version 2.x raised OpenCage::Geocoder. Now OpenCage::Error is raised.

Upgrading to version 2.0

  • Version 0.1x only returned one result
geocoder.geocode('Berlin').coordinates # Version 0.12
geocoder.geocode('Berlin').first.coordinates # Version 2

geocoder.reverse_geocode(50, 7).name # Version 0.12
geocoder.reverse_geocode(50, 7).address # Version 2
  • Version 0.1x raised an error when no result was found. Version 2 returns an empty list (forward) or nil (reverse).


Copyright (c) OpenCage GmbH. See LICENSE for details.

Who is OpenCage GmbH?

We run a worldwide geocoding API and geosearch service based on open data. Learn more about us.

We also run Geomob, a series of regular meetups for location based service creators, where we do our best to highlight geoinnovation. If you like geo stuff, you will probably enjoy the Geomob podcast.