IPGeolocation Kotlin SDK

Overview

Official Kotlin SDK for the IPGeolocation.io IP Location API.

Look up IPv4, IPv6, and domains with /v3/ipgeo and /v3/ipgeo-bulk . Get geolocation, company, ASN, timezone, network, hostname, abuse, user-agent, currency, and security data from one API.

• Kotlin/JVM SDK targeting Java 8+
• Typed JSON responses plus raw JSON and XML methods
• Built on the JDK HTTP stack

Install

Maven:

<dependency>
  <groupId>io.ipgeolocation</groupId>
  <artifactId>ipgeolocation-kotlin-sdk</artifactId>
  <version>1.0.0</version>
</dependency>

Gradle Kotlin DSL:

implementation("io.ipgeolocation:ipgeolocation-kotlin-sdk:1.0.0")

Gradle Groovy:

implementation 'io.ipgeolocation:ipgeolocation-kotlin-sdk:1.0.0'

• Maven Central coordinates: io.ipgeolocation:ipgeolocation-kotlin-sdk
• Package page: https://central.sonatype.com/artifact/io.ipgeolocation/ipgeolocation-kotlin-sdk
• GitHub repository: https://github.com/IPGeolocation/ip-geolocation-api-kotlin-sdk

All public types live under the io.ipgeolocation.sdk package. Your IDE will auto-import the classes used in the examples below.

git clone https://github.com/IPGeolocation/ip-geolocation-api-kotlin-sdk.git
cd ip-geolocation-api-kotlin-sdk
mvn install

Quick Start

import io.ipgeolocation.sdk.IpGeolocationClient
import io.ipgeolocation.sdk.IpGeolocationClientConfig
import io.ipgeolocation.sdk.LookupIpGeolocationRequest

fun main() {
    val apiKey = System.getenv("IPGEO_API_KEY")
        ?: error("set IPGEO_API_KEY first")

    IpGeolocationClient(
        IpGeolocationClientConfig(apiKey = apiKey),
    ).use { client ->
        val response = client.lookupIpGeolocation(
            LookupIpGeolocationRequest(ip = "8.8.8.8"),
        )

        println(response.data.ip) // 8.8.8.8
        println(response.data.location?.countryName) // United States
        println(response.data.location?.city)
        println(response.data.timeZone?.name)
        println(response.metadata.creditsCharged)
    }
}

You can also call lookupIpGeolocation() with no request object to resolve the caller IP.

At a Glance

Get Your API Key

Create an IPGeolocation account and copy an API key from your dashboard.

1. Sign up: https://app.ipgeolocation.io/signup
2. Verify your email if prompted
3. Sign in: https://app.ipgeolocation.io/login
4. Open your dashboard: https://app.ipgeolocation.io/dashboard
5. Copy an API key from the API Keys section

For server-side Kotlin code, keep the API key in an environment variable or secret manager. For browser-based single lookups on paid plans, use request-origin auth instead of exposing an API key in frontend code.

Plan Behavior

Feature availability depends on your plan and request parameters.

Paid plans still need include for optional modules. fields and excludes only trim the response. They do not turn modules on or unlock paid data.

Client Configuration

Config values are validated when the client is created. Request values are validated before each request is sent.

Available Methods

Request Options

Examples

The examples below assume you already have a configured client in scope:

val client = IpGeolocationClient(
    IpGeolocationClientConfig(
        apiKey = System.getenv("IPGEO_API_KEY"),
    ),
)

val response = client.lookupIpGeolocation()

println(response.data.ip)

val response = client.lookupIpGeolocation(
    LookupIpGeolocationRequest(
        ip = "ipgeolocation.io",
    ),
)

println(response.data.ip)
println(response.data.domain) // ipgeolocation.io
println(response.data.location?.countryName)

val response = client.lookupIpGeolocation(
    LookupIpGeolocationRequest(
        ip = "9.9.9.9",
        include = listOf("security", "abuse"),
    ),
)

println(response.data.security?.threatScore)
println(response.data.abuse?.emails?.firstOrNull())

