Recently while coding my "who is online" WordPress plugin Quick Count I had an idea that it would be great if I could somehow detect visitor's country of origin from his IP address. After doing some research I've learned that most online IP to country services are proprietary and offer limited services for free or they don't offer free service at all. Then I came across a great ip-countryside open source project by Markus Goldstein. He has developed open source C++ application that creates IP to country database using 5 Regional Internet Registries (RIR): AFRINIC, APNIC, ARIN, LACNIC and RIPE. I've decided to create open source WordPress plugin named Quick Flag that uses this database to provide IP to country services to all WordPress community. In this article I'll show you how to install and use Quick Flag IP to country functionality from your own plugin or theme.

Installation

Quick Flag is hosted by the official WordPress plugin directory from where it can be installed using integrated WordPress plugin installer or manually.

Integrated WordPress plugin installer method

• Go to Plugins > Add New.
• Under Search, type in 'Quick Flag'.
• Click Install Now to install the WordPress Plugin.
• A popup window will ask you to confirm your wish to install the Plugin.
• If this is the first time you've installed a WordPress Plugin, enter the FTP login credential information. If you've installed a Plugin before, it will still have the login information.
• Click Proceed to continue with the installation. The resulting installation screen will list the installation as successful or note any problems during the install.
• If successful, click Activate Plugin to activate it, or Return to Plugin Installer for further actions.
• Have fun using Quick Flag from your own plugin or theme.

Manual method

• Upload 'quick-flag' folder from quick-flag.zip file downloaded from Quick Flag WordPress plugin directory page to the '/wp-content/plugins/' directory.
• Activate 'Quick Flag' plugin through the 'Plugins' menu in WordPress.
• Have fun using Quick Flag from your own plugin or theme.

If you're plugin or theme developer you can bundle Quick Flag with your theme or add notice to your plugin or theme informing your users about increased functionality if they install Quick Flag. After installation Quick Flag will automatically update its IP to country database (weekly).

Big thanks to Markus Goldstein for generating weekly database updates and providing automatic update server.

Usage

Besides IP to country features Quick Flag comes with Quality Set of country flag icons created by Mark James. This way you can present your plugin or theme users not only country name but also country flags. Here's the basic Quick Flag usage example for imaginary 123.123.123.123 IP address originating from country Croatia:

// Query database with following IP address 
$ip_address = '123.123.123.123';
global $quick_flag;
if(isset($quick_flag) && is_object($quick_flag)){
    if(($info = $quick_flag->get_info($ip_address)) != false){
        $version = $info->version;      // Quick Flag version (float): 2.00
        $ip = $info->ip;                // IP address (string): 123.123.123.123
        $code = $info->code;            // Country code (string): HR
        $name = $info->name;            // Country name (string): Croatia
        $latitude = $info->latitude;    // Country latitude (float): 45.1667
        $longitude = $info->longitude;  // Country longitude (float): 15.5
        $flag = $quick_flag->get_flag($info, 'my-own-css-class'); // CSS class is optional, 'quick-flag' by default
    }
}

After executing preceding code $flag variable will contain following string:

<img
    class="my-own-css-class"
    title="Croatia"
    src="http://www.yoursite.com/wp-content/plugins/quick-flag/img/flags/HR.gif"
/>

That's my 100% open source solution for IP to country functionality for any WordPress plugin or theme. Any questions please post here or at Quick Flag official page here at TechyTalk.info.