Geocodio is an amazing tool for any Rails developer looking to incorporate location-based data into their project. In this article, I’m going to break down how to integrate the Geocodio API into a website that will allow users to find and review the contact information for their Congressional Representatives.
Let’s get started!
First, we need to create and set-up our project. We can do that by running a simple rails generator in our terminal.
rails new code-sample-congress-search -–api
Note
You’ll want to include the name of your own application in place of code-sample-congress-search.
The --api tag included at the end of the generator will automatically format your application to emphasize the backend. It will cut out some inessential Middleware that pertains to frontend development in Rails and will also set your ApplicationController to inherit from Api instead of Base. If you want to build out frontend views in Rails itself, you may want to consider leaving this tag off.
Once the generator is finished its work, you’ll have a complete skeleton of a Rails API that you can use as your foundation. Go ahead and cd into your new directory.
cd code-sample-congress-search
To work with Geocodio, we’re going to want to add a few important tools to our Gemfile. Open your Gemfile and insert the following:
gem 'geocodio-gem'
gem 'dotenv-rails'
gem 'faraday'
gem 'faraday-follow_redirects'
gem 'nokogiri', '>= 1.13.6'
You will also want to uncomment the already existing code from this block of commented text.
gem 'rack-cors'
Here’s a quick rundown on what these Ruby gems are going to do for us:
To be certain everything has been installed correctly, you may want to run the following in your terminal:
bundle install
Now that we’ve installed Dotenv-Rails, let’s secure our API key for future use. We’ll need it when we’re ready to make a call to the Geocodio API.
Create a file in your root directory (in my case “code-sample-congress-search”) called .env. This is your environment file. Then, within that file, assign your API key from Geocodio - which you can access on your Dashboard - to a variable. That variable should be in ALL CAPS.
API_KEY=<Your API key goes here>
Next comes the most important part: you must add your new .env file to the .gitignore file, which should already be contained within your root directory. This ensures that your .env file does not get pushed to Github, exposing your API key publicly. This is crucial for the security of your application.
You’ll need to access your API_KEY eventually, but we’ll get to that soon.
With that done, we’ll need to consider what resources we want to add to our application. In this particular case, since our functionality is limited to finding information about a Congressional District - and there aren’t any other dynamic relationships - we only need one resource: District. We will use the controller that this resource provides us to retrieve data from the Geocodio API.
rails generate resource District
By running this generator, we’ll construct a few important things:
Note:
Since we’ll only be using this controller to retrieve data from the Geocodio API, I did not include any attributes for our District resource. If you want to store data into an internal database, you will want to include necessary attributes when you generate your own resources.
To avoid any potential errors, let’s go ahead and migrate our database to get it out of our way.
rails db:migrate
Okay, we’ve spent a lot of time generating and configuring, but now it’s finally time to start implementing our code!
Generally, when building out a Rails application, you would want to establish relationships between your models and add CRUD actions to your controllers that would allow you to Create, Read, Update or Delete instances of those models. But for our purposes, this backend application is fairly barebones. All we want is a single action within districts_controller.rb that can be used to call the Geocodio API and retrieve Congressional District data about an input address.
Before we do anything else, we need to make sure that we make our Dotenv-Rails and Geocodio-Gem gems available to our districts_controller by requiring them at the top of the file.
require 'dotenv-rails'
require 'geocodio/gem'
We should already have an empty DistrictsController class to work within. Let’s go ahead and use our Geocodio Ruby library to grab a sample address so that we can test if it’s working. I’ll explain the code once we’re done, but to follow along check out the Single Address section of the Geocodio API docs.
require 'dotenv-rails'
require 'geocodio/gem'
class DistrictsController < ApplicationController
def get_district
geocodio = Geocodio::Gem.new(ENV["API_KEY"])
location = geocodio.geocode(["1600 Pennsylvania Ave. Washington, DC 20500"], ["cd"])
district = location["results"][0]["fields"]["congressional_districts"][0]
render json: district
end
end
Let’s break everything down:
First, I created a method named get_district, which I can call to activate this block of code.
Next, I connected the application to the Geocodio library by creating an instance variable called geocodio and assigning it to Geocodio::Gem.new(ENV["API_KEY"]). Notice that when I create a new instance, I pass in the API_KEY from my .env file. This will make sure that Geocodio recognizes me as a valid user, but without ever exposing the key to the public.
With the library available to me, I run the .geocode() method on my geocodio instance. In square brackets, I pass in a string of an address that I want to look up. Usually you wouldn’t want to hardcode this, but I want to test to make sure everything is working before I abstract it into a variable. I chose the White House as an example address.
I also pass in an additional array containing the string ["cd"] into geocode() - which will append information about the address’ Congressional District onto the data that is returned from Geocodio. There are lots of different fields you can append to your results. Find them here. Any field codes you add to the secondary array will append the associated datasets to your results.
If we were to check what the location variable returns, we would get a response from Geocodio! It will include all of the requested information about the address we’ve provided.
We could stop there, but I’d rather sift through only the essential data that we need. As such, I create one more variable, district, that is assigned to location["results"][0]["fields"]["congressional_districts"][0], which provides us all the data we need about the Congressional District of the address provided - without any extraneous information.
Finally, I render the district variable as JSON, making the data easy to read and display on whatever frontend we choose.
We have one more step to complete before we’ll actually be able to review and access the data we want to retrieve from the Geocodio API. We need to set up a route that will allow us to call the get_district action in our controller.
Navigate to your config directory and open the routes.rb file. This is where we build out our routes. Let’s go ahead and set up a GET route to call get_district.
get '/get_district' => 'districts#get_district'
Note:
You may notice some code that is already in your routes file. When you generated the District resource, a group of routes named resources :districts was automatically built. This includes GET, POST, PATCH and DELETE routes for every District resource. I’ve chosen to delete this code, because we’re not going to need it right now - but you can make your own decision based on the needs of your application.
With our /get_district route wired up, we are all set to make our first test call to the Geocodio API. Let’s make sure everything is working as we would hope!
Go ahead and run a rails server in your terminal.
rails s
Then, in your browser, navigate to the /get_district route. Most likely, if you are using a Rails server, your server port will be 3000, so your URL should look like this:
http://localhost:3000/get_district
If you’ve followed the instructions to this point you should see a response from the Geocodio API that contains all of the requested data. We’ve made our first successful API call!
Now that we’re officially making a successful request to the Geocodio API - and received a response - it’s time to chat a bit about integrating our backend with a frontend.
Ultimately, there are a lot of options here and I can’t cover them all. You could build your frontend within your already existing Rails application by incorporating views. You could also construct an entirely separate project using a language like JavaScript and an asynchronous technique like fetch() to grab the data from our Rails app.
In my case, I chose to use the React Javascript library - but from here on out I’ll try to keep things as all-purpose as possible. Just recognize that you may need to make some adjustments to your integration strategy depending on how you’ve elected to build your frontend.
What we need to do to make our application a bit more useful - because not everyone is going to need to know the Congressional District data for a single, hard-coded address - is to find a way to abstract out our location variable. Regardless of your frontend strategy, we need to accomplish a few things to make this happen:
In my React frontend, I constructed a Search component that renders a search bar and captures the value entered into that form on submit.
When the page re-renders after the submit, I make a fetch() call to the Rails backend. Here’s what that fetch looks like for reference:
const fetchDistrict = () => {
fetch(`http://localhost:3000/get_district?search=${address}`),
method: “GET”,
headers: {
“Content-Type”: “application/json”
}
})
.then(resp => resp.json())
.then(data => {
if (data.error){
console.log(“Something went wrong”)
} else {
setDistrict(data)
}
})
}
Since this isn’t a React tutorial, the main thing to focus on here is the first line of my fetch. When I call the get_district route, I query a search parameter and pass in the address state, which includes the address string submitted in my search bar. By including this in the URL that I’m fetching, I am effectively sending the address string to my backend server as a parameter.
Once I’ve added one small change to my districts_controller, this will return the Congressional District data for any address I enter into the form.
What do I need to add?
require 'dotenv-rails'
require 'geocodio/gem'
class DistrictsController < ApplicationController
def get_districts
addressString = params["search"]
geocodio = Geocodio::Gem.new(ENV["API_KEY"])
location = geocodio.geocode([addressString], ["cd"])
district = location["results"][0]["fields"]["congressional_districts"][0]
render json: district
end
end
Since the fetch creates a parameter called search, which contains our address string - we can return that string through params["search"] in our districts_controller.
I’ve assigned params["search"] to a variable called addressString. When I pass addressString into the square brackets in the .geocode() method, Geocodio will retrieve information for the submitted addresses. The rest of our code will render the requested district information as JSON and send a response back to the frontend for the data to be displayed!
This is awesome. We can enter an address into the search bar on our frontend, retrieve the Congressional District information about that address from the Geocodio API through our backend and then render the retrieved data for the user to consume. This is exactly what we want.
But there’s still one more thing to consider…
If we want to utilize our Rails backend in unison with a separate frontend - in my case React - then the frontend will need permission to receive the incoming data.
Earlier, we uncommented the ‘rack-cors’ gem, but we haven’t actually done anything with it yet. Rack CORS allows us to permit an external source - or origin - to retrieve data from our Rails backend. It’s a security feature that is totally customizable. You decide what origins can access data from your app. If an unknown origin makes a request, they won’t receive a response.
To configure our Rack CORS, navigate into the config/initializers directory and find the file called cors.rb.
Inside the file, uncomment the following code.
Rails.application.config.middleware.insert_before 0, Rack::Cors do
allow do
origins '*'
resource '*',
headers: :any,
methods: [:get, :post, :put, :patch, :delete, :options, :head]
end
end
Notice that origins is currently set to an asterisk(*). This is where we set which domains have permission to access our Rails backend. In this case, the asterisk indicates that any domain that were to attempt to retrieve data would receive a response. That’s okay for now, but if our site went live, it could cause some real security issues.
Since my React server currently runs on localhost:3001, I’m going to pass that into origins so that it is the only domain that can access data from the backend.
origins 'http://localhost:3001'
Now, when my React frontend makes a call to my Rails backend, it will receive the data from the Geocodio API - but no other applications will be able to do the same.
That’s it! We now have a working application that will allow a user to search for their address and retrieve information about their Congressional District from the Geocodio API. This is just one of many ways to integrate Geocodio with a Ruby On Rails application.
For a closer look - or to follow along, check out the sample code for Congress Search - which was built with a Ruby On Rails backend and a React frontend.