This add-on is operated by Expedited Security

Convert mailing addresses into Lat,Long Coordinates

Last updated July 27, 2023

Geocody is an add-on to convert mailing addresses into Lat,Long Coordinates

Convert (geocode) mailing addresses into their respective Latitude and Longitude for use with:

• Custom Online Maps
• Physical Store Finders
• Distance Calculations
• Data Visualizations
• Other GIS functions

Geocody exposes an API and has supported examples for Ruby, PHP, Python, Node and Java.

Provisioning the add-on

Geocody can be attached to a Heroku application via the CLI:

$ heroku addons:create geocody
-----> Adding geocody to sharp-mountain-4005... done, v18 (free)

Once Geocody has been added a GEOCODY_API_KEY config variable will contain your specific api key granting access to the newly provisioned Geocody instance. This can be confirmed using the heroku config:get command.

$ heroku config:get GEOCODY_API_KEY
Bl4XHVbdsf5GIXQbqTfXR5IrpuuXER2kaVc2zNnA

After installing Geocody your application should be modified to fully integrate with the add-on.

Local setup

Environment setup

After provisioning the add-on it’s necessary to locally replicate the config vars so your development environment can operate against the service.

Use the Heroku Local command-line tool to configure, run and manage process types specified in your app’s Procfile. Heroku Local reads configuration variables from a .env file. To view all of your app’s config vars, type heroku config. Use the following command for each value that you want to add to your .env file.

$ heroku config:get GEOCODY_API_KEY -s  >> .env

For more information, see the Heroku Local article.

Input Parameter Descriptions

All languages will follow this call structure for inputs.

Using with Ruby

Install the Geocody gem.

# In your Gemfile
gem 'geocody', git: 'https://github.com/mbuckbee/Geocody-Gem.git'

Making a Request

$ > require 'geocody'
=> true

# Note: the 'Controller' here is not a reference to Rails controllers
# but an internal structure, won't interfere with your Rails app and will
# work fine in a standalone ruby app or another framework

$ > gc = Geocody::APIController.new


$ > result = gc.lookup("1432 Greenbrier Pkwy, Chesapeake, VA 23320", "US", "EN")

Using Results

$ > result.found
=> 1

$ > result.locations[0].country
=> "United States of America"

$ > result.locations[0].country_code
=> "us"

$ > result.locations[0].address
=> "Pop's Diner, 1432, Greenbrier Parkway, Chesapeake, Chesapeake City, Virginia, 23320, United States of America"

$ > result.locations[0].city
=> "Chesapeake City"

$ > result.locations[0].postal_code
=> "23320"

$ > result.locations[0].latitude
=> 36.77782295

$ > result.locations[0].longitude
=> -76.2315181468951

Using with PHP

<?php

$ch = curl_init('https://geocody.expeditedaddons.com/?address=1432+Greenbrier+Pkwy%2C+Chesapeake%2C+VA+23320&api_key=' . getenv('GEOCODY_API_KEY') . '&country_code=US&language_code=en');

$response = curl_exec($ch);
curl_close($ch);

var_dump($response);

Using with Python

import os
from urllib2 import Request, urlopen

request = Request('https://geocody.expeditedaddons.com/?address=1432+Greenbrier+Pkwy%2C+Chesapeake%2C+VA+23320&api_key=' + os.environ['GEOCODY_API_KEY'] + '&country_code=US&language_code=en')

response_body = urlopen(request).read()
print response_body

Using with Node

var request = require('request');

request('https://geocody.expeditedaddons.com/?address=1432+Greenbrier+Pkwy%2C+Chesapeake%2C+VA+23320&api_key=' + process.env.GEOCODY_API_KEY + '&country_code=US&language_code=en', function (error, response, body) {
  console.log('Status:', response.statusCode);
  console.log('Headers:', JSON.stringify(response.headers));
  console.log('Response:', body);
});

Using with Java

// Maven : Add these dependecies to your pom.xml (java6+)
// <dependency>
//     <groupId>org.glassfish.jersey.core</groupId>
//     <artifactId>jersey-client</artifactId>
//     <version>2.8</version>
// </dependency>
// <dependency>
//     <groupId>org.glassfish.jersey.media</groupId>
//     <artifactId>jersey-media-json-jackson</artifactId>
//     <version>2.8</version>
// </dependency>

import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.MediaType;

Client client = ClientBuilder.newClient();
Response response = client.target('https://geocody.expeditedaddons.com/?address=1432+Greenbrier+Pkwy%2C+Chesapeake%2C+VA+23320&api_key=' + System.getenv('GEOCODY_API_KEY') + '&country_code=US&language_code=en}')
  .request(MediaType.TEXT_PLAIN_TYPE)
  .get();

System.out.println("status: " + response.getStatus());
System.out.println("headers: " + response.getHeaders());
System.out.println("body:" + response.readEntity(String.class));

Result Field Descriptions

Dashboard

The Geocody dashboard allows you to monitor your API usage limits.

The dashboard can be accessed via the CLI:

$ heroku addons:open geocody
Opening geocody for sharp-mountain-4005

or by visiting the Heroku Dashboard and selecting the application in question. Select Geocody from the Add-ons menu.

Troubleshooting

As a sanity check it is sometimes useful to bypass your app stack and check the endpoint, your API Key and parameters directly.

Test with your browser

# Modify the following to use your actual API Key
https://geocody.expeditedaddons.com/?address=1432+Greenbrier+Pkwy%2C+Chesapeake%2C+VA+23320&api_key=REPLACE_WITH_YOUR_GEOCODY_API_KEY&country_code=US&language_code=en

A successful call will return your requested data with a HTTP result code of 200 along with your data. We recommend the JSON Formatter extension as a useful tool.

Your api key can be found on your Geocody dashboard.

Migrating between plans

Use the heroku addons:upgrade command to migrate to a new plan.

$ heroku addons:upgrade geocody:newplan
-----> Upgrading geocody:newplan to sharp-mountain-4005... done, v18 ($49/mo)
       Your plan has been updated to: geocody:newplan

Removing the add-on

Geocody can be removed via the CLI.

$ heroku addons:destroy geocody
-----> Removing geocody from sharp-mountain-4005... done, v20 (free)

Support

All Geocody support and runtime issues should be submitted via one of the Heroku Support channels. Any non-support related issues or product feedback is welcome at support@expeditedaddons.com