Class GeoLocation

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()
  • GeoLocation.Status

• 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:

  • ZoneId.of(String)

• 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(boolean)

• 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