Java SDK

The Java SDK provides a robust and feature-rich way to integrate GeoIP lookups into your Java applications.

Installation

Maven

Add the dependency to your pom.xml:

<dependency>
    <groupId>org.geoipapi</groupId>
    <artifactId>geoip</artifactId>
    <version>0.0.1</version>
</dependency>

Gradle

Add the dependency to your build.gradle:

implementation 'org.geoipapi:geoip:0.0.1'

Quick Start

import org.openapis.openapi.GeoIp;
import org.openapis.openapi.models.operations.GetIpResponse;
import org.openapis.openapi.models.operations.GetIpDataResponse;

public class Example {
    public static void main(String[] args) {
        GeoIp client = GeoIp.builder()
            .serverURL("https://api.geoipapi.com")
            .build();
        
        try {
            // Get current IP address
            GetIpResponse ipResponse = client.geoIPEndpoints().getIp().call();
            if (ipResponse.res().isPresent()) {
                System.out.println("Current IP: " + ipResponse.res().get());
            }
            
            // Get detailed geolocation data
            GetIpDataResponse geoData = client.geoIPEndpoints().getIpData().call();
            if (geoData.responseGetJsonDataJsonGet().isPresent()) {
                var data = geoData.responseGetJsonDataJsonGet().get();
                System.out.println("Location data retrieved successfully!");
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Configuration

Configure the client with custom settings:

GeoIp client = GeoIp.builder()
    .serverURL("https://api.geoipapi.com")
    .build();

Available Methods

getIp()

Get your current public IP address:

GetIpResponse response = client.geoIPEndpoints().getIp().call();
if (response.res().isPresent()) {
    System.out.println("Current IP: " + response.res().get());
}

getIpData()

Get comprehensive geolocation data:

GetIpDataResponse response = client.geoIPEndpoints().getIpData().call();
if (response.responseGetJsonDataJsonGet().isPresent()) {
    var geoData = response.responseGetJsonDataJsonGet().get();
    System.out.println("Location data retrieved successfully!");
}

Response Model

The Java SDK uses strongly-typed response models. The exact structure depends on your API specification, but typically includes:

// Response structures are auto-generated based on your API specification
// Check the models/operations/ package for exact type definitions

Error Handling

Handle different types of errors:

import org.openapis.openapi.models.errors.HTTPValidationError;

try {
    GetIpDataResponse response = client.geoIPEndpoints().getIpData().call();
    // Handle successful response
} catch (HTTPValidationError e) {
    // Handle validation errors (422)
    System.err.println("Validation error: " + e.getMessage());
} catch (Exception e) {
    // Handle other API errors
    System.err.println("API error: " + e.getMessage());
}

Custom HTTP Client

Configure a custom HTTP client:

// Configure custom timeouts and settings
GeoIp client = GeoIp.builder()
    .serverURL("https://api.geoipapi.com")
    .build();

Thread Safety

The client is thread-safe and can be shared across multiple threads:

// Safe to use across multiple threads
private static final GeoIp CLIENT = GeoIp.builder()
    .serverURL("https://api.geoipapi.com")
    .build();

Building from Source

Clone and build the project:

git clone https://github.com/geoipapi/geo-ip-java.git
cd geo-ip-java

# Unix/Linux/macOS
./gradlew build

# Windows
gradlew.bat build