java.lang.Object
com.maxmind.geoip.LookupService
public class LookupServiceextends Object
Provides a lookup service for information based on an IP address. The location of a database file is supplied when creating a lookup service instance. The edition of the database determines what information is available about an IP address. See the DatabaseInfo class for further details.

The following code snippet demonstrates looking up the country that an IP address is from:

// First, create a LookupService instance with the location of the database.
LookupService lookupService = new LookupService("c:\\geoip.dat");
// Assume we have a String ipAddress (in dot-decimal form).
Country country = lookupService.getCountry(ipAddress);
System.out.println("The country is: " + country.getName());
System.out.println("The country code is: " + country.getCode());
In general, a single LookupService instance should be created and then reused repeatedly.

Tip: Those deploying the GeoIP API as part of a web application may find it difficult to pass in a File to create the lookup service, as the location of the database may vary per deployment or may even be part of the web-application. In this case, the database should be added to the classpath of the web-app. For example, by putting it into the WEB-INF/classes directory of the web application. The following code snippet demonstrates how to create a LookupService using a database that can be found on the classpath:

String fileName = getClass().getResource("/GeoIP.dat").toExternalForm()
        .substring(6);
LookupService lookupService = new LookupService(fileName);

  • Field Details

    • file

      private RandomAccessFile file
      Random access handle on the database file.

    • databaseFile

      private final File databaseFile
      The GeoIP database file.

    • databaseInfo

      private DatabaseInfo databaseInfo
      Information about the database.

    • charset

      private static final Charset charset
      Charset used for the database strings.

    • charsetDecoder

      private final CharsetDecoder charsetDecoder
      Decoder for the database strings.

    • databaseType

      private byte databaseType
      The database type. Default is the country edition.

    • databaseSegments

      private int[] databaseSegments
      Segment start offsets in the database.

    • recordLength

      private int recordLength
      Record length in bits, from the file.

    • dboptions

      private int dboptions
      Database type flags for this file.

    • dbbuffer

      private byte[] dbbuffer
      The whole database, when memory-mapped mode is off.

    • index_cache

      private byte[] index_cache
      Cache of the first-level index records.

    • mtime

      private long mtime
      Modification time of the database file.

    • last_netmask

      private int last_netmask
      Netmask of the last lookup.

    • US_OFFSET

      private static final int US_OFFSET
      Country table offset for US state records.
      See Also:

    • CANADA_OFFSET

      private static final int CANADA_OFFSET
      Country table offset for Canadian province records.
      See Also:

    • WORLD_OFFSET

      private static final int WORLD_OFFSET
      Country table offset for world region records.
      See Also:

    • FIPS_RANGE

      private static final int FIPS_RANGE
      Size of the FIPS country code range.
      See Also:

    • COUNTRY_BEGIN

      private static final int COUNTRY_BEGIN
      Database offset where country records begin.
      See Also:

    • STATE_BEGIN_REV0

      private static final int STATE_BEGIN_REV0
      State record start in revision 0 databases.
      See Also:

    • STATE_BEGIN_REV1

      private static final int STATE_BEGIN_REV1
      State record start in revision 1 databases.
      See Also:

    • STRUCTURE_INFO_MAX_SIZE

      private static final int STRUCTURE_INFO_MAX_SIZE
      Longest structure info field read.
      See Also:

    • DATABASE_INFO_MAX_SIZE

      private static final int DATABASE_INFO_MAX_SIZE
      Longest database info field read.
      See Also:

    • GEOIP_STANDARD

      public static final int GEOIP_STANDARD
      No cache: every node visit is a disk read.
      See Also:

    • GEOIP_MEMORY_CACHE

      public static final int GEOIP_MEMORY_CACHE
      Cache flag: load the whole database into RAM and read records from it.
      See Also:

    • GEOIP_CHECK_CACHE

      public static final int GEOIP_CHECK_CACHE
      Cache flag: stat the database file on each lookup and reload it if it changed.
      See Also:

    • GEOIP_INDEX_CACHE

      public static final int GEOIP_INDEX_CACHE
      Cache flag: hold the search index in RAM while still reading records from disk.
      See Also:

    • GEOIP_UNKNOWN_SPEED

      public static final int GEOIP_UNKNOWN_SPEED
      NetSpeed edition: the ISP's connection speed is not classified.
      See Also:

    • GEOIP_DIALUP_SPEED

      public static final int GEOIP_DIALUP_SPEED
      NetSpeed edition: the connection is dialup or slower.
      See Also:

    • GEOIP_CABLEDSL_SPEED

      public static final int GEOIP_CABLEDSL_SPEED
      NetSpeed edition: the connection is cable or DSL.
      See Also:

    • GEOIP_CORPORATE_SPEED

      public static final int GEOIP_CORPORATE_SPEED
      NetSpeed edition: the connection is corporate or faster.
      See Also:

    • SEGMENT_RECORD_LENGTH

      private static final int SEGMENT_RECORD_LENGTH
      Record length for segment regions, in bytes.
      See Also:

    • STANDARD_RECORD_LENGTH

      private static final int STANDARD_RECORD_LENGTH
      Record length for standard databases, in bytes.
      See Also:

    • ORG_RECORD_LENGTH

      private static final int ORG_RECORD_LENGTH
      Record length for org databases, in bytes.
      See Also:

    • MAX_RECORD_LENGTH

      private static final int MAX_RECORD_LENGTH
      Longest record length supported.
      See Also:

    • MAX_ORG_RECORD_LENGTH

      private static final int MAX_ORG_RECORD_LENGTH
      Longest org record read.
      See Also:

    • FULL_RECORD_LENGTH

      private static final int FULL_RECORD_LENGTH
      Scratch buffer size for a full record.
      See Also:

    • UNKNOWN_COUNTRY

      private final Country UNKNOWN_COUNTRY
      Country returned when nothing matches.

    • countryCode

      private static final String[] countryCode
      Country codes indexed by the database.

    • countryName

      private static final String[] countryName
      Country names indexed by the database.

  • Constructor Details

    • LookupService

      public LookupService(String databaseFile) throws IOException
      Create a new lookup service using the specified database file.
      Parameters:
      databaseFile - String representation of the database file.
      Throws:
      IOException - if an error occured creating the lookup service from the database file.

    • LookupService

      public LookupService(File databaseFile) throws IOException
      Create a new lookup service using the specified database file.
      Parameters:
      databaseFile - the database file.
      Throws:
      IOException - if an error occured creating the lookup service from the database file.

    • LookupService

      public LookupService(String databaseFile, int options) throws IOException
      Create a new lookup service using the specified database file.
      Parameters:
      databaseFile - String representation of the database file.
      options - database flags to use when opening the database GEOIP_STANDARD read database from disk GEOIP_MEMORY_CACHE cache the database in RAM and read it from RAM
      Throws:
      IOException - if an error occured creating the lookup service from the database file.

    • LookupService

      public LookupService(File databaseFile, int options) throws IOException
      Create a new lookup service using the specified database file.
      Parameters:
      databaseFile - the database file.
      options - database flags to use when opening the database GEOIP_STANDARD read database from disk GEOIP_MEMORY_CACHE cache the database in RAM and read it from RAM
      Throws:
      IOException - if an error occured creating the lookup service from the database file.

  • Method Details

    • init

      private void init() throws IOException
      Reads meta-data from the database file.
      Throws:
      IOException - if an error occurs reading from the database file.

    • close

      public void close()
      Closes the lookup service.

    • getAllCountryNames

      public List<String> getAllCountryNames()
      The country names the loaded database can resolve, as a copy of its internal name table.
      Returns:
      The list of all known country names

    • getAllCountryCodes

      public List<String> getAllCountryCodes()
      The ISO country codes the loaded database can resolve, as a copy of its internal code table.
      Returns:
      The list of all known country codes

    • getCountryV6

      public Country getCountryV6(String ipAddress)
      Returns the country the IP address is in.
      Parameters:
      ipAddress - String version of an IPv6 address, i.e. "::127.0.0.1"
      Returns:
      the country the IP address is from.

    • getCountry

      public Country getCountry(String ipAddress)
      Returns the country the IP address is in.
      Parameters:
      ipAddress - String version of an IP address, i.e. "127.0.0.1"
      Returns:
      the country the IP address is from.

    • getCountry

      public Country getCountry(InetAddress ipAddress)
      Returns the country the IP address is in.
      Parameters:
      ipAddress - the IP address.
      Returns:
      the country the IP address is from.

    • getCountryV6

      public Country getCountryV6(InetAddress addr)
      Returns the country the IP address is in.
      Parameters:
      addr - the IP address as Inet6Address.
      Returns:
      the country the IP address is from.

    • getCountry

      public Country getCountry(long ipAddress)
      Returns the country the IP address is in.
      Parameters:
      ipAddress - the IP address in long format.
      Returns:
      the country the IP address is from.

    • countryToIP

      public void countryToIP(String country, Writer out) throws IOException
      I2P - Write all IPv4 address ranges for the given country to out.
      Parameters:
      country - ISO two-letter code, matched case-insensitively
      out - caller must close
      Throws:
      IOException - if a range line cannot be written to out

    • getID

      public int getID(String ipAddress)
      Looks up the database record ID covering the given IP address.
      Parameters:
      ipAddress - the address to look up, as a name or a numeric literal
      Returns:
      the database ID for the given IP

    • getID

      public int getID(InetAddress ipAddress)
      Looks up the database record ID covering the given IP address.
      Parameters:
      ipAddress - the address to look up
      Returns:
      the database ID for the given IP

    • getID

      public int getID(long ipAddress)
      Looks up the database record ID covering the given IP address.
      Parameters:
      ipAddress - the IPv4 address in long format, most significant byte first
      Returns:
      the database ID for the given IP

    • last_netmask

      public int last_netmask()
      Returns the prefix length that the last search stopped at.
      Returns:
      the netmask from the last lookup

    • netmask

      public void netmask(int nm)
      Sets the prefix length that last_netmask() reports.
      Parameters:
      nm - the prefix length in bits, 0-32 for IPv4 or 0-128 for IPv6

    • getDatabaseInfo

      public DatabaseInfo getDatabaseInfo()
      Returns information about the database.
      Returns:
      the database edition and build epoch, or an empty DatabaseInfo if the file carries no trailing info block

    • _check_mtime

      void _check_mtime()
      Void

    • getLocationV6

      public Location getLocationV6(String str)
      Looks up the city record for an IPv6 address. Requires the GeoIP City database.
      Parameters:
      str - the address to look up, as a name or a numeric literal
      Returns:
      the location, or null if str names no address

    • getLocation

      public Location getLocation(InetAddress addr)
      Looks up the city record for an IPv4 address. Requires the GeoIP City database.
      Parameters:
      addr - the address to look up
      Returns:
      the location, or null if the database holds no city record for it

    • getLocation

      public Location getLocation(String str)
      Looks up the city record for an IPv4 address. Requires the GeoIP City database.
      Parameters:
      str - the address to look up, as a name or a numeric literal
      Returns:
      the location, or null if str names no address

    • getRegion

      public Region getRegion(String str)
      Looks up the region record for an IPv4 address.
      Parameters:
      str - the address to look up, as a name or a numeric literal
      Returns:
      the region, or null if str names no address

    • getRegion

      public Region getRegion(InetAddress addr)
      Looks up the region record for an IPv4 address.
      Parameters:
      addr - the address to look up
      Returns:
      the country code, country name and two-letter region code

    • getRegion

      public Region getRegion(long ipnum)
      Looks up the region record for an IPv4 address.
      Parameters:
      ipnum - the address in long format, most significant byte first
      Returns:
      the region, blank if the database is not a region edition

    • getLocationV6

      public Location getLocationV6(InetAddress addr)
      Looks up the city record for an IPv6 address.
      Parameters:
      addr - the address to look up
      Returns:
      the location, or null if the database holds no city record for it

    • getLocation

      public Location getLocation(long ipnum)
      Looks up the city record for an IPv4 address.
      Parameters:
      ipnum - the address in long format, most significant byte first
      Returns:
      the location, or null if the database holds no city record for it

    • readCityRecord

      private Location readCityRecord(int seekCountry) throws IOException
      Reads the city record for a country seek position.
      Parameters:
      seekCountry - the country record offset
      Returns:
      the location, or null if absent
      Throws:
      IOException - if the database read fails

    • readRecordBuf

      private ByteBuffer readRecordBuf(int seek, int maxLength) throws IOException
      Reads a record's bytes into a buffer.
      Parameters:
      seek - the offset to read from
      maxLength - the most bytes to read
      Returns:
      the record bytes
      Throws:
      IOException - if the database read fails

    • readString

      private String readString(ByteBuffer buffer) throws CharacterCodingException
      Reads a NUL-terminated string from the buffer.
      Parameters:
      buffer - the record buffer
      Returns:
      the decoded text
      Throws:
      CharacterCodingException - if the bytes are not decodable

    • readAngle

      private static float readAngle(ByteBuffer buffer)
      Reads a latitude or longitude value from the buffer.
      Parameters:
      buffer - the record buffer
      Returns:
      the angle in degrees

    • readMetroAreaCombo

      private static int readMetroAreaCombo(ByteBuffer buffer)
      Reads the combined metro area code from the buffer.
      Parameters:
      buffer - the record buffer
      Returns:
      the metro area code

    • getOrg

      public String getOrg(InetAddress addr)
      Looks up the owning organisation for an IPv4 address.
      Parameters:
      addr - the address to look up
      Returns:
      the organisation name, or null if the database holds no record for it

    • getOrg

      public String getOrg(String str)
      Looks up the owning organisation for an IPv4 address.
      Parameters:
      str - the address to look up, as a name or a numeric literal
      Returns:
      the organisation name, or null if str names no address

    • getOrg

      public String getOrg(long ipnum)
      Looks up the owning organisation for an IPv4 address.
      Parameters:
      ipnum - the address in long format, most significant byte first
      Returns:
      the organisation name, or null if the database holds no record for it

    • getOrgV6

      public String getOrgV6(String str)
      Looks up the owning organisation for an IPv6 address.
      Parameters:
      str - the address to look up, as a name or a numeric literal
      Returns:
      the organisation name, or null if str names no address

    • getOrgV6

      public String getOrgV6(InetAddress addr)
      Looks up the owning organisation for an IPv6 address.
      Parameters:
      addr - the address to look up
      Returns:
      the organisation name, or null if the database holds no record for it

    • readOrgRecord

      private String readOrgRecord(int seekOrg) throws IOException
      Reads the organization name for a seek position.
      Parameters:
      seekOrg - the record offset
      Returns:
      the organization name
      Throws:
      IOException - if the database read fails

    • seekCountryV6

      private int seekCountryV6(InetAddress addr)
      Finds the country index value given an IPv6 address.
      Parameters:
      addr - the ip address to find in long format.
      Returns:
      the country index.

    • seekCountry

      private int seekCountry(long ipAddress)
      Finds the country index value given an IP address.
      Parameters:
      ipAddress - the ip address to find in long format.
      Returns:
      the country index.

    • readNode

      private void readNode(byte[] buf, int[] x, int offset)
      Reads one node's two child offsets into x.
      Parameters:
      buf - the buffer holding the node
      x - where the child offsets are stored
      offset - the node offset in the database

    • bytesToLong

      private static long bytesToLong(byte[] address)
      Returns the long version of an IP address given an InetAddress object.
      Parameters:
      address - the InetAddress.
      Returns:
      the long form of the IP address.

    • unsignedByteToInt

      private static int unsignedByteToInt(byte b)
      Converts a byte to its unsigned value.
      Parameters:
      b - the byte
      Returns:
      the value from 0 to 255