The Geocodio API is a great tool for integrating location-based data into your Ruby or Rails application. To help ease the work of developers, we’ve built a Ruby Library that includes a number of different methods that call the API and allow you to retrieve the information you require.
In this article, we’re going to go over how to implement and install our Ruby Library. Then, we’ll use it to reverse geocode a single pair of coordinates.
Start by navigating to your Gemfile. Once there, add the following gems:
gem 'geocodio-gem'
gem 'faraday'
gem 'faraday-follow_redirects'
The only requirement is geocodio-gem, but to prevent potential errors, you may also want to include faraday and faraday-follow_redirects if you haven’t already installed them. They work with the Geocodio Gem to make calls to the API.
Then, to ensure everything is loaded, run bundle install in your terminal.
At the top of the file where you’d like to work, add require ‘geocodio/gem’.
With the gem required, initialize a Geocodio::Gem class by passing in your API Key. If you still need to generate an API Key, you can do so by logging into your account and navigating to the API Keys tab in your account dashboard.
Note: You may want to consider securing your API Key in a .env file using a gem like dotenv or dotenv-rails.
geocodio = Geocodio::Gem.new(“YOUR API KEY”)
You now have access to a number of methods available through the Library, including .reverse(), .geocode(), .createList(), etc. You can call these methods on your newly created geocodio variable.
To reverse geocode an address, use the .reverse() method and pass in a string that contains that latitude and longitude coordinates. The pair should be separated by a comma. Be sure to wrap the string in square brackets ([ ]).
We’ll respond with a JSON object that contains the address most closely associated with those coordinates, as well as some additional information such as Accuracy Type and Score.
If you receive multiple results, the first result will usually be the most accurate to your input.
results = geocodio.reverse(["38.9002898,-76.9990361"])
results # => {"results"=>[{"address_components"=>{"number"=>"508", "street"=>"H", "suffix"=>"St", "postdirectional"=>"NE", "formatted_street"=>"H St NE", "city"=>"Washington", "county"=>"District of Columbia", "state"=>"DC", "zip"=>"20002", "country"=>"US"}, "formatted_address"=>"508 H St NE, Washington, DC 20002", "location"=>{"lat"=>38.900432, "lng"=>-76.999031}, "accuracy"=>1, "accuracy_type"=>"rooftop", "source"=>"Statewide DC"}, {"address_components"=>{"number"=>"510", "street"=>"H", "suffix"=>"St", "postdirectional"=>"NE", "formatted_street"=>"H St NE", "city"=>"Washington", "county"=>"District of Columbia", "state"=>"DC", "zip"=>"20002", "country"=>"US"}, "formatted_address"=>"510 H St NE, Washington, DC 20002", "location"=>{"lat"=>38.900429, "lng"=>-76.998965}, "accuracy"=>1, "accuracy_type"=>"rooftop", "source"=>"Statewide DC"}, {"address_components"=>{"number"=>"506", "street"=>"H", "suffix"=>"St", "postdirectional"=>"NE", "formatted_street"=>"H St NE", "city"=>"Washington", "county"=>"District of Columbia", "state"=>"DC", "zip"=>"20002", "country"=>"US"}, "formatted_address"=>"506 H St NE, Washington, DC 20002", "location"=>{"lat"=>38.900437, "lng"=>-76.999099}, "accuracy"=>1, "accuracy_type"=>"rooftop", "source"=>"Statewide DC"}, {"address_components"=>{"number"=>"504", "street"=>"H", "suffix"=>"St", "postdirectional"=>"NE", "formatted_street"=>"H St NE", "city"=>"Washington", "county"=>"District of Columbia", "state"=>"DC", "zip"=>"20002", "country"=>"US"}, "formatted_address"=>"504 H St NE, Washington, DC 20002", "location"=>{"lat"=>38.900422, "lng"=>-76.999169}, "accuracy"=>1, "accuracy_type"=>"rooftop", "source"=>"Statewide DC"}, {"address_components"=>{"number"=>"512", "street"=>"H", "suffix"=>"St", "postdirectional"=>"NE", "formatted_street"=>"H St NE", "city"=>"Washington", "county"=>"District of Columbia", "state"=>"DC", "zip"=>"20002", "country"=>"US"}, "formatted_address"=>"512 H St NE, Washington, DC 20002", "location"=>{"lat"=>38.900435, "lng"=>-76.998897}, "accuracy"=>1, "accuracy_type"=>"rooftop", "source"=>"Statewide DC"}, {"address_components"=>{"number"=>"500", "street"=>"H", "suffix"=>"St", "postdirectional"=>"NE", "formatted_street"=>"H St NE", "city"=>"Washington", "county"=>"District of Columbia", "state"=>"DC", "zip"=>"20002", "country"=>"US"}, "formatted_address"=>"500 H St NE, Washington, DC 20002", "location"=>{"lat"=>38.900203, "lng"=>-76.999507}, "accuracy"=>0.46, "accuracy_type"=>"nearest_street", "source"=>"TIGER/Line® dataset from the US Census Bureau"}, {"address_components"=>{"number"=>"800", "street"=>"5th", "suffix"=>"St", "postdirectional"=>"NE", "formatted_street"=>"5th St NE", "city"=>"Washington", "county"=>"District of Columbia", "state"=>"DC", "zip"=>"20002", "country"=>"US"}, "formatted_address"=>"800 5th St NE, Washington, DC 20002", "location"=>{"lat"=>38.900203, "lng"=>-76.999507}, "accuracy"=>0.46, "accuracy_type"=>"nearest_street", "source"=>"TIGER/Line® dataset from the US Census Bureau"}, {"address_components"=>{"number"=>"817", "street"=>"6th", "suffix"=>"St", "postdirectional"=>"NE", "formatted_street"=>"6th St NE", "city"=>"Washington", "county"=>"District of Columbia", "state"=>"DC", "zip"=>"20002", "country"=>"US"}, "formatted_address"=>"817 6th St NE, Washington, DC 20002", "location"=>{"lat"=>38.900203, "lng"=>-76.998442}, "accuracy"=>0.45, "accuracy_type"=>"nearest_street", "source"=>"TIGER/Line® dataset from the US Census Bureau"}, {"address_components"=>{"number"=>"774", "street"=>"6th", "suffix"=>"St", "postdirectional"=>"NE", "formatted_street"=>"6th St NE", "city"=>"Washington", "county"=>"District of Columbia", "state"=>"DC", "zip"=>"20002", "country"=>"US"}, "formatted_address"=>"774 6th St NE, Washington, DC 20002", "location"=>{"lat"=>38.900078, "lng"=>-76.998443}, "accuracy"=>0.45, "accuracy_type"=>"nearest_street", "source"=>"TIGER/Line® dataset from the US Census Bureau"}, {"address_components"=>{"number"=>"474", "street"=>"H", "suffix"=>"St", "postdirectional"=>"NE", "formatted_street"=>"H St NE", "city"=>"Washington", "county"=>"District of Columbia", "state"=>"DC", "zip"=>"20002", "country"=>"US"}, "formatted_address"=>"474 H St NE, Washington, DC 20002", "location"=>{"lat"=>38.900205, "lng"=>-76.99994}, "accuracy"=>0.44, "accuracy_type"=>"nearest_street", "source"=>"TIGER/Line® dataset from the US Census Bureau"}, {"address_components"=>{"number"=>"540", "street"=>"I", "suffix"=>"St", "postdirectional"=>"NE", "formatted_street"=>"I St NE", "city"=>"Washington", "county"=>"District of Columbia", "state"=>"DC", "zip"=>"20002", "country"=>"US"}, "formatted_address"=>"540 I St NE, Washington, DC 20002", "location"=>{"lat"=>38.901323, "lng"=>-76.998836}, "accuracy"=>0.43, "accuracy_type"=>"nearest_street", "source"=>"TIGER/Line® dataset from the US Census Bureau"}, {"address_components"=>{"number"=>"900", "street"=>"5th", "suffix"=>"St", "postdirectional"=>"NE", "formatted_street"=>"5th St NE", "city"=>"Washington", "county"=>"District of Columbia", "state"=>"DC", "zip"=>"20002", "country"=>"US"}, "formatted_address"=>"900 5th St NE, Washington, DC 20002", "location"=>{"lat"=>38.901323, "lng"=>-76.999509}, "accuracy"=>0.43, "accuracy_type"=>"nearest_street", "source"=>"TIGER/Line® dataset from the US Census Bureau"}, {"address_components"=>{"number"=>"900", "street"=>"6th", "suffix"=>"St", "postdirectional"=>"NE", "formatted_street"=>"6th St NE", "city"=>"Washington", "county"=>"District of Columbia", "state"=>"DC", "zip"=>"20002", "country"=>"US"}, "formatted_address"=>"900 6th St NE, Washington, DC 20002", "location"=>{"lat"=>38.901323, "lng"=>-76.998446}, "accuracy"=>0.43, "accuracy_type"=>"nearest_street", "source"=>"TIGER/Line® dataset from the US Census Bureau"}]}
That’s all there is to it! You’ve made a basic call on a pair of coordinates.