NAV
curl ruby python php Node.js jQuery java

Introduction

Documentation for IP address location API

ipapi.co provides a REST API to find the location of an IP address.

Specifically, you can get the following information for any IP address:
city, region , country , continent, postal code, latitude, longitude, timezone, utc_offset, european union (EU) membership, country calling code, currency, languages spoken, asn and organization.

The API can also help you to find the public IP address of a device.

The API can be integrated in your application either on the server side or on the client side. The documentation below uses json format as an example. Other supported formats are xml, csv, yaml and jsonp.

Both IPv4 & IPv6 type addresses are supported.

Location of a specific IP

Complete location

require 'net/http'
require 'json'

loc = Net::HTTP.get(URI('https://ipapi.co/8.8.8.8/json/'))
puts JSON.parse(loc)
from requests import get

loc = get('https://ipapi.co/8.8.8.8/json/')
print loc.json()
<?php
    $loc = file_get_contents('https://ipapi.co/8.8.8.8/json/');
    echo $loc;
    $obj = json_decode($loc);
?>
var https = require('https');

https.get('https://ipapi.co/8.8.8.8/json/', function(resp){
    var body = ''
    resp.on('data', function(data){
        body += data;
    });

    resp.on('end', function(){
        var loc = JSON.parse(body);
        console.log(loc);
    });
});
$.getJSON('https://ipapi.co/8.8.8.8/json/', function(data){
  console.log(data)
})
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

public class Ipapi {

    public static void main(String[] args) throws IOException {
        URL ipapi = new URL("https://ipapi.co/8.8.8.8/json/");

        URLConnection c = ipapi.openConnection();
        c.setRequestProperty("User-Agent", "java-ipapi-client");
        BufferedReader reader = new BufferedReader(
          new InputStreamReader(c.getInputStream())
        );

        String line;
        while ((line = reader.readLine()) != null)
        {
            System.out.println(line);
        }
        reader.close();
    }

}
curl 'https://ipapi.co/8.8.8.8/json/'

The above command returns JSON structured like this:

{
    "ip": "8.8.8.8",
    "city": "Mountain View",
    "region": "California",
    "region_code": "CA",
    "country": "US",
    "country_name": "United States",
    "continent_code": "NA",
    "in_eu": false,
    "postal": "94035",
    "latitude": 37.386,
    "longitude": -122.0838,
    "timezone": "America/Los_Angeles",
    "utc_offset": "-0800",
    "country_calling_code": "+1",
    "currency": "USD",
    "languages": "en-US,es-US,haw,fr",
    "asn": "AS15169",
    "org": "Google LLC"
}

This endpoint returns the complete location information for an IP address specified in the URL. This type of request is typically used on the server side, where the server knows the IP address of a user and wants to retrieve it’s location.

HTTP Request

GET https://ipapi.co/{ip}/{format}/

URL Parameters

Parameter Description
ip An IP address for which you want to retrieve the location
format Data format of response, possible values are json, jsonp, xml, csv, yaml

Example

https://ipapi.co/8.8.8.8/json/

Response

The response is in one of the following formats : json, jsonp, xml, csv, yaml
and contains the following fields:

Field                      Description
ip public (external) IP address (same as URL ip)
city city name
region region name (administrative division)
region_code region code
country country code (two letter, ISO 3166-1 alpha-2)
country_name country name
continent_code continent code
in_eu whether IP address belongs to a country that is a member of European Union (EU)
postal postal code
latitude latitude
longitude longitude
timezone timezone (IANA format i.e. “Area/Location”)
utc_offset UTC offset as +HHMM or -HHMM (HH is hours, MM is minutes)
country_calling_code country calling code (dial in code, comma separated)
currency currency code (ISO 4217)
languages languages spoken (comma separated 2 or 3 letter ISO 639 code with optional hyphen separated country suffix)
asn autonomous system number
org organinzation name

Specific location field

require 'net/http'

puts Net::HTTP.get(URI('https://ipapi.co/8.8.8.8/country/'))
from requests import get

print get('https://ipapi.co/8.8.8.8/country/').text
<?php
    echo file_get_contents('https://ipapi.co/8.8.8.8/country/');
?>
var https = require('https');

https.get('https://ipapi.co/8.8.8.8/country/', function(resp){
    var body = ''
    resp.on('data', function(data){
        body += data;
    });

    resp.on('end', function(){
        console.log(body);
    });
});
$.get('https://ipapi.co/8.8.8.8/country/', function(data){
  console.log(data)
})
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

