Free IP address to country code lookup API service


IP2.CC is a free IP address to country code lookup service (API).

The service is based on the DNS infrastructure due to DNS' proven track of reliability and scalability.


The service is free for private users or applications under development.

For commercial applications in production a license fee is applicable. The license also provides access to a REST API. Please get in touch.

If you are a satisfied free user of this service, a donation would be appreciated to continue maintenance and development.


To lookup the country code of a particular IP address, in this example, you need to retrieve the TXT record (TXT, not A record!) of This will return you the two-letter ISO country code of the IP address requested.

So to summarise there are two steps involved:

  1. Change the IPv6 colons (:) or IPv4 dots (.) for hyphens (-). Examples:
  2. Lookup the DNS TXT record of "hyphenated IP address" + ".free.query.ip2.cc". Example:

It is important your application only and exclusively requests the TXT record and nothing else. Requesting other records types (A, MX, CNAME, etc.) is pointless and wastes resources. Users or applications not following this simple point will unfortunately be blocked.


The following is a simple PHP example on how to retrieve the country code from an IP address:


// If "ip" is passed either via GET or POST use that IP address
if (isset($_REQUEST["ip"] )) $ip = strip_tags(trim($_REQUEST["ip"]));

// If not, use the client's (visitor's) IP address instead
else $ip = $_SERVER["REMOTE_ADDR"];

// In case your IPv6 address comes from another source and is not fully expanded use this function first
function expandIPv6($ip){
	$hex = unpack("H*hex", inet_pton($ip));
        return implode(':', str_split($hex['hex'], 4));
$ip = expandIPv6($ip);

// First check if it is fully expanded IPv6 address, if not we assume it is IPv4. If not fully expanded you first need to run the previous function
if(strlen($ip) == 39) {
	// Substitute the colons (:) in the IPv6 address to prepare for the DNS lookup: 0123:4567:0000:0000:0000:0000:89ab:cdef becomes 0123-4567-0000-0000-0000-0000-89ab-cdef
	$ip = str_replace('-', ':', $ip); //IPv6
} else {
	// Substitute the dots (.) in the IPv4 address to prepare for the DNS lookup: becomes 1-2-3-4
	$ip = str_replace('-', '.', $ip); //IPv4

// Define your account, if non-paying use the free one
$account = 'free';

// Define hostname used
$hostname = 'query.ip2.cc';

// Merge full query domain
$query = $ip . '.' . $account . '.' . $hostname;

// Lookup the TXT record storing the country code of the IP address and suppress any outputted errors
$lookup = @dns_get_record($query, DNS_TXT);

// PHP's function assigns the TXT record to a child array, reassign to a variable
$cc = $lookup[0]['txt'];

// Output the country code stored in the variable
echo $cc;

Country Names

Apart from the country codes, if you also need the English country names then you can download the following country-to-code mapping list to use with the service.

Make sure you save it in UTF-8.


Please get in touch at:

ip2cc @ calpeconsulting.com

Your feedback is welcome.