This add-on is operated by Expedited Security
Convert mailing addresses into Lat,Long Coordinates
Geocody
Last updated July 27, 2023
This article is a work in progress, or documents a feature that is not yet released to all users. This article is unlisted. Only those with the link can access it.
The Geocody add-on is currently in beta.
Table of Contents
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:
A list of all plans available can be found here.
$ 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
Credentials and other sensitive configuration values should not be committed to source-control. In Git exclude the .env
file with: echo .env >> .gitignore
.
For more information, see the Heroku Local article.
Input Parameter Descriptions
All languages will follow this call structure for inputs.
Index | Name | Example | Description |
---|---|---|---|
0 | address |
string | The address or partial address to try and locate |
1 | country_code |
string | The ISO 2-letter country code to be biased towards (default is no country bias) |
2 | language_code |
string | The language to display results in, available languages are: de, en, es, fr, it, pt, ru |
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
Attribute | Type | Description |
---|---|---|
found |
string | Number of addresses found matching the mailing address given |
country |
string | Full name of the located country |
country_code |
string | ISO country code of the located address |
postal_code |
string | Postal code of the location |
address |
string | The address that was used for location lookup |
city |
string | City of the located address |
latitude |
float | Latitude of the address |
longitude |
float | Longitude of the located address |
state |
string | State or Region of the located address |
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
No downtime or disruption of service will occur as you modify your 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.
This will destroy all associated data, cannot be undone and will immediately block access to the API
$ 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