IP Address To Country API

Our free IP Address To Country API enables your application to query in which continent and country a given IP address is used.
A query to the RESTful API will return continent and country codes as well as the corresponding names in several languages to choose from. The result can be retrieved in common data formats like TXT, CSV, JSON, JSONP, XML, and YAML. Please refer to the documentation below for implementation details and sample code.

API URL

The API URL has the following form:

http://api.ipaddress.com/iptocountry?parameters

The list of supported parameters and returned values is enumerated further below. Parameters are submitted using a standard query string, and individual parameters are separated using the ampersand ( & ) character as shown in the following example:

http://api.ipaddress.com/iptocountry?format=json&ip=54.92.128.223

API Parameters

The IP Address To Country API supports the parameters listed below. All values are case sensitive unless noted otherwise. Some parameters are used for certain output formats only.
If you send a request with unsupported parameter values it might get answered with either 400 Bad Request or 404 Not Found HTTP status code.

Parameter Required Possible Values Default Value Supported Formats
format no
  • csv - Comma Separated Values
  • json - JavaScript Object Notation
  • jsonp - JSON with Padding
  • txt - Plain Text
  • xml - Extensible Markus Language
  • yaml - YAML
txt n/a
ip no Any IPv4 Address Caller's IP address All
language no
  • de - German
  • en - English
  • es - Spanish
  • fr - French
  • ja - Japanese
  • pt - Portuguese
  • ru - Russian
  • zh - Chinese
en All but txt
callback no Up to 63 alphanumeric characters ([a-zA-Z0-9]) callback jsonp

API Return Values

The API returns the IP address queried as well as the continent and country code and name where the IP address is used. If the IP address cannot be resolved to a certain continent or country then empty fields will be returned.

Value Description Supported Formats
ipaddress The IPv4 Address queried All but txt
continent_code The continent code. Possible values are
  • AF - Africa
  • AN - Antarctica
  • AS - Asia
  • EU - Europe
  • NA - North America
  • OC - Oceania
  • SA - South America
All but txt
continent_name The name of the continent in the requested locale All but txt
country_code The two-letter ISO 3166-1 country code All
country_name The name of the country in the requested locale All but txt

API Usage Samples

The plain text data format returns the country code only, the other formats provide more information about the queried IP address. Please have a look at the samples further below to find out how the values are returned in individual formats.

Plain Text

http://api.ipaddress.com/iptocountry
http://api.ipaddress.com/iptocountry?format=txt
http://api.ipaddress.com/iptocountry?format=txt&ip=54.92.128.223
US

CSV

http://api.ipaddress.com/iptocountry?format=csv&ip=54.92.128.223
ipaddress,continent_code,continent_name,country_code,country_name
54.92.128.223,NA,"North America",US,"United States"

JSON

http://api.ipaddress.com/iptocountry?format=json&ip=54.92.128.223&language=es
{"ipaddress":"54.92.128.223","continent_code":"NA","continent_name":"Norteamérica","country_code":"US","country_name":"Estados Unidos"}

JSONP

http://api.ipaddress.com/iptocountry?format=jsonp&ip=54.92.128.223&language=fr
callback({"ipaddress":"54.92.128.223","continent_code":"NA","continent_name":"Amérique du Nord","country_code":"US","country_name":"États-Unis"});

JSONP with Custom Callback Function

http://api.ipaddress.com/iptocountry?format=jsonp&ip=54.92.128.223&language=ja&callback=customCallback
customCallback({"ipaddress":"54.92.128.223","continent_code":"NA","continent_name":"北アメリカ","country_code":"US","country_name":"アメリカ合衆国"});

XML

http://api.ipaddress.com/iptocountry?format=xml&ip=54.92.128.223&language=pt
<?xml version="1.0"?><location><ipaddress>54.92.128.223</ipaddress><continent_code>NA</continent_code><continent_name>América do Norte</continent_name><country_code>US</country_code><country_name>Estados Unidos</country_name></location>

YAML

http://api.ipaddress.com/iptocountry?format=yaml&ip=54.92.128.223&language=ru
---
ipaddress: 54.92.128.223
continent_code: NA
continent_name: Северная Америка
country_code: US
country_name: США

Sample Code

The API can be queried from almost any programming language, and even for a single programming language different methods may be available. The following code samples provide an overview about common techniques to retrieve the country mapping for a given IP address. To keep the examples simple error checking has been omitted.

PHP

<?php
$csv = array_map ('str_getcsv', file('http://api.ipaddress.com/iptocountry?format=csv'));
print_r ($csv);
?>
<?php
$xml = simplexml_load_file ('http://api.ipaddress.com/iptocountry?format=xml');
print_r ($xml);
?>
<?php
$ch = curl_init ('http://api.ipaddress.com/iptocountry?format=json');
curl_setopt ($ch, CURLOPT_RETURNTRANSFER, true);
$data = curl_exec ($ch);
curl_close ($ch);
$json = json_decode ($data);
print_r ($json);
?>

Javascript

<script type="text/javascript">
function iptocountry(callback){
  var r;
  if (window.XMLHttpRequest)r=new XMLHttpRequest();
  else r=new ActiveXObject("Microsoft.XMLHTTP");
  r.onreadystatechange=function(){
    if (r.readyState==4&&r.status=="200")callback(r.responseText);
  };
  r.open("GET","http://api.ipaddress.com/iptocountry?format=json",true);
  r.send(null);
}
iptocountry(function(response){
  var json=JSON.parse(response);
  document.write("<p>IP address: "+json.ipaddress+"</p>");
  document.write("<p>Country Code: "+json.country_code+"</p>");
  document.write("<p>Country Name: "+json.country_name+"</p>");
});
</script>

jQuery

<script src="https://code.jquery.com/jquery-1.12.3.min.js"></script>
<script type="text/javascript">
$(document).ready(function(){
  $.getJSON("http://api.ipaddress.com/iptocountry?format=json",function(json){
    document.write("<p>IP address: "+json.ipaddress+"</p>");
    document.write("<p>Country Code: "+json.country_code+"</p>");
    document.write("<p>Country Name: "+json.country_name+"</p>");
  });
});
</script>

Bash

#!/bin/bash
COUNTRY=$(curl -s http://api.ipaddress.com/iptocountry)
echo "Country Code: $COUNTRY"
#!/bin/bash
COUNTRY=`curl -s http://api.ipaddress.com/iptocountry`
echo "Country Code: $COUNTRY"
Top of the Page