Class GeoLocation

java.lang.Object
co.mindus.ip2location.GeoLocation
public final class GeoLocation extends Object
Immutable result object containing geolocation data for an IP address lookup.

This class encapsulates all geographic information that can be determined from an IP address using the IP2Location database. The availability of each field depends on which Database variant is being used.

Status Handling

Always check isOk() before accessing location data:

GeoLocation loc = service.lookup("8.8.8.8");
if (loc.isOk()) {
    System.out.println("Country: " + loc.getCountryCode());
    System.out.println("City: " + loc.getCity());
    System.out.println("Location: " + loc.getLocationDescription());
} else {
    System.err.println("Lookup failed: " + loc.getStatus());
}

Status Values

The GeoLocation.Status enum provides type-safe status codes:

StatusMeaning
GeoLocation.Status.OKLookup successful, all fields populated
GeoLocation.Status.EMPTY_IPIP address was null or empty
GeoLocation.Status.INVALID_IPIP address format was invalid
GeoLocation.Status.NOT_FOUNDIP not found in database
GeoLocation.Status.DB_NOT_LOADEDNo database loaded
GeoLocation.Status.IPV6_NOT_SUPPORTEDIPv6 lookup but no IPv6 DB
GeoLocation.Status.DB_ERRORI/O error during lookup
GeoLocation.Status.SERVICE_DISABLEDService is disabled
GeoLocation.Status.SERVICE_DISPOSEDService has been disposed
GeoLocation.Status.SERVICE_SHUTDOWNManager has been shut down
GeoLocation.Status.SERVICE_NOT_CONFIGUREDManager not configured
GeoLocation.Status.SERVICE_RECONFIGURINGService is reconfiguring

Field Availability by Database Type

FieldDB1DB3DB5DB9DB11
Country code/name✓✓✓✓✓
Region✓✓✓✓
City✓✓✓✓
Latitude/Longitude✓✓✓
ZIP Code✓✓
Timezone✓

Location Description

Use getLocationDescription() or getLocationDescription(boolean) to get a human-readable string of all defined location fields:

GeoLocation loc = service.lookup("8.8.8.8");
if (loc.isOk()) {
    // Without coordinates
    String desc = loc.getLocationDescription();
    // "Mountain View, California, United States of America, 94043, America/Los_Angeles"
    
    // With coordinates
    String descWithCoords = loc.getLocationDescription(true);
    // "Mountain View, California, United States of America, 94043, America/Los_Angeles, 37.4056°N, 122.0775°W"
}

Thread Safety

This class is immutable and therefore inherently thread-safe. Instances can be safely shared between threads without synchronization.

Creating Instances

Use the GeoLocation.Builder for programmatic creation:

GeoLocation loc = GeoLocation.builder()
    .ip("8.8.8.8")
    .status(GeoLocation.Status.OK)
    .countryCode("US")
    .countryName("United States of America")
    .city("Mountain View")
    .latitude(37.4056)
    .longitude(-122.0775)
    .build();
