A Ruby client for the OpenCage geocoding API.
gem install opencage-geocoder
Or in your Gemfile:
source 'https://rubygems.org'
gem 'opencage-geocoder'
You can find a comprehensive tutorial for using this module on the OpenCage site.
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')
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
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"}}
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
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, Михайловский проезд ...
OpenCage::Geocoder
. Now OpenCage::Error
is raised.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
Copyright (c) OpenCage GmbH. See LICENSE for details.
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.