This add-on is operated by Expedited Security

Find the Country and City of origin for an IP Address

Last updated March 23, 2019

IP to Earth is an add-on to find the Country, City, Region, Latitude and Longitude of origin for an IP Address

Identifying the geographic location of a site visitor let you customize content, speed delivery, filter options or pre-fill data for your users.

IP to Earth exposes an API and has supported examples for Ruby, PHP, Python, Node and Java.

Provisioning the add-on

IP to Earth can be attached to a Heroku application via the CLI:

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

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

$ heroku config:get IPTOEARTH_API_KEY
Bl4XHVbdsf5GIXQbqTfXR5IrpuuXER2kaVc2zNnA

After installing IP to Earth 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 IPTOEARTH_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 Ip-To-Earth gem.

# In your Gemfile
gem 'iptoearth', git: 'https://github.com/mbuckbee/Ip-To-Earth-Gem.git'

Making a Request

require "ip_to_earth"

# 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

ite = IpToEarth::APIController.new

result = ite.lookup('68.10.149.45') # Pass in any valid IPv4 or IPv6 value

Using Results

result.valid
 => true

result.country
 => "United States"

result.country_code
 => "US"

result.hostname
 => ""

result.city
 => "Virginia Beach"

result.ip
 => "68.10.149.45"

result.latitude
 => 36.852928161621094

result.longitude
 => -75.97798156738281

result.region
 => "Virginia"

Using with PHP

<?php

$ch = curl_init('https://iptoearth.expeditedaddons.com/?api_key=' . getenv('IPTOEARTH_API_KEY') . '&ip=68.10.149.45');

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

var_dump($response);

Using with Python

import os
from urllib2 import Request, urlopen

request = Request('https://iptoearth.expeditedaddons.com/?api_key=' + os.environ['IPTOEARTH_API_KEY'] + '&ip=68.10.149.45')

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

Using with Node

var request = require('request');

request('https://iptoearth.expeditedaddons.com/?api_key=' + process.env.IPTOEARTH_API_KEY + '&ip=68.10.149.45', 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 dependencies 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://iptoearth.expeditedaddons.com/?api_key=' + System.getenv('IPTOEARTH_API_KEY') + '&ip=68.10.149.45}')
  .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 IP to Earth dashboard allows you to monitor your API usage limits.

The dashboard can be accessed via the CLI:

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

or by visiting the Heroku Dashboard and selecting the application in question. Select IP to Earth 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://iptoearth.expeditedaddons.com/?api_key=REPLACE_WITH_YOUR_IPTOEARTH_API_KEY&ip=68.10.149.45

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 IP to Earth dashboard.

Migrating between plans

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

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

Removing the add-on

IP to Earth can be removed via the CLI.

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

Support

All IP to Earth 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