Author:
Christopher Mindus
See Also:

  • Method Details

    • getIp

      public String getIp()
      Returns the IP address that was looked up.
      Returns:
      The IP address string as provided to the lookup method

    • getStatus

      public GeoLocation.Status getStatus()
      Returns the status of the lookup operation.
      Returns:
      The status enum value
      See Also:

    • isOk

      public boolean isOk()
      Returns whether the lookup was successful.

      This is equivalent to checking if getStatus() == Status.OK.

      Returns:
      true if the lookup succeeded and location data is available

    • isIPv6

      public boolean isIPv6()
      Returns whether the looked-up IP address was an IPv6 address.
      Returns:
      true if the IP was IPv6, false if IPv4

    • getCountryCode

      public String getCountryCode()
      Returns the ISO 3166-1 alpha-2 country code.

      Available in all database types (DB1+).

      Returns:
      Two-letter country code (e.g., "US", "DE", "JP"), or null/"-" if unavailable

    • getCountryName

      public String getCountryName()
      Returns the full country name.

      Available in all database types (DB1+).

      Returns:
      Country name (e.g., "United States of America"), or null/"-" if unavailable

    • getRegion

      public String getRegion()
      Returns the region or state name.

      Requires DB3 or higher. Returns null or "-" if unavailable.

      Returns:
      Region/state name (e.g., "California"), or null/"-" if unavailable

    • getCity

      public String getCity()
      Returns the city name.

      Requires DB3 or higher. Returns null or "-" if unavailable.

      Returns:
      City name (e.g., "Mountain View"), or null/"-" if unavailable

    • getLatitude

      public double getLatitude()
      Returns the latitude in decimal degrees.

      Requires DB5 or higher. Returns 0.0 if unavailable.

      Note: For reserved/private IP ranges, coordinates may be 0.0 or point to a country's geographic center.

      Returns:
      Latitude in range -90.0 (South Pole) to 90.0 (North Pole)

    • getLongitude

      public double getLongitude()
      Returns the longitude in decimal degrees.

      Requires DB5 or higher. Returns 0.0 if unavailable.

      Returns:
      Longitude in range -180.0 (West) to 180.0 (East)

    • getZipCode

      public String getZipCode()
      Returns the ZIP or postal code.

      Requires DB9 or higher. Returns null or "-" if unavailable.

      Note: Format varies by country (e.g., "94043" for US, "80331" for Germany).

      Returns:
      ZIP/postal code string, or null/"-" if unavailable

    • getTimeZone

      public String getTimeZone()
      Returns the timezone in IANA tz database format.

      Requires DB11. Returns null or "-" if unavailable.

      The returned value can be used with ZoneId.of(String):

      if (loc.getTimeZone() != null && !"-".equals(loc.getTimeZone())) {
    ZoneId zone = ZoneId.of(loc.getTimeZone());
    ZonedDateTime localTime = ZonedDateTime.now(zone);
}
      Returns:
      Timezone string (e.g., "America/Los_Angeles", "Europe/Berlin"), or null/"-"
      See Also:

    • getLocationDescription

      public String getLocationDescription()
      Returns a human-readable description of the location.

      Equivalent to getLocationDescription(false).

      Returns:
      A comma-separated string of location fields, or empty string if no data
      See Also:

    • getLocationDescription

      public String getLocationDescription(boolean includeCoordinates)
      Returns a human-readable description of the location.

      This method returns only the fields that have defined values (not null, not empty, not "-"), concatenated in order of importance with ", " as separator.

      Field order (most important first):

      1. City
      2. Region/State
      3. Country name (or country code if name is not available)
      4. ZIP/Postal code
      5. Timezone
      6. Coordinates (if includeCoordinates is true and both lat/long are non-zero)

      Example outputs:

      • "Mountain View, California, United States of America, 94043, America/Los_Angeles"
      • "Munich, Bavaria, Germany"
      • "Tokyo, Japan, Asia/Tokyo, 35.6895°N, 139.6917°E" (with coordinates)
      • "US" (if only country code is available)
      • "" (empty string if lookup failed or no data)
      Parameters:
      includeCoordinates - true to include latitude/longitude if available
      Returns:
      A comma-separated string of location fields, or empty string if no data

    • toString

      public String toString()
      Returns a string representation of this geolocation result.

      For successful lookups, includes IP, city, region, and country. For failed lookups, includes IP and status.

      Overrides:
      toString in class Object
      Returns:
      Human-readable string representation

    • equals

      public boolean equals(Object o)
      Compares this GeoLocation with another object for equality.

      Two GeoLocation objects are equal if all their fields are equal.

      Overrides:
      equals in class Object
      Parameters:
      o - The object to compare with
      Returns:
      true if the objects are equal

    • hashCode

      public int hashCode()
      Returns a hash code for this GeoLocation.
      Overrides:
      hashCode in class Object
      Returns:
      Hash code based on key fields

    • error

      public static GeoLocation error(String ip, GeoLocation.Status status)
      Creates an error result with the specified status.
      Parameters:
      ip - The IP address that was looked up (may be null)
      status - The error status
      Returns:
      A GeoLocation with the error status and no location data

    • builder

      public static GeoLocation.Builder builder()
      Creates a new builder for constructing GeoLocation instances.
      Returns:
      A new Builder instance