A ruby client for the OpenCage Data geocoding API. Supports forward and reverse geocoding for the entire world using open datasources like OpenStreetMap.

Monthly Downloads: 4,048
Programming language: Ruby
License: MIT License
Latest version: v2.1.2

OpenCage Geocoder alternatives and similar gems

Based on the "Geolocation" category.
Alternatively, view OpenCage Geocoder alternatives based on common mentions on social networks and blogs.

Do you think we are missing an alternative of OpenCage Geocoder or a related project?

Add another 'Geolocation' Gem


OpenCage Geocoder

A Ruby client for the OpenCage geocoding API.

Build status / Code quality / etc

Build Status Kritika Analysis Status Gem Version


gem install opencage-geocoder

Or in your Gemfile:

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


Complete documentation for the OpenCage geocoding API can be found at opencagedata.com/api.


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

require 'opencage/geocoder'

geocoder = OpenCage::Geocoder.new(api_key: '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"
# }

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::Geocoder::GeocodingError if there is a problem with either input or response, for example:

# Invalid API key
geocoder =  OpenCage::Geocoder.new(api_key: 'invalid-api-key')
# OpenCage::Geocoder::GeocodingError (invalid API key)

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

Batch geocoding

Fill a text file queries.txt with queries:


Then loop through the file:

geocoder = OpenCage::Geocoder.new(api_key: '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}"

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

Upgrading from version 0.1x

  • 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 the OpenCage Geocoder. 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.

*Note that all licence references and agreements mentioned in the OpenCage Geocoder README section above are relevant to that project's source code only.