IP2CC

Free IP address to country code query service

About

IP2CC is a free IP address to country code query service (API).

Instead of a standard REST API, IP2CC is based on the DNS infrastructure due to its proven track of reliability and scalability.

Please note that if you simply want to find the country of your own IP address then just use our Android application.

IP2CC Android application

Pricing

The service is free for private and business users.

However we do offer a dedicated service for business applications for maximum reliability. Please get in touch with your business case details.

How-To

To query the country code of a particular IP address, in this example 1.2.3.4, you need to retrieve the TXT record (only TXT record, not A record!) of 1-2-3-4.free.query.ip2cc.com. 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:
    • IPv6: 0123:4567:0000:0000:0000:0000:89ab:cdef becomes 0123-4567-0000-0000-0000-0000-89ab-cdef
    • IPv4: 1.2.3.4 becomes 1-2-3-4
  2. Query the DNS TXT record of "hyphenated IP address" + ".free.query.ip2cc.com". Example:
    • IPv6: 0123-4567-0000-0000-0000-0000-89ab-cdef.free.query.ip2cc.com
    • IPv4: 1-2-3-4.free.query.ip2cc.com

It is important your application only and exclusively queries the TXT record and nothing else. Querying other records types (A, MX, etc.) is pointless and wastes resources.

The DNS query should always go to your system's normal DNS resolver of choice (default behaviour). Users or applications not following this simple point will unfortunately be blocked.

Examples:

dig

$ dig +short TXT 0123-4567-0000-0000-0000-0000-89ab-cdef.free.query.ip2cc.com
"IP"

$ dig +short  TXT 1-2-3-4.free.query.ip2cc.com 
"US"

host

$ host -t TXT 0123-4567-0000-0000-0000-0000-89ab-cdef.free.query.ip2cc.com
0123-4567-0000-0000-0000-0000-89ab-cdef.free.query.ip2cc.com descriptive text "IP"

$ host -t TXT 1-2-3-4.free.query.ip2cc.com 
1-2-3-4.free.query.ip2cc.com descriptive text "US"

nslookup

$ nslookup -type=TXT 0123-4567-0000-0000-0000-0000-89ab-cdef.free.query.ip2cc.com
0123-4567-0000-0000-0000-0000-89ab-cdef.free.query.ip2cc.com	text = "IP"

$ nslookup -type=TXT 1-2-3-4.free.query.ip2cc.com 
1-2-3-4.free.query.ip2cc.com	text = "US"

PHP

<?php

// 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 query: 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 query: 1.2.3.4 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.ip2cc.com';

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

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

// PHP's function assigns the TXT record to a child array, reassign to a variable
$cc = $record[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.

Contact

Your feedback is welcome! Please get in touch at:

ip2cc @ calpeconsulting.com