Pointpin

Thanks for trying out Pointpin. I'm going to walk you through how to get your app or site set up with Pointpin's fast and reliable geolocation API. This page will show very basic integration with Ruby, PHP, and Node, but the API is language and framework agnostic: it returns vanilla JSON, so any programming environment with a JSON library can use Pointpin.

This page assumes you've created a Pointpin project and thereby have an API key to make requests.

Making a request for geolocation data with Pointpin is pretty simple. Try running this in the command line:

curl https://geo.pointp.in/[your api key]/json/3.17.186.218

That should return a JSON object that maybe looks something like this:

{
  "ip": "3.17.186.218",
  "continent_code": "NA",
  "country_code": "US",
  "country_name": "United States",
  "region_name": "Ohio",
  "region_code": "OH",
  "city_name": "Columbus",
  "postcode": "43215",
  "latitude": 39.9625,
  "longitude": -83.0061,
  "time_zone": "America/New_York"
}

Simple.

We recommend using the official Pointpin Ruby gem for integration with Ruby apps. First install the gem by adding this to your gemfile.

gem 'pointpin', '~> 1.0.0'

Then configure the gem to use your API key (in Rails, you can do this in config/initializers/pointpin.rb):

Pointpin.api_key = '[your_api_key]'

You're all set up now. You can make Pointpin API requests easily:

location = Pointpin.locate(target_ip)

The location variable is now a Hashie::Mash object containing a bunch of useful information about the IP's location:

#<Hashie::Mash city_name="Dublin" continent_code="EU"
country_code="IE" country_name="Ireland"
ip="55.111.555.555" latitude=53.3331 longitude=-6.2489
postcode=nil region_name="Dublin City" time_zone="Europe/Dublin">

So, for example, you can persist the visitor's time zone.

current_user.time_zone = location.time_zone
current_user.save

Integrating Pointpin into a Ruby application without the gem is easy, too. I'm going to use open-uri, which is a nice wrapper for net/http, and Ruby's json module.

require 'open-uri'
require 'json'
url = "https://geo.pointp.in/[your_api_key]/json/[target_ip]"
location_data = JSON.parse(URI.parse(url).read)

The location_data variable is now a Ruby hash with useful local information about the target IP.

As of version 5.2, PHP comes bundled with some useful JSON functions. We're going to use file_get_contents to make the request and json_decode to parse the results.

$url = "https://geo.pointp.in/[your_api_key]/json/[target_ip]";
$json = file_get_contents($url);
$location_data = json_decode($json, true);

The $location_data variable is now a PHP associative array with useful local information about the target IP.

Node has great built-in support for JSON. We're going ot use http.get to make the request, and

var url = 'https://geo.pointp.in/[your_api_key]/json/[target_ip]';

http.get(url, function(res) {
  var pp_json = '';

  res.on('data', function(chunk) {
    pp_json += chunk;
  });

  res.on('end', function() {
    var locationData = JSON.parse(pp_json)
  });
})

The locationData variable is a Javascript object with useful local information about the target IP.