Free Geolocation API - IP Address to Country

Welcome developers! Develop your app or website with the power of IPAddress.com. Our free Geolocation API will help you resolve an IP address to a country. The API enables your application to query in which continent and country a given IP address is used. A query to the RESTful Geolocation 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.

Do you have a need to find out your or your visitor's public IP address in a programmatic way? We also have a My IP address API that is free and provides the caller's IP address in formats like TXT, CSV, JSON, JSONP, XML and YAML.

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=34.204.172.188

Geolocation API Parameters

The Geolocation API resolves an IP address to country and 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.

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.

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=34.204.172.188

CSV

http://api.ipaddress.com/iptocountry?format=csv&ip=34.204.172.188

JSON

http://api.ipaddress.com/iptocountry?format=json&ip=34.204.172.188&language=es

JSONP

http://api.ipaddress.com/iptocountry?format=jsonp&ip=34.204.172.188&language=fr

JSONP with Custom Callback Function

http://api.ipaddress.com/iptocountry?format=jsonp&ip=34.204.172.188&language=ja&callback=customCallback

XML

http://api.ipaddress.com/iptocountry?format=xml&ip=34.204.172.188&language=pt

YAML

http://api.ipaddress.com/iptocountry?format=yaml&ip=34.204.172.188&language=ru

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"

Share What You Found