OpenCage Geocoder

A Ruby client for the OpenCage geocoding API.

Build status / Code quality / etc

Installation

gem install opencage-geocoder

Or in your Gemfile:

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

Tutorial

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 opencagedata.com/api.

Usage

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

Annotations

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:

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

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

begin

Batch geocoding

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:

geocoder = OpenCage::Geocoder.new(api_key: 'your-api-key-here')

results = []
File.foreach('queries.txt') do |line|
  latitude, longitude = 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(latitude), Float(longitude))
  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

puts results.map(&:address)
# 韓國館, 金山十一街, 金山里, 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

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.