public class Ipapi {

    public static void main(String[] args) throws IOException {
        URL ipapi = new URL("https://ipapi.co/8.8.8.8/country/");

        URLConnection c = ipapi.openConnection();
        c.setRequestProperty("User-Agent", "java-ipapi-client");
        BufferedReader reader = new BufferedReader(
          new InputStreamReader(c.getInputStream())
        );
        String line;
        while ((line = reader.readLine()) != null)
        {
            System.out.println(line);
        }
        reader.close();
    }

}
curl 'https://ipapi.co/8.8.8.8/country/'

The above command returns the value for the requested field (e.g. country):

US

This endpoint returns a single location field for an IP address specified in the URL. This type of request is typically used on the server side, where the server knows the IP address of a user and wants to retrieve a particular location field as plain text.

HTTP Request

GET https://ipapi.co/{ip}/{field}/

URL Parameters

Parameter Description
ip An IP address for which you want to retrieve the location field
field A specific location field, possible values are : city, region, region_code, country, country_name, continent_code, in_eu, postal, latitude, longitude, latlong, timezone, utc_offset, languages, country_calling_code, currency, asn, org

Examples

https://ipapi.co/8.8.8.8/city/
https://ipapi.co/8.8.8.8/country/
https://ipapi.co/8.8.8.8/timezone/
https://ipapi.co/8.8.8.8/languages/
https://ipapi.co/8.8.8.8/currency/

Response

The response type is plain text and contains the value of the requested field

Field                      Description
ip public (external) IP address (same as URL ip)
city city name
region region name (administrative division)
region_code region code
country country code (two letter, ISO 3166-1 alpha-2)
country_name country name
continent_code continent code
in_eu whether IP address belongs to a country that is a member of European Union (EU)
postal postal code
latitude latitude
longitude longitude
latlong comma separated latitude and longitude
timezone timezone (IANA format i.e. “Area/Location”)
utc_offset UTC offset as +HHMM or -HHMM (HH is hours, MM is minutes)
country_calling_code country calling code (dial in code, comma separated)
currency currency code (ISO 4217)
languages languages spoken (comma separated 2 or 3 letter ISO 639 code with optional hyphen separated country suffix)
asn autonomous system number
org organinzation name
















Location of client’s IP

Complete location

require 'net/http'
require 'json'

loc = Net::HTTP.get(URI('https://ipapi.co/json/'))
puts JSON.parse(loc)
from requests import get

loc = get('https://ipapi.co/json/')
print loc.json()
<?php
    $loc = file_get_contents('https://ipapi.co/json/');
    echo $loc;
    $obj = json_decode($loc);
?>
var https = require('https');

https.get('https://ipapi.co/json/', function(resp){
    var body = ''
    resp.on('data', function(data){
        body += data;
    });

    resp.on('end', function(){
        var loc = JSON.parse(body);
        console.log(loc);
    });
});
$.getJSON('https://ipapi.co/json/', function(data){
  console.log(data)
})
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

public class Ipapi {

    public static void main(String[] args) throws IOException {
        URL ipapi = new URL("https://ipapi.co/json/");

        URLConnection c = ipapi.openConnection();
        c.setRequestProperty("User-Agent", "java-ipapi-client");
        BufferedReader reader = new BufferedReader(
          new InputStreamReader(c.getInputStream())
        );
        String line;
        while ((line = reader.readLine()) != null)
        {
            System.out.println(line);
        }
        reader.close();
    }

}
curl 'https://ipapi.co/json/'

Retrieve location for your IP address formatted as JSON
(say your IP address is “208.67.222.222”)

{
    "ip": "208.67.222.222",
    "city": "San Francisco",
    "region": "California",
    "region_code": "CA",
    "country": "US",
    "country_name": "United States",
    "continent_code": "NA",
    "in_eu": false,
    "postal": "94107",
    "latitude": 37.7697,
    "longitude": -122.3933,
    "timezone": "America/Los_Angeles",
    "utc_offset": "-0800",
    "country_calling_code": "+1",
    "currency": "USD",
    "languages": "en-US,es-US,haw,fr",
    "asn": "AS36692",
    "org": "OpenDNS, LLC"
}

