IP2COUNTRY PHP AND DELPHI CLASSES
---------------------------------

Revision 2013-02-05.

Software written by Mats Gefvert. 
Send bug reports, comments, etc to <mats@gefvert.org>.

Released into the public domain - do whatever you want with it :)


INTRO

    This software builds on the IpToCountry public download at 
    http://software77.net/geo-ip/ which has data tables for mapping a specific 
    IP adress to a country. However, it seemed appropriate to me to optimize 
    the information somewhat. This library creates a binary-optimized version
    of the data tables, and, as a result, we can do binary lookups in O(log2 n)
    time, which significantly reduces lookup time.

    While running the data tests on my Intel Core i5 laptop, the PHP class 
    averages about 40,000 lookups per second using as little as 1.5 MB overhead,
    and the Delphi class is capable of doing up to 1.1 million lookups per 
    second. Since it uses a cache feature, it is dependent on the order of IP
    addresses looked up - it prefers sequential IP addresses (=sorted IP lists).
    
    The data/ directory contains a download of the IpToCountry CSV file - you
    probably want to download a new version from the website above. There are
    a few generated files in there (generated by process_csv.php), which are
    the meat of the application. You really only need ip2country.dat, the rest 
    can be omitted.
    
    The PHP files are:
        Ip2Country.php  - contains the class that allows you to look up IP's
        lookup.php      - a command-line utility that allows you to query the
                          database
        process_csv.php - command-line script that generates the data files
                          from the CSV file
        memtest.php     - checks memory usage for preloaded data
        test.php        - runs a few timing and correctness tests on the data

    The Delphi files are
        Ip2Country.pas  - class that looks up IP addresses
        Lookups.pas     - utility class used by Ip2Country.pas
        lookup.dpr/exe  - command-line utility for looking up IP's
        multi.dpr/exe   - tool that allows you to do multiple lookups on the
                          database using standard input and output pipes.
        test.dpr/exe    - basically same as test.php
        
        
USE IN YOUR OWN PROGRAMS

    To use the library in your own programs, just use
    
        require_once 'Ip2Country.php';
        
        $ipc = new Ip2Country('ip2country.dat');
        echo $ipc->lookup('8.8.4.4');
        
    The parameter to the Ip2Country constructor is where the class can find the
    data file. If you omit the parameter, it searches for the data file in the
    current directory. $ipc->lookup() should return a two-letter ISO code.

    All you need for deployment is Ip2Country.php and ip2country.dat.
    
    The Delphi class should be ready to include into your programs without
    difficulty. It doesn't have any external dependencies beyond Lookups.pas.
    See the examples for how to integrate it - it's very straight-forward.
    

PRELOADING VS DYNAMIC LOOKUPS

    The default behavior for the PHP and Delphi class is to load data blocks
    dynamically on demand - this is good if you're only doing a few lookups; it
    will keep memory usage very low (typically a few KB's).
    
    If you're doing a lot of lookups, however, you might want to preload the
    database into memory using the preload() function. This quickly reads the
    entire database in one single call, and you can now query IPs very
    efficiently.
    
    The lookup function uses a cache function that tries to see if the IP lookup
    falls into the same block as the last lookup, and if so, it just returns the
    country code without even accessing the database. So for optimal access,
    please sort the IP addresses you're looking up - it will provide better
    cache hits.


OTHER USE

    It might be possible to use the multi.exe program as a CGI binary, although
    I haven't tested it. Since it takes a series of IP addresses as standard
    input (one IP per line) and returns a list of IP=COUNTRY rows on the
    standard output, it might work for website integration, either directly
    through a CGI or executed by a PHP or Perl script.
    
    But I haven't tested it. Feel free to let me know if it works.

    
    
Besides that, all quiet on the western front.