{"id":27019305,"url":"https://github.com/opencagedata/ruby-opencage-geocoder","last_synced_at":"2025-04-04T17:27:11.601Z","repository":{"id":17778885,"uuid":"20648703","full_name":"OpenCageData/ruby-opencage-geocoder","owner":"OpenCageData","description":"Ruby client for the OpenCage geocoding API","archived":false,"fork":false,"pushed_at":"2025-04-02T14:32:06.000Z","size":150,"stargazers_count":14,"open_issues_count":0,"forks_count":11,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-02T14:52:24.610Z","etag":null,"topics":["geocoding","opencage","opencage-geocoder","ruby"],"latest_commit_sha":null,"homepage":"https://opencagedata.com/tutorials/geocode-in-ruby","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OpenCageData.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.txt","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-06-09T14:06:41.000Z","updated_at":"2025-04-02T14:32:00.000Z","dependencies_parsed_at":"2024-05-16T22:33:10.166Z","dependency_job_id":"2b836855-7410-455c-bc46-d14b29e84a23","html_url":"https://github.com/OpenCageData/ruby-opencage-geocoder","commit_stats":{"total_commits":90,"total_committers":12,"mean_commits":7.5,"dds":0.6555555555555556,"last_synced_commit":"2a4b8dcd7158029dbbc6567cea5e377a1e0e8b01"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenCageData%2Fruby-opencage-geocoder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenCageData%2Fruby-opencage-geocoder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenCageData%2Fruby-opencage-geocoder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenCageData%2Fruby-opencage-geocoder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OpenCageData","download_url":"https://codeload.github.com/OpenCageData/ruby-opencage-geocoder/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247219592,"owners_count":20903476,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["geocoding","opencage","opencage-geocoder","ruby"],"created_at":"2025-04-04T17:27:10.798Z","updated_at":"2025-04-04T17:27:11.590Z","avatar_url":"https://github.com/OpenCageData.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenCage Geocoder\n\nA Ruby client for the [OpenCage geocoding API](https://opencagedata.com/api).\n\n## Build status / Code quality / etc\n\n[![Build Status](https://github.com/OpenCageData/ruby-opencage-geocoder/actions/workflows/build.yml/badge.svg?branch=master)](https://github.com/OpenCageData/ruby-opencage-geocoder/actions/workflows/build.yml)\n[![Gem Version](https://badge.fury.io/rb/opencage-geocoder.svg)](https://badge.fury.io/rb/opencage-geocoder)\n![Mastodon Follow](https://img.shields.io/mastodon/follow/109287663468501769?domain=https%3A%2F%2Fen.osm.town%2F\u0026style=social)\n\n## Installation\n\n```\ngem install opencage-geocoder\n```\n\nOr in your Gemfile:\n\n```ruby\nsource 'https://rubygems.org'\ngem 'opencage-geocoder'\n```\n\n## Tutorial\n\nYou can find a comprehensive [tutorial for using this module on the OpenCage site](https://opencagedata.com/tutorials/geocode-in-ruby).\n\n## API Documentation\n\nComplete documentation for the OpenCage geocoding API can be found at\n[opencagedata.com/api](https://opencagedata.com/api).\n\n## Usage\n\nCreate an instance of the geocoder, passing a valid OpenCage Geocoder API key:\n\n```ruby\nrequire 'opencage/geocoder'\n\ngeocoder = OpenCage::Geocoder.new(api_key: 'your-api-key-here')\n```\n\n### Geocode an address or place name\n\n```ruby\nresults = geocoder.geocode('82 Clerkenwell Road, London')\np results.first.coordinates\n# [ 51.5221558691, -0.100838524406 ]\n\nresults = geocoder.geocode('Manchester')\nresults.each { |res| p res.address }\n# \"Manchester, Greater Manchester, England, United Kingdom\"\n# \"Manchester, NH, United States of America\"\n# \"Manchester, Jamaica\"\n# \"Manchester, CT 06042, United States of America\"\n# ...\n\n# We want the city in Canada and results in Japanese\nresults = geocoder.geocode('Manchester', countrycode: 'CA', language: 'ja')\np results.first.address\n# \"Manchester, ノバスコシア州, カナダ\"\np results.first.components\n# {\n#   \"_type\" =\u003e \"city\",\n#   \"city\" =\u003e \"Manchester\",\n#   \"county\" =\u003e \"Guysborough County\",\n#   \"state\" =\u003e \"ノバスコシア州\",\n#   \"state_code\" =\u003e \"NS\",\n#   \"country\" =\u003e \"カナダ\",\n#   \"country_code\" =\u003e \"ca\",\n#   \"ISO_3166-1_alpha-2\" =\u003e \"CA\",\n#   \"ISO_3166-1_alpha-3\" =\u003e \"CAN\"\n# }\np results.first.geometry # might be empty for some results\np results.first.bounds # might be empty for some results\n```\n\n### Convert latitude, longitude to an address\n\n```ruby\nresult = geocoder.reverse_geocode(51.5019951, -0.0698806)\np result.address\n# 'Bermondsey Wall West, Bermondsey, London Boro ...\n\n```\n\n### Annotations\n\nSee the [API documentation](https://opencagedata.com/api#annotations) for a\ncomplete list of annotations.\n\n```ruby\nresult = geocoder.reverse_geocode(-22.6792, 14.5272)\np result.annotations['geohash']\n# \"k7fqfx6h5jbq5tn8tnpn\"\np result.annotations['timezone']\n# {\"timezone\"=\u003e{\"name\"=\u003e\"Africa/Windhoek\", \"now_in_dst\"=\u003e0, \"offset_sec\"=\u003e7200, \"offset_string\"=\u003e200, \"short_name\"=\u003e\"CAT\"}}\n```\n\n### Error handling\n\nThe geocoder will return an `OpenCage::Error` subclass if there is a\nproblem with either input or response, for example:\n\n```ruby\nbegin\n  # Invalid API key\n  geocoder =  OpenCage::Geocoder.new(api_key: 'invalid-api-key')\n  geocoder.geocode('Manchester')\nrescue OpenCage::Error::AuthenticationError =\u003e e\n  p 'invalid apikey'\nrescue OpenCage::Error::QuotaExceeded =\u003e e\n  p 'over quota'\nrescue StandardError =\u003e e\n  p 'other error: ' + e.message\nend\n\n# Using strings instead of numbers for reverse geocoding\ngeocoder.reverse_geocode('51.5019951', '-0.0698806')\n# raises OpenCage::Error::InvalidRequest (not valid numeric coordinates: \"51.5019951\", \"-0.0698806\")\n\nbegin\n\n```\n\n### Batch geocoding\n\nFill a text file `queries.txt` with queries:\n\n```\n24.77701,121.02189\n31.79261,35.21785\n9.54828,44.07715\n59.92903,30.32989\n```\n\nThen loop through the file:\n\n```ruby\ngeocoder = OpenCage::Geocoder.new(api_key: 'your-api-key-here')\n\nresults = []\nFile.foreach('queries.txt') do |line|\n  latitude, longitude = line.chomp.split(',')\n\n  # Use Float() rather than #to_f because it will throw an ArgumentError if\n  # there is an invalid line in the queries.txt file\n  result = geocoder.reverse_geocode(Float(latitude), Float(longitude))\n  results.push(result)\nrescue ArgumentError, OpenCage::Error::GeocodingError =\u003e error\n  # Stop looping through the queries if there is an error\n  puts \"Error: #{error.message}\"\n  break\nend\n\nputs results.map(\u0026:address)\n# 韓國館, 金山十一街, 金山里, Hsinchu 30082, Taiwan\n# David Hazan 11, NO Jerusalem, Israel\n# هرجيسا, Jameeco Weyn, Hargeisa, Somalia\n# Китайское бистро, Apraksin Yard, Михайловский проезд ...\n```\n\n## Upgrading to version 3.0\n\n- Version 2.x raised `OpenCage::Geocoder`. Now `OpenCage::Error` is raised.\n\n## Upgrading to version 2.0\n\n- Version 0.1x only returned one result\n\n```\ngeocoder.geocode('Berlin').coordinates # Version 0.12\ngeocoder.geocode('Berlin').first.coordinates # Version 2\n\ngeocoder.reverse_geocode(50, 7).name # Version 0.12\ngeocoder.reverse_geocode(50, 7).address # Version 2\n```\n\n- Version 0.1x raised an error when no result was found. Version 2 returns an empty list (forward) or nil (reverse).\n\n## Copyright\n\nCopyright (c) OpenCage GmbH. See LICENSE for details.\n\n## Who is OpenCage GmbH?\n\n\u003ca href=\"https://opencagedata.com\"\u003e\u003cimg src=\"opencage_logo_300_150.png\"\u003e\u003c/a\u003e\n\nWe run a worldwide [geocoding API](https://opencagedata.com/api) and [geosearch](https://opencagedata.com/geosearch) service based on open data.\nLearn more [about us](https://opencagedata.com/about).\n\nWe also run [Geomob](https://thegeomob.com), 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](https://thegeomob.com/podcast/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopencagedata%2Fruby-opencage-geocoder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopencagedata%2Fruby-opencage-geocoder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopencagedata%2Fruby-opencage-geocoder/lists"}