val visitorUserAgent =
    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_2) AppleWebKit/601.3.9 (KHTML, like Gecko) Version/9.0.2 Safari/601.3.9"

val response = client.lookupIpGeolocation(
    LookupIpGeolocationRequest(
        ip = "115.240.90.163",
        include = listOf("user_agent"),
        headers = mapOf("User-Agent" to visitorUserAgent),
    ),
)

println(response.data.userAgent?.name)
println(response.data.userAgent?.operatingSystem?.name)

val response = client.lookupIpGeolocation(
    LookupIpGeolocationRequest(
        ip = "8.8.8.8",
        include = listOf("security"),
        fields = listOf(
            "location.country_name",
            "security.threat_score",
            "security.is_vpn",
        ),
        excludes = listOf("currency"),
    ),
)

println(response.data.location?.countryName)
println(response.data.security?.isVpn)
println(response.data.currency == null)

val response = client.lookupIpGeolocationRaw(
    LookupIpGeolocationRequest(
        ip = "8.8.8.8",
        output = ResponseFormat.XML,
    ),
)

println(response.data)

val response = client.bulkLookupIpGeolocation(
    BulkLookupIpGeolocationRequest(
        ips = listOf("8.8.8.8", "1.1.1.1"),
    ),
)

for (result in response.data) {
    if (result.isSuccess()) {
        println(result.data?.ip)
    } else {
        println(result.error?.message)
    }
}

val response = client.bulkLookupIpGeolocationRaw(
    BulkLookupIpGeolocationRequest(
        ips = listOf("8.8.8.8", "1.1.1.1"),
    ),
)

println(response.data)

Response Metadata

Every method returns ApiResponse<T> , where:

• data contains the typed object or raw response string
• metadata contains response details such as:
  • creditsCharged
  • successfulRecords
  • statusCode
  • durationMs
  • rawHeaders

Example:

println(response.metadata.statusCode)
println(response.metadata.durationMs)
println(response.metadata.firstHeaderValue("content-type"))

JSON Helpers

Use JsonOutput for logs, debugging, or CLI output.

Example:

val compact = JsonOutput.toPrettyJson(response.data)
val full = JsonOutput.toPrettyJson(response.data, JsonOutputMode.FULL)

println(compact)
println(full)

Errors

The SDK throws typed exceptions instead of leaving you to parse error bodies yourself.

ApiException has status-specific subclasses:

• BadRequestException
• UnauthorizedException
• NotFoundException
• MethodNotAllowedException
• PayloadTooLargeException
• UnsupportedMediaTypeException
• LockedException
• RateLimitException
• ClientClosedRequestException
• ServerErrorException

ApiException also exposes:

• statusCode
• apiMessage

Example:

try {
    client.lookupIpGeolocation(
        LookupIpGeolocationRequest(output = ResponseFormat.XML),
    )
} catch (error: ValidationException) {
    println(error.message)
}

Troubleshooting

• Bulk lookup always requires apiKey . requestOrigin is not enough.
• Typed methods only support JSON. Use the raw methods for XML.
• If you need security, abuse, user-agent, or hostname data, include those modules explicitly.
• fields and excludes filter the response. They do not unlock paid data.
• requestOrigin must be an origin only. Do not include a path, query string, fragment, or userinfo.
• Response fields are nullable so omitted fields stay omitted.
• connectTimeout must be less than or equal to readTimeout .
• The SDK rejects responses larger than maxResponseBodyChars . The default cap is 32 MiB .
• If Maven prints sun.misc.Unsafe warnings from kotlin-compiler during local builds, run Maven with JDK 21 LTS. That warning is from the current Kotlin compiler toolchain, not from the SDK runtime.

Frequently Asked Questions

Links

• Homepage: https://ipgeolocation.io
• IP Location API product page: https://ipgeolocation.io/ip-location-api.html
• Documentation: https://ipgeolocation.io/documentation/ip-location-api.html
• GitHub repository: https://github.com/IPGeolocation/ip-geolocation-api-kotlin-sdk