This endpoint returns the complete location of the client (device) that’s making the request. You do not need to specify the IP address, it is inferred from the request. This type of request is typically used on the client side (user’s browser). The location corresponds to the public IP address of the user.

HTTP Request

GET https://ipapi.co/{format}/

URL Parameters

Parameter Description
format Data format of response, possible values are json, jsonp, xml, csv, yaml

Example

https://ipapi.co/json/

Response

The response is in one of the following formats : json, jsonp, xml, csv, yaml
and contains the following fields:

Field                      Description
ip public (external) IP address of the client / user
city city name
region region name (administrative division)
region_code region code
country country code (two letter, ISO 3166-1 alpha-2)
country_name country name
continent_code continent code
in_eu whether IP address belongs to a country that is a member of European Union (EU)
postal postal code
latitude latitude
longitude longitude
timezone timezone (IANA format i.e. “Area/Location”)
utc_offset UTC offset as +HHMM or -HHMM (HH is hours, MM is minutes)
country_calling_code country calling code (dial in code, comma separated)
currency currency code (ISO 4217)
languages languages spoken (comma separated 2 or 3 letter ISO 639 code with optional hyphen separated country suffix)
asn autonomous system number
org organinzation name

Specific location field

require 'net/http'

puts Net::HTTP.get(URI('https://ipapi.co/ip/'))
from requests import get

print get('https://ipapi.co/ip/').text
<?php
    echo file_get_contents('https://ipapi.co/ip/');
?>
var https = require('https');

https.get('https://ipapi.co/ip/', function(resp){
    var body = ''
    resp.on('data', function(data){
        body += data;
    });

    resp.on('end', function(){
        console.log(body);
    });
});
$.get('https://ipapi.co/ip/', function(data){
  console.log(data)
})
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

public class Ipapi {

    public static void main(String[] args) throws IOException {
        URL ipapi = new URL("https://ipapi.co/ip/");

        URLConnection c = ipapi.openConnection();
        c.setRequestProperty("User-Agent", "java-ipapi-client");
        BufferedReader reader = new BufferedReader(
          new InputStreamReader(c.getInputStream())
        );
        String line;
        while ((line = reader.readLine()) != null)
        {
            System.out.println(line);
        }
        reader.close();
    }

}
curl 'https://ipapi.co/ip/'

Retrieve specific field (e.g. your IP address)

208.67.222.222

This endpoint returns a single location field for the client (device) that’s making the request. You do not need to specify the IP address, it is inferred from the request. This type of request is typically used on the client side (user’s browser). The location field corresponds to the public IP address of the user. The returned value is plain text.

HTTP Request

GET https://ipapi.co/{field}/

URL Parameters

Parameter Description
field A specific location field, possible values are : ip, city, region, region_code, country, country_name, continent_code, in_eu, postal, latitude, longitude, latlong, timezone, utc_offset, languages, country_calling_code, currency, asn, org

Examples

https://ipapi.co/ip/
https://ipapi.co/city/
https://ipapi.co/country/
https://ipapi.co/timezone/
https://ipapi.co/languages/
https://ipapi.co/currency/

Response

The response type is plain text and contains the value of the requested field

Field                      Description
ip public (external) IP address of the client / user
city city name
region region name (administrative division)
region_code region code
country country code (two letter, ISO 3166-1 alpha-2)
country_name country name
continent_code continent code
in_eu whether IP address belongs to a country that is a member of European Union (EU)
postal postal code
latitude latitude
longitude longitude
latlong comma separated latitude and longitude
timezone timezone (IANA format i.e. “Area/Location”)
utc_offset UTC offset as +HHMM or -HHMM (HH is hours, MM is minutes)
country_calling_code country calling code (dial in code, comma separated)
currency currency code (ISO 4217)
languages languages spoken (comma separated 2 or 3 letter ISO 639 code with optional hyphen separated country suffix)
asn autonomous system number
org organinzation name
















Errors

The API uses the following standard error codes:

Error Code Reason Response
400 Bad Request
404 URL Not Found
405 Method Not Allowed
429 Quota exceeded { “error” : true, reason": “RateLimited” }

Additional possible errors with a 200 response may be :

For an invalid IP address, the response would be
{ "error" : true, "reason": "Invalid IP Address" }

For a reserved / non-public IP address, all fields except IP address would be null
{ "ip" : "127.0.0.1", 'city':null, ... }

If there’s no information available for a field, that particular field would be assigned a value of null