Free Geolocation API - IP Address to Country

Welcome developers! Develop your app or website with the power of 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.


The API URL has the following form:

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:

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.

ParameterRequiredPossible ValuesDefault ValueSupported Formats
  • csv - Comma Separated Values
  • json - JavaScript Object Notation
  • jsonp - JSON with Padding
  • txt - Plain Text
  • xml - Extensible Markus Language
  • yaml - YAML
ipnoAny IPv4 AddressCaller's IP addressAll
  • de - German
  • en - English
  • es - Spanish
  • fr - French
  • ja - Japanese
  • pt - Portuguese
  • ru - Russian
  • zh - Chinese
enAll but txt
callbacknoUp to 63 alphanumeric characters ([a-zA-Z0-9])callbackjsonp

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.

ValueDescriptionSupported Formats
ipaddressThe IPv4 Address queriedAll but txt
continent_codeThe 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_nameThe name of the continent in the requested localeAll but txt
country_codeThe two-letter ISO 3166-1 country codeAll
country_nameThe name of the country in the requested localeAll 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

ipaddress,continent_code,continent_name,country_code,country_name,NA,"North America",US,"United States"

{"ipaddress":"","continent_code":"NA","continent_name":"Norteamérica","country_code":"US","country_name":"Estados Unidos"}

callback({"ipaddress":"","continent_code":"NA","continent_name":"Amérique du Nord","country_code":"US","country_name":"États Unis"});

JSONP with Custom Callback Function

<?xml version="1.0"?><location><ipaddress></ipaddress><continent_code>NA</continent_code><continent_name>América do Norte</continent_name><country_code>US</country_code><country_name>EUA</country_name></location>

--- ipaddress: 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.


$csv = array_map ('str_getcsv', file(''));
print_r ($csv);
$xml = simplexml_load_file ('');
print_r ($xml);
$ch = curl_init ('');
curl_setopt ($ch, CURLOPT_RETURNTRANSFER, true);
$data = curl_exec ($ch);
curl_close ($ch);
$json = json_decode ($data);
print_r ($json);


<script type="text/javascript">
function iptocountry(callback){
  var r;
  if (window.XMLHttpRequest)r=new XMLHttpRequest();
  else r=new ActiveXObject("Microsoft.XMLHTTP");
    if (r.readyState==4&&r.status=="200")callback(r.responseText);
  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 src=""></script>
<script type="text/javascript">
    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>");


COUNTRY=$(curl -s
echo "Country Code: $COUNTRY"
COUNTRY=`curl -s`
echo "Country Code: $COUNTRY"