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 (name & code), country (name & code), continent, postal code / zip code, latitude, longitude, timezone, utc offset, european union (EU) membership, country calling code, country capital, country tld (top-level domain), currency (name & code), area & population of the country, languages spoken, asn, organization and hostname*.

* hostname is an optional add-on, currently in beta. Please contact us to learn more about it or to enable it for your account.

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.

Please refer to the right pane for examples in Ruby, Python, PHP, Javascript, Node.js, jQuery, Java, C# and Go. If your language of choice isn’t listed here, it doesn’t mean that the API can’t handle it, as long as you can send an HTTP web request and consume the response. Please contact us for any support requests.

Location of a specific IP

Complete location

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

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);
?>

fetch('https://ipapi.co/8.8.8.8/json/')
.then(function(response) {
  response.json().then(jsonData => {
    console.log(jsonData);
  });
})
.catch(function(error) {
  console.log(error)
});

var https = require('https');

const options = {
  path: '/8.8.8.8/json/',
  host: 'ipapi.co',
  port: 443,
  headers: { 'User-Agent': 'nodejs-ipapi-v1.02' }
};
https.get(options, 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-v1.02");
        BufferedReader reader = new BufferedReader(
          new InputStreamReader(c.getInputStream())
        );

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

}

using System;
using System.Net;
using System.IO;
using System.Text;

public class Program
{
  public static void Main()
  {   
      ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;
      HttpWebRequest request = (HttpWebRequest)WebRequest.Create("https://ipapi.co/8.8.8.8/json/");
      request.UserAgent="ipapi.co/#c-sharp-v1.03";
      HttpWebResponse response = (HttpWebResponse)request.GetResponse();
      var reader = new System.IO.StreamReader(response.GetResponseStream(), UTF8Encoding.UTF8);
      Console.WriteLine(reader.ReadToEnd());
  }
}

package main
import (
    "fmt"
    "io/ioutil"
    "log"
    "net/http"
)
func main() {
    ipapiClient := http.Client{}
    req, err := http.NewRequest("GET", "https://ipapi.co/8.8.8.8/json/", nil)
    req.Header.Set("User-Agent", "ipapi.co/#go-v1.5")
    resp, err := ipapiClient.Do(req)
    defer resp.Body.Close()
    body, err := ioutil.ReadAll(resp.Body)    
    if err != nil {log.Fatal(err) }
    fmt.Println(string(body))
}

The above code returns the following JSON output (except for hostname, which is an optional add-on)

{
    "ip": "8.8.8.8",
    "version": "IPv4",
    "city": "Mountain View",
    "region": "California",
    "region_code": "CA",
    "country_code": "US",
    "country_code_iso3": "USA",
    "country_name": "United States",
    "country_capital": "Washington",
    "country_tld": ".us",
    "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",
    "currency_name": "Dollar",
    "languages": "en-US,es-US,haw,fr",
    "country_area": 9629091.0,
    "country_population": 310232863,
    "asn": "AS15169",
    "org": "Google LLC"
    "hostname": "dns.google"
}

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

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:

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/');
?>

fetch('https://ipapi.co/8.8.8.8/country/')
.then(function(response) {
  response.text().then(txt => {
    console.log(txt);
  });
})
.catch(function(error) {
  console.log(error)
});

var https = require('https');

const options = {
  path: '/8.8.8.8/country/',
  host: 'ipapi.co',
  port: 443,
  headers: { 'User-Agent': 'nodejs-ipapi-v1.02' }
};
https.get(options, 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-v1.02");
        BufferedReader reader = new BufferedReader(
          new InputStreamReader(c.getInputStream())
        );
        String line;
        while ((line = reader.readLine()) != null)
        {
            System.out.println(line);
        }
        reader.close();
    }

}

using System;
using System.Net;
using System.IO;
using System.Text;
public class Program
{
  public static void Main()
  {   
      ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;
      HttpWebRequest request = (HttpWebRequest)WebRequest.Create("https://ipapi.co/8.8.8.8/country/");
      request.UserAgent="ipapi.co/#c-sharp-v1.03";
      HttpWebResponse response = (HttpWebResponse)request.GetResponse();
      var reader = new System.IO.StreamReader(response.GetResponseStream(), UTF8Encoding.UTF8);
      Console.WriteLine(reader.ReadToEnd());
  }
}

package main
import (
    "fmt"
    "io/ioutil"
    "log"
    "net/http"
)
func main() {
    ipapiClient := http.Client{}
    req, err := http.NewRequest("GET", "https://ipapi.co/8.8.8.8/country/", nil)
    req.Header.Set("User-Agent", "ipapi.co/#go-v1.5")
    resp, err := ipapiClient.Do(req)
    defer resp.Body.Close()
    body, err := ioutil.ReadAll(resp.Body)    
    if err != nil {log.Fatal(err) }
    fmt.Println(string(body))
}

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

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

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);
?>

fetch('https://ipapi.co/json/')
.then(function(response) {
  response.json().then(jsonData => {
    console.log(jsonData);
  });
})
.catch(function(error) {
  console.log(error)
});

var https = require('https');

const options = {
  path: '/json/',
  host: 'ipapi.co',
  port: 443,
  headers: { 'User-Agent': 'nodejs-ipapi-v1.02' }
};
https.get(options, 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-v1.02");
        BufferedReader reader = new BufferedReader(
          new InputStreamReader(c.getInputStream())
        );
        String line;
        while ((line = reader.readLine()) != null)
        {
            System.out.println(line);
        }
        reader.close();
    }

}

using System;
using System.Net;
using System.IO;
using System.Text;
public class Program
{
  public static void Main()
  {   
      ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;
      HttpWebRequest request = (HttpWebRequest)WebRequest.Create("https://ipapi.co/json/");
      request.UserAgent="ipapi.co/#c-sharp-v1.03";
      HttpWebResponse response = (HttpWebResponse)request.GetResponse();
      var reader = new System.IO.StreamReader(response.GetResponseStream(), UTF8Encoding.UTF8);
      Console.WriteLine(reader.ReadToEnd());
  }
}

package main
import (
    "fmt"
    "io/ioutil"
    "log"
    "net/http"
)
func main() {
    ipapiClient := http.Client{}
    req, err := http.NewRequest("GET", "https://ipapi.co/json/", nil)
    req.Header.Set("User-Agent", "ipapi.co/#go-v1.5")
    resp, err := ipapiClient.Do(req)
    defer resp.Body.Close()
    body, err := ioutil.ReadAll(resp.Body)    
    if err != nil {log.Fatal(err) }
    fmt.Println(string(body))
}

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

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:

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/');
?>

fetch('https://ipapi.co/ip/')
.then(function(response) {
  response.text().then(txt => {
    console.log(txt);
  });
})
.catch(function(error) {
  console.log(error)
});

var https = require('https');

const options = {
  path: '/ip/',
  host: 'ipapi.co',
  port: 443,
  headers: { 'User-Agent': 'nodejs-ipapi-v1.02' }
};
https.get(options, 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-v1.02");
        BufferedReader reader = new BufferedReader(
          new InputStreamReader(c.getInputStream())
        );
        String line;
        while ((line = reader.readLine()) != null)
        {
            System.out.println(line);
        }
        reader.close();
    }

}

using System;
using System.Net;
using System.IO;
using System.Text;
public class Program
{
  public static void Main()
  {   
      ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;
      HttpWebRequest request = (HttpWebRequest)WebRequest.Create("https://ipapi.co/ip/");
      request.UserAgent="ipapi.co/#c-sharp-v1.03";
      HttpWebResponse response = (HttpWebResponse)request.GetResponse();
      var reader = new System.IO.StreamReader(response.GetResponseStream(), UTF8Encoding.UTF8);
      Console.WriteLine(reader.ReadToEnd());
  }
}

package main
import (
    "fmt"
    "io/ioutil"
    "log"
    "net/http"
)
func main() {
    ipapiClient := http.Client{}
    req, err := http.NewRequest("GET", "https://ipapi.co/ip/", nil)
    req.Header.Set("User-Agent", "ipapi.co/#go-v1.5")
    resp, err := ipapiClient.Do(req)
    defer resp.Body.Close()
    body, err := ioutil.ReadAll(resp.Body)    
    if err != nil {log.Fatal(err) }
    fmt.Println(string(body))
}

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

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

Errors

The API uses the following standard HTTP 4xx client error codes :

Additional possible errors with a HTTP 200 status code have a response in the following format :

{ "error": true, "reason": "...", "ip": "..."}

Some examples are :

If there’s no information available for a particular field, then that field would be assigned a value depending on the chosen output format i.e.