GeoLocation (NetPhantom® 8.0 Java API Specification)

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:

Status	Meaning
`GeoLocation.Status.OK`	Lookup successful, all fields populated
`GeoLocation.Status.EMPTY_IP`	IP address was null or empty
`GeoLocation.Status.INVALID_IP`	IP address format was invalid
`GeoLocation.Status.NOT_FOUND`	IP not found in database
`GeoLocation.Status.DB_NOT_LOADED`	No database loaded
`GeoLocation.Status.IPV6_NOT_SUPPORTED`	IPv6 lookup but no IPv6 DB
`GeoLocation.Status.DB_ERROR`	I/O error during lookup
`GeoLocation.Status.SERVICE_DISABLED`	Service is disabled
`GeoLocation.Status.SERVICE_DISPOSED`	Service has been disposed
`GeoLocation.Status.SERVICE_SHUTDOWN`	Manager has been shut down
`GeoLocation.Status.SERVICE_NOT_CONFIGURED`	Manager not configured
`GeoLocation.Status.SERVICE_RECONFIGURING`	Service is reconfiguring

Field Availability by Database Type

Field	DB1	DB3	DB5	DB9	DB11
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:: IP2LocationService.lookup(String), IP2LocationManager.lookup(String), Database, GeoLocation.Status

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`GeoLocation.Builder` Builder for creating `GeoLocation` instances.
`static class`	`GeoLocation.Status` Enumeration of possible lookup result statuses.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static GeoLocation.Builder`	`builder()` Creates a new builder for constructing GeoLocation instances.
`boolean`	`equals(Object o)` Compares this GeoLocation with another object for equality.
`static GeoLocation`	`error(String ip, GeoLocation.Status status)` Creates an error result with the specified status.
`String`	`getCity()` Returns the city name.
`String`	`getCountryCode()` Returns the ISO 3166-1 alpha-2 country code.
`String`	`getCountryName()` Returns the full country name.
`String`	`getIp()` Returns the IP address that was looked up.
`double`	`getLatitude()` Returns the latitude in decimal degrees.
`String`	`getLocationDescription()` Returns a human-readable description of the location.
`String`	`getLocationDescription(boolean includeCoordinates)` Returns a human-readable description of the location.
`double`	`getLongitude()` Returns the longitude in decimal degrees.
`String`	`getRegion()` Returns the region or state name.
`GeoLocation.Status`	`getStatus()` Returns the status of the lookup operation.
`String`	`getTimeZone()` Returns the timezone in IANA tz database format.
`String`	`getZipCode()` Returns the ZIP or postal code.
`int`	`hashCode()` Returns a hash code for this GeoLocation.
`boolean`	`isIPv6()` Returns whether the looked-up IP address was an IPv6 address.
`boolean`	`isOk()` Returns whether the lookup was successful.
`String`	`toString()` Returns a string representation of this geolocation result.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Method Detail
  - 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

Class GeoLocation

Status Handling

Status Values

Field Availability by Database Type

Location Description

Thread Safety

Creating Instances

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Detail

getIp

getStatus

isOk

isIPv6

getCountryCode

getCountryName

getRegion

getCity

getLatitude

getLongitude

getZipCode

getTimeZone

getLocationDescription

getLocationDescription

Example outputs:

toString

equals

hashCode

error

builder