Getting started with Pointpin
This page will give a quick introduction to using 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 your first request
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/18.97.14.89
That should return a JSON object that maybe looks something like this:
{
"ip": "18.97.14.89",
"continent_code": "NA",
"country_code": "US",
"country_name": "United States",
"region_name": "Virginia",
"region_code": "VA",
"city_name": "Ashburn",
"postcode": "20149",
"latitude": 39.0469,
"longitude": -77.4903,
"time_zone": "America/New_York"
}
Simple.
Using Pointpin with the Ruby Gem
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
Using Pointpin with Ruby manually
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.
Using Pointpin with PHP
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.
Using Pointpin with Node
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.