ipgeolocation-java-sdk

Ipgeolocation provides a set of APIs to make IP based decisions.

Installation Requirements

Java: 1.8 or higher
Build Tools: Maven 3.8.3+ or Gradle 7.2+

Using Maven

Add the following dependency to your pom.xml file:

xml

<dependency>
  <groupId>io.ipgeolocation</groupId>
  <artifactId>ipgeolocation</artifactId>
  <version>2.0.0</version>
</dependency>

Using Gradle

Add this to your build.gradle file:

groovy

repositories {
    mavenCentral()
    mavenLocal() // Only needed if using locally built version
}
dependencies {
    implementation "io.ipgeolocation:ipgeolocation:2.0.0"
}

Manual Installation

To build the SDK manually:

bash

mvn clean package

Then include the following JARs in your classpath:

target/ipgeolocation-sdk-java-2.0.0.jar
All JARs in target/lib/

Authentication Setup

To authenticate API requests, you need an API key from ipgeolocation.io. Once obtained, configure your API client as follows:

java

import invoker.io.ipgeolocation.sdk.ApiClient;
import invoker.io.ipgeolocation.sdk.Configuration;
import auth.invoker.io.ipgeolocation.sdk.ApiKeyAuth;

ApiClient client = Configuration.getDefaultApiClient();
client.setBasePath("https://api.ipgeolocation.io/v2");

ApiKeyAuth apiKeyAuth = (ApiKeyAuth) client.getAuthentication("ApiKeyAuth");
apiKeyAuth.setApiKey("YOUR_API_KEY_HERE");

Ensure that your API key is securely stored and not exposed in public repositories.

IP Geolocation Examples

1 - Basic Plan Examples

The default response returns the main location and currency fields.

Default Fields

java

import io.ipgeolocation.sdk.api.IPGeolocationAPI;
import io.ipgeolocation.sdk.model.GeolocationResponse;

IPGeolocationAPI api = new IPGeolocationAPI(client);
GeolocationResponse response = api.getIPGeolocation()
        .ip("8.8.8.8")
        .execute();

System.out.println(response);

Sample Response:

java

class GeolocationResponse {
    ip: 8.8.8.8
    location: class Location {
        continentCode: NA
        continentName: North America
        countryCode2: US
        countryCode3: USA
        countryName: United States
        countryNameOfficial: United States of America
        countryCapital: Washington, D.C.
        stateProv: California
        stateCode: US-CA
        district: Santa Clara
        city: Mountain View
        zipcode: 94043-1351
        latitude: 37.42240
        longitude: -122.08421
        isEu: false
        countryFlag: https://ipgeolocation.io/static/flags/us_64.png
        geonameId: 6301403
        countryEmoji: 🇺🇸
    }
    countryMetadata: class CountryMetadata {
        callingCode: +1
        tld: .us
        languages: [en-US, es-US, haw, fr]
    }
    currency: class Currency {
        code: USD
        name: US Dollar
        symbol: $
    }
}

You can filter fields with the 'fields' and 'excludes' parameters:

"Filtering Specific Fields from the Response (Use of 'exclude' and 'fields')"

'fields' and 'excludes' params

java

GeolocationResponse response = api.getIPGeolocation()
    .ip("8.8.4.4")
    .fields("location")
    .excludes("location.continent_code,location.continent_name")
    .execute();

System.out.println(response);

Sample Response:

java

class GeolocationResponse {
    ip: 8.8.4.4
    location: class Location {
        countryCode2: US
        countryCode3: USA
        countryName: United States
        countryNameOfficial: United States of America
        countryCapital: Washington, D.C.
        stateProv: California
        stateCode: US-CA
        district: Santa Clara
        city: Mountain View
        zipcode: 94043-1351
        latitude: 37.42240
        longitude: -122.08421
        isEu: false
        countryFlag: https://ipgeolocation.io/static/flags/us_64.png
        geonameId: 6301403
        countryEmoji: 🇺🇸
    }
}

2 - Standard Plan Examples

Default Fields

java

import io.ipgeolocation.sdk.api.IPGeolocationAPI;
import io.ipgeolocation.sdk.model.GeolocationResponse;

IPGeolocationAPI api = new IPGeolocationAPI(client);
GeolocationResponse response = api.getIPGeolocation()
        .ip("8.8.8.8")
        .execute();

System.out.println(response);

Sample Response:

java

class GeolocationResponse {
    ip: 8.8.8.8
    location: class Location {
        continentCode: NA
        continentName: North America
        countryCode2: US
        countryCode3: USA
        countryName: United States
        countryNameOfficial: United States of America
        countryCapital: Washington, D.C.
        stateProv: California
        stateCode: US-CA
        district: Santa Clara
        city: Mountain View
        zipcode: 94043-1351
        latitude: 37.42240
        longitude: -122.08421
        isEu: false
        countryFlag: https://ipgeolocation.io/static/flags/us_64.png
        geonameId: 6301403
        countryEmoji: 🇺🇸
    }
    countryMetadata: class CountryMetadata {
        callingCode: +1
        tld: .us
        languages: [en-US, es-US, haw, fr]
    }
    network: class Network {
        asn: class NetworkAsn {
            asNumber: AS15169
            organization: Google LLC
            country: US
        }
        company: class NetworkCompany {
            name: Google LLC
        }
    }
    currency: class Currency {
        code: USD
        name: US Dollar
        symbol: $
    }
}

"Here is an example to get the geolocation data for IP address '2001:4230:4890::1' in French language:"

Retrieving Geolocation Data in Multiple Languages

java

IPGeolocationAPI api = new IPGeolocationAPI(client);
GeolocationResponse response = api.getIPGeolocation()
        .ip("2001:4230:4890::1")
        .lang("fr")
        .execute();

System.out.println(response);

Sample Response:

java

class GeolocationResponse {
    ip: 2001:4230:4890:0:0:0:0:1
    location: class Location {
        continentCode: AF
        continentName: Afrique
        countryCode2: MU
        countryCode3: MUS
        countryName: Maurice
        countryNameOfficial: 
        countryCapital: Port Louis
        stateProv: Wilhems des plaines
        stateCode: MU-PW
        district: Quatre Bornes
        city: Quatre Bornes
        zipcode: 72201
        latitude: -20.24304
        longitude: 57.49631
        isEu: false
        countryFlag: https://ipgeolocation.io/static/flags/mu_64.png
        geonameId: 1106777
        countryEmoji: 🇲🇺
    }
    countryMetadata: class CountryMetadata {
        callingCode: +230
        tld: .mu
        languages: [en-MU, bho, fr]
    }
    network: class Network {
        asn: class NetworkAsn {
            asNumber: AS0
            organization: 
            country:
        }
        company: class NetworkCompany {
            name: African Network Information Center AfriNIC Ltd
        }
    }
    currency: class Currency {
        code: MUR
        name: Mauritius Rupee
        symbol: ₨
    }
}

Include HostName, Timezone and User-Agent

java

IPGeolocationAPI api = new IPGeolocationAPI(client);
GeolocationResponse response = api.getIPGeolocation()
        .ip("4.5.6.7")
        .fields("location.country_name,location.country_capital")
        .include("user_agent, time_zone, hostnameFallbackLive")
        .execute();

System.out.println(response);

Sample Response:

java

class GeolocationResponse {
    ip: 4.5.6.7
    hostname: 4.5.6.7
    location: class Location {
        countryName: United States
        countryCapital: Washington, D.C.
    }
    timeZone: class TimeZone {
        name: America/Chicago
        offset: -6
        offsetWithDst: -5
        currentTime: 2025-05-28 06:52:16.748-0500
        currentTimeUnix: 1748433136.748
        isDst: true
        dstSavings: 1
        dstExists: true
        dstStart: class TimeZoneDstStart {
            utcTime: 2025-03-09 TIME 08
            duration: +1H
            gap: true
            dateTimeAfter: 2025-03-09 TIME 03
            dateTimeBefore: 2025-03-09 TIME 02
            overlap: false
        }
        dstEnd: class TimeZoneDstEnd {
            utcTime: 2025-11-02 TIME 07
            duration: -1H
            gap: false
            dateTimeAfter: 2025-11-02 TIME 01
            dateTimeBefore: 2025-11-02 TIME 02
            overlap: true
        }
    }
    userAgent: class UserAgentData {
        userAgentString: OpenAPI-Generator/1.0.0/java
        name: OpenAPI-Generator
        type: Special
        version: 1.0.0
        versionMajor: 1
        device: class UserAgentDataDevice {
            name: Unknown
            type: Unknown
            brand: Unknown
            cpu: Unknown
        }
        engine: class UserAgentDataEngine {
            name: Unknown
            type: Unknown
            version: ??
            versionMajor: ??
        }
        operatingSystem: class UserAgentDataOperatingSystem {
            name: Unknown
            type: Unknown
            version: ??
            versionMajor: ??
            build: ??
        }
    }
}

The IP Geolocation API supports hostname lookup for all paid subscriptions. However, this is not included by default. To enable hostname resolution, use the include parameter with one of the following options:

hostname: Performs a quick lookup using the internal hostname database. If no match is found, the IP is returned as-is. This is fast but may produce incomplete results.
liveHostname: Queries live sources for accurate hostname resolution. This may increase response time.
hostnameFallbackLive: Attempts the internal database first, and falls back to live sources if no result is found. This option provides a balance of speed and reliability.

3 - Advanced Plan Examples

These examples demonstrate typical usage of the IP Geolocation API with different subscription tiers. Use fields to specify exactly which data to receive, include for optional data like security and user agent, and excludes to omit specific keys from the response.

Include DMA, Abuse and Security

java

import io.ipgeolocation.sdk.api.IPGeolocationAPI;
import io.ipgeolocation.sdk.model.GeolocationResponse;

IPGeolocationAPI api = new IPGeolocationAPI(client);
GeolocationResponse response = api.getIPGeolocation()
        .ip("8.8.8.8")
        .excludes("location.country_flag,location.country_emoji")
        .include("dma,abuse,security")
        .execute();

System.out.println(response);

Sample Response:

java

class GeolocationResponse {
    ip: 8.8.8.8
    location: class Location {
        continentCode: NA
        continentName: North America
        countryCode2: US
        countryCode3: USA
        countryName: United States
        countryNameOfficial: United States of America
        countryCapital: Washington, D.C.
        stateProv: California
        stateCode: US-CA
        district: Santa Clara
        city: Mountain View
        zipcode: 94043-1351
        latitude: 37.42240
        longitude: -122.08421
        isEu: false
        countryFlag: null
        geonameId: 6301403
        countryEmoji: null
        accuracyRadius: 
        locality: Mountain View
        dmaCode: 807
    }
    countryMetadata: class CountryMetadata {
        callingCode: +1
        tld: .us
        languages: [en-US, es-US, haw, fr]
    }
    network: class Network {
        asn: class NetworkAsn {
            asNumber: AS15169
            organization: Google LLC
            country: US
            asnName: GOOGLE
            type: BUSINESS
            domain: about.google
            dateAllocated: 
            allocationStatus: assigned
            numOfIpv4Routes: 965
            numOfIpv6Routes: 104
            rir: ARIN
        }
        connectionType: 
        company: class NetworkCompany {
            name: Google LLC
            type: Business
            domain: googlellc.com
        }
    }
    currency: class Currency {
        code: USD
        name: US Dollar
        symbol: $
    }
    security: class Security {
        threatScore: 0
        isTor: false
        isProxy: false
        proxyType: 
        proxyProvider: 
        isAnonymous: false
        isKnownAttacker: false
        isSpam: false
        isBot: false
        isCloudProvider: false
        cloudProvider: 
    }
    abuse: class Abuse {
        route: 8.8.8.0/24
        country: 
        handle: ABUSE5250-ARIN
        name: Abuse
        organization: Abuse
        role: abuse
        kind: group
        address: 1600 Amphitheatre Parkway
        Mountain View
        CA
        94043
        United States
        emails: [network-abuse@google.com]
        phoneNumbers: [+1-650-253-0000]
    }
}

All features available in the Free plan are also included in the Standard and Advanced plans. Similarly, all features of the Standard plan are available in the Advanced plan.

Bulk IP Geolocation Example

The SDK also supports bulk IP geolocation requests using the getBulkIpGeolocation() method. All parameters like fields, include, and excludes can also be used in bulk requests."

Retrieving Geolocation Data in Multiple Languages

java


import io.ipgeolocation.sdk.model.BulkIPRequest;
import io.ipgeolocation.sdk.api.IPGeolocationAPI;
import io.ipgeolocation.sdk.model.BulkGeolocationResponse;

IPGeolocationAPI api = new IPGeolocationAPI(client);

BulkIPRequest bulkRequest = new BulkIPRequest();
bulkRequest.addIp("8.8.8.8");
bulkRequest.addIp("1.1.1.1");

List<BulkGeolocationResponse> response = api.getBulkIPGeolocation()
        .bulkIpRequest(bulkRequest)
        .fields("location.country_name,location.city")
        .include("security,timezone")
        .excludes("location.continent_code")
        .execute();

System.out.println(response);

IP Security Examples

This section provides usage examples of the getIPSecurity() method from the SDK across various subscription tiers. Each example demonstrates different ways to query threat intelligence and risk metadata using parameters like fields, excludes, and optional modules. For full API specifications, refer to the official IP Security API documentation.

Basic Request (Minimal Setup)

java

import io.ipgeolocation.sdk.api.IPSecurityAPI;
import io.ipgeolocation.sdk.model.SecurityAPIResponse;

IPSecurityAPI api = new IPSecurityAPI(client);
SecurityAPIResponse response = api.getIPSecurity()
        .ip("2.56.188.34")
        .execute();

System.out.println(response);

Sample Response:

java

class SecurityAPIResponse {
    ip: 2.56.188.34
    security: class Security {
        threatScore: 80
        isTor: false
        isProxy: true
        proxyType: VPN
        proxyProvider: Nord VPN
        isAnonymous: true
        isKnownAttacker: true
        isSpam: false
        isBot: false
        isCloudProvider: true
        cloudProvider: Packethub S.A.
    }
}

Include Multiple Optional Fields

java

SecurityAPIResponse response = api.getIPSecurity()
    .ip("2.56.188.34")
    .include("location,network,currency,time_zone,user_agent,country_metadata,hostname")
    .execute();

Sample Response:

java

class SecurityAPIResponse {
    ip: 2.56.188.34
    hostname: 2.56.188.34
    security: class Security {
        threatScore: 80
        isTor: false
        isProxy: true
        proxyType: VPN
        proxyProvider: Nord VPN
        isAnonymous: true
        isKnownAttacker: true
        isSpam: false
        isBot: false
        isCloudProvider: true
        cloudProvider: Packethub S.A.
    }
    location: class LocationMinimal {
        continentCode: NA
        continentName: North America
        countryCode2: US
        countryCode3: USA
        countryName: United States
        countryNameOfficial: United States of America
        countryCapital: Washington, D.C.
        stateProv: Texas
        stateCode: US-TX
        district: Dallas County
        city: Dallas
        zipcode: 75207
        latitude: 32.78916
        longitude: -96.82170
        isEu: false
        countryFlag: https://ipgeolocation.io/static/flags/us_64.png
        geonameId: 7181768
        countryEmoji: 🇺🇸
    }
    network: class NetworkMinimal {
        asn: class NetworkMinimalAsn {
            asNumber: AS62240
            organization: Clouvider Limited
            country: GB
        }
        company: class NetworkMinimalCompany {
            name: Packethub S.A.
        }
    }
    timeZone: class TimeZone {
        name: America/Chicago
        offset: -6
        offsetWithDst: -5
        currentTime: 2025-05-29 08:27:44.939-0500
        currentTimeUnix: 1748525264.939
        isDst: true
        dstSavings: 1
        dstExists: true
        dstStart: class TimeZoneDstStart {
            utcTime: 2025-03-09 TIME 08
            duration: +1H
            gap: true
            dateTimeAfter: 2025-03-09 TIME 03
            dateTimeBefore: 2025-03-09 TIME 02
            overlap: false
        }
        dstEnd: class TimeZoneDstEnd {
            utcTime: 2025-11-02 TIME 07
            duration: -1H
            gap: false
            dateTimeAfter: 2025-11-02 TIME 01
            dateTimeBefore: 2025-11-02 TIME 02
            overlap: true
        }
    }
    userAgent: class UserAgentData {
        userAgentString: OpenAPI-Generator/1.0.0/java
        name: OpenAPI-Generator
        type: Special
        version: 1.0.0
        versionMajor: 1
        device: class UserAgentDataDevice {
            name: Unknown
            type: Unknown
            brand: Unknown
            cpu: Unknown
        }
        engine: class UserAgentDataEngine {
            name: Unknown
            type: Unknown
            version: ??
            versionMajor: ??
        }
        operatingSystem: class UserAgentDataOperatingSystem {
            name: Unknown
            type: Unknown
            version: ??
            versionMajor: ??
            build: ??
        }
    }
    countryMetadata: class CountryMetadata {
        callingCode: +1
        tld: .us
        languages: [en-US, es-US, haw, fr]
    }
    currency: class Currency {
        code: USD
        name: US Dollar
        symbol: $
    }
}

Request with Field Filtering

java

SecurityAPIResponse response = api.getIPSecurity()
        .ip("195.154.221.54")
        .fields("is_tor,is_proxy,is_bot,is_spam")
        .execute();

System.out.println(response);

Sample Response:

java

class SecurityAPIResponse {
    ip: 195.154.221.54
    security: class Security {
        isTor: false
        isProxy: true
        isSpam: false
        isBot: false
    }
}

Bulk IP Security Request

The SDK also supports bulk IP Security requests using the getBulkIPSecurity() method. All parameters like fields, include, and excludes can also be used in bulk requests.

Retrieving Geolocation Data in Multiple Languages

java

import io.ipgeolocation.sdk.model.BulkSecurityResponse;
import io.ipgeolocation.sdk.model.BulkIPRequest;

BulkIPRequest bulkRequest = new BulkIPRequest();
bulkRequest.addIp("2.56.188.34");
bulkRequest.addIp("2.56.188.35");

List<BulkSecurityResponse> response = api.getBulkIPSecurity(bulkIPRequest)
        .include("location,network")
        .fields("security.threat_score,location.country_name")
        .execute();

System.out.println(response);

ASN API Examples

This section provides usage examples of the getAsnDetails() method from the SDK. These methods allow developers to retrieve detailed ASN-level network data either by ASN number or by IP address. Note that ASN API is only available in the Advanced subscription plans." + Refer to the ASN API documentation for a detailed list of supported fields and behaviors.

Get ASN Information by IP Address

java

import io.ipgeolocation.sdk.api.AsnLookupAPI;
import io.ipgeolocation.sdk.api.AsnLookupApi;
import io.ipgeolocation.sdk.model.ASNResponse;

AsnLookupAPI api = new AsnLookupAPI(client);

ASNResponse response = api.getAsnDetails()
        .ip("8.8.8.8")
        .execute();

System.out.println(response);

Sample Response:

java

class ASNResponse {
    ip: 8.8.8.8
    asn: class ASNDetails {
        asNumber: AS15169
        organization: Google LLC
        country: US
        asnName: GOOGLE
        type: BUSINESS
        domain: about.google
        dateAllocated: 
        allocationStatus: assigned
        numOfIpv4Routes: 983
        numOfIpv6Routes: 104
        rir: ARIN
    }
}

Get ASN Information by ASN Number

java

import io.ipgeolocation.sdk.model.ASNResponse;

ASNResponse response = api.getAsnDetails()
        .asn("AS15169")
        .execute();

System.out.println(response);

Sample Response:

java

class ASNResponse {
    asn: class ASNDetails {
        asNumber: AS15169
        organization: Google LLC
        country: US
        asnName: GOOGLE
        type: BUSINESS
        domain: about.google
        dateAllocated: 
        allocationStatus: assigned
        numOfIpv4Routes: 983
        numOfIpv6Routes: 104
        rir: ARIN
    }
}

Combine All objects using Include

java

import io.ipgeolocation.sdk.model.ASNResponse;

ASNResponse response = api.getAsnDetails()
        .asn("AS12")
        .include("peers,downstreams,upstreams,routes,whois_response")
        .execute();

System.out.println(response);

Sample Response:

java

class ASNResponse {
    ip: null
    asn: class ASNDetails {
        asNumber: AS12
        organization: New York University
        country: US
        asnName: NYU-DOMAIN
        type: EDUCATION
        domain: nyu.edu
        dateAllocated: 
        allocationStatus: assigned
        numOfIpv4Routes: 11
        numOfIpv6Routes: 1
        rir: ARIN
        routes: [192.76.177.0/24, 216.165.96.0/20, 216.165.89.0/24, 216.165.0.0/18, 216.165.112.0/21, 128.122.0.0/16, 2607:f600::/32, 216.165.102.0/24, 216.165.64.0/19, 216.165.120.0/22, 192.86.139.0/24, 216.165.103.0/24]
        upstreams: [class ASNConnection {
            asNumber: AS3269
            description: Telecom Italia S.p.A.
            country: IT
        }, class ASNConnection {
            asNumber: AS8220
            description: COLT Technology Services Group Limited
            country: GB
        }, class ASNConnection {
            asNumber: AS286
            description: GTT Communications Inc.
            country: US
        }, class ASNConnection {
            asNumber: AS3257
            description: GTT Communications Inc.
            country: US
        }, class ASNConnection {
            asNumber: AS3754
            description: NYSERNet
            country: US
        }, class ASNConnection {
            asNumber: AS3356
            description: Level 3 Parent, LLC
            country: US
        }, class ASNConnection {
            asNumber: AS6461
            description: Zayo Bandwidth
            country: US
        }, class ASNConnection {
            asNumber: AS137
            description: Consortium GARR
            country: IT
        }]
        downstreams: [class ASNConnection {
            asNumber: AS394666
            description: NYU Langone Health
            country: US
        }, class ASNConnection {
            asNumber: AS54965
            description: Polytechnic Institute of NYU
            country: US
        }]
        peers: [class ASNConnection {
            asNumber: AS3269
            description: Telecom Italia S.p.A.
            country: IT
        }, class ASNConnection {
            asNumber: AS8220
            description: COLT Technology Services Group Limited
            country: GB
        }, class ASNConnection {
            asNumber: AS394666
            description: NYU Langone Health
            country: US
        }, class ASNConnection {
            asNumber: AS286
            description: GTT Communications Inc.
            country: NL
        }, class ASNConnection {
            asNumber: AS286
            description: GTT Communications Inc.
            country: US
        }, class ASNConnection {
            asNumber: AS3257
            description: GTT Communications Inc.
            country: US
        }, class ASNConnection {
            asNumber: AS3754
            description: NYSERNet
            country: US
        }, class ASNConnection {
            asNumber: AS3356
            description: Level 3 Parent, LLC
            country: US
        }, class ASNConnection {
            asNumber: AS6461
            description: Zayo Bandwidth
            country: US
        }, class ASNConnection {
            asNumber: AS137
            description: Consortium GARR
            country: IT
        }, class ASNConnection {
            asNumber: AS54965
            description: Polytechnic Institute of NYU
            country: US
        }]
        whoisResponse: 
        
        
        ASNumber:       12
        ASName:         NYU-DOMAIN
        ASHandle:       AS12
        RegDate:        1984-07-05
        Updated:        2023-05-25    
        Ref:            https://rdap.arin.net/registry/autnum/12
        
        
        OrgName:        New York University
        OrgId:          NYU-Z
        Address:        726 Broadway, 8th Floor - ITS
        City:           New York
        StateProv:      NY
        PostalCode:     10003
        Country:        US
        RegDate:        2023-05-15
        Updated:        2023-05-15
        Ref:            https://rdap.arin.net/registry/entity/NYU-Z
        
        
        OrgAbuseHandle: OIS9-ARIN
        OrgAbuseName:   Office of Information Security
        OrgAbusePhone:  +1-212-998-3333 
        OrgAbuseEmail:  abuse@nyu.edu
        OrgAbuseRef:    https://rdap.arin.net/registry/entity/OIS9-ARIN
        
        OrgNOCHandle: COSI-ARIN
        OrgNOCName:   Communications Operations Services - ITS
        OrgNOCPhone:  +1-212-998-3444 
        OrgNOCEmail:  noc-cosi-arin@nyu.edu
        OrgNOCRef:    https://rdap.arin.net/registry/entity/COSI-ARIN
        
        OrgTechHandle: COSI-ARIN
        OrgTechName:   Communications Operations Services - ITS
        OrgTechPhone:  +1-212-998-3444 
        OrgTechEmail:  noc-cosi-arin@nyu.edu
        OrgTechRef:    https://rdap.arin.net/registry/entity/COSI-ARIN
        
        RTechHandle: COSI-ARIN
        RTechName:   Communications Operations Services - ITS
        RTechPhone:  +1-212-998-3444 
        RTechEmail:  noc-cosi-arin@nyu.edu
        RTechRef:    https://rdap.arin.net/registry/entity/COSI-ARIN
        
        RNOCHandle: COSI-ARIN
        RNOCName:   Communications Operations Services - ITS
        RNOCPhone:  +1-212-998-3444 
        RNOCEmail:  noc-cosi-arin@nyu.edu
        RNOCRef:    https://rdap.arin.net/registry/entity/COSI-ARIN
               
    }
}

Timezone API Examples

This section provides usage examples of the getTimezone() method from the SDK, showcasing how to fetch timezone and time-related data using different query types — IP address, latitude/longitude, and timezone ID. For full API specifications, refer to the Timezone API documentation.

Get Timezone by IP Address

java

import io.ipgeolocation.sdk.api.TimezoneAPI;
import io.ipgeolocation.sdk.model.TimezoneResponse;

TimezoneAPI api = new TimezoneAPI(client);

TimezoneResponse response = api.getTimezone()
        .ip("8.8.8.8")
        .execute();

System.out.println(response);

Sample Response:

java

class TimeZoneResponse {
    ip: 8.8.8.8
   
    location: class TimezoneLocation {
        continentCode: NA
        continentName: North America
        countryCode2: US
        countryCode3: USA
        countryName: United States
        countryNameOfficial: United States of America
        isEu: false
        stateProv: California
        stateCode: US-CA
        district: Santa Clara
        city: Mountain View
        locality: null
        zipcode: 94043-1351
        latitude: 37.42240
        longitude: -122.08421
    }
    timeZone: class TimezoneDetails {
        name: America/Los_Angeles
        offset: -8
        offsetWithDst: -7
        date: 2025-06-23
        dateTime: 2025-06-23 02:15:25
        dateTimeTxt: Monday, June 23, 2025 02:15:25
        dateTimeWti: Mon, 23 Jun 2025 02:15:25 -0700
        dateTimeYmd: 2025-06-23T02:15:25-0700
        dateTimeUnix: 1.750670125437E9
        time24: 02:15:25
        time12: 02:15:25 AM
        week: 26
        month: 6
        year: 2025
        yearAbbr: 25
        isDst: true
        dstSavings: 1
        dstExists: true
        dstStart: class TimezoneDetailDstStart {
            utcTime: 2025-03-09 TIME 10
            duration: +1H
            gap: true
            dateTimeAfter: 2025-03-09 TIME 03
            dateTimeBefore: 2025-03-09 TIME 02
            overlap: false
        }
        dstEnd: class TimezoneDetailDstEnd {
            utcTime: 2025-11-02 TIME 09
            duration: -1H
            gap: false
            dateTimeAfter: 2025-11-02 TIME 01
            dateTimeBefore: 2025-11-02 TIME 02
            overlap: true
        }
    }
}

Get Timezone by Timezone Name

java

import io.ipgeolocation.sdk.model.TimezoneResponse;

TimezoneResponse response = api.getTimezone()
        .tz("Europe/ London")
        .execute();

System.out.println(response);

Sample Response:

java

class TimeZoneResponse {
    timeZone: class TimezoneDetails {
        name: Europe/London
        offset: 0
        offsetWithDst: 1
        date: 2025-06-23
        dateTime: 2025-06-23 10:25:01
        dateTimeTxt: Monday, June 23, 2025 10:25:01
        dateTimeWti: Mon, 23 Jun 2025 10:25:01 +0100
        dateTimeYmd: 2025-06-23T10:25:01+0100
        dateTimeUnix: 1.750670701706E9
        time24: 10:25:01
        time12: 10:25:01 AM
        week: 26
        month: 6
        year: 2025
        yearAbbr: 25
        isDst: true
        dstSavings: 1
        dstExists: true
        dstStart: class TimezoneDetailDstStart {
            utcTime: 2025-03-30 TIME 01
            duration: +1H
            gap: true
            dateTimeAfter: 2025-03-30 TIME 02
            dateTimeBefore: 2025-03-30 TIME 01
            overlap: false
        }
        dstEnd: class TimezoneDetailDstEnd {
            utcTime: 2025-10-26 TIME 01
            duration: -1H
            gap: false
            dateTimeAfter: 2025-10-26 TIME 01
            dateTimeBefore: 2025-10-26 TIME 02
            overlap: true
        }
    }
}

Get Timezone from Any Address

java

import io.ipgeolocation.sdk.model.TimezoneResponse;

TimezoneResponse response = api.getTimezone()
        .location("Munich, Germany")
        .execute();

System.out.println(response);

Sample Response:

java

class TimeZoneResponse {
    location: class TimezoneLocation {
        locationString: Munich, Germany
        countryName: Germany
        stateProv: Bavaria
        city: Munich
        locality: 
        latitude: 48.13711
        longitude: 11.57538
    }
    timeZone: class TimezoneDetails {
        name: Europe/Berlin
        offset: 1
        offsetWithDst: 2
        date: 2025-06-23
        dateTime: 2025-06-23 11:35:23
        dateTimeTxt: Monday, June 23, 2025 11:35:23
        dateTimeWti: Mon, 23 Jun 2025 11:35:23 +0200
        dateTimeYmd: 2025-06-23T11:35:23+0200
        dateTimeUnix: 1.750671323755E9
        time24: 11:35:23
        time12: 11:35:23 AM
        week: 26
        month: 6
        year: 2025
        yearAbbr: 25
        isDst: true
        dstSavings: 1
        dstExists: true
        dstStart: class TimezoneDetailDstStart {
            utcTime: 2025-03-30 TIME 01
            duration: +1H
            gap: true
            dateTimeAfter: 2025-03-30 TIME 03
            dateTimeBefore: 2025-03-30 TIME 02
            overlap: false
        }
        dstEnd: class TimezoneDetailDstEnd {
            utcTime: 2025-10-26 TIME 01
            duration: -1H
            gap: false
            dateTimeAfter: 2025-10-26 TIME 02
            dateTimeBefore: 2025-10-26 TIME 03
            overlap: true
        }
    }
}

Get Timezone from Location Coordinates

java

import io.ipgeolocation.sdk.model.TimezoneResponse;

TimezoneResponse response = api.getTimezone()
        .lat(48.8566F)
        ._long(2.3522F)
        .execute();

System.out.println(response);

Sample Response:

java

class TimeZoneResponse {
    timeZone: class TimezoneDetails {
        name: Europe/Paris
        offset: 1
        offsetWithDst: 2
        date: 2025-06-23
        dateTime: 2025-06-23 11:53:31
        dateTimeTxt: Monday, June 23, 2025 11:53:31
        dateTimeWti: Mon, 23 Jun 2025 11:53:31 +0200
        dateTimeYmd: 2025-06-23T11:53:31+0200
        dateTimeUnix: 1.750672411295E9
        time24: 11:53:31
        time12: 11:53:31 AM
        week: 26
        month: 6
        year: 2025
        yearAbbr: 25
        isDst: true
        dstSavings: 1
        dstExists: true
        dstStart: class TimezoneDetailDstStart {
            utcTime: 2025-03-30 TIME 01
            duration: +1H
            gap: true
            dateTimeAfter: 2025-03-30 TIME 03
            dateTimeBefore: 2025-03-30 TIME 02
            overlap: false
        }
        dstEnd: class TimezoneDetailDstEnd {
            utcTime: 2025-10-26 TIME 01
            duration: -1H
            gap: false
            dateTimeAfter: 2025-10-26 TIME 02
            dateTimeBefore: 2025-10-26 TIME 03
            overlap: true
        }
    }
}

Get Timezone and Airport Details from IATA Code

java

import io.ipgeolocation.sdk.model.TimezoneResponse;

TimezoneResponse response = api.getTimezone()
        .iataCode("ZRH")
        .execute();

System.out.println(response);

Sample Response:

java

class TimeZoneResponse {
    airportDetails: class TimezoneAirport {
        type: large_airport
        name: Zurich Airport
        latitude: 47.45806
        longitude: 8.54806
        elevationFt: 1417
        continentCode: EU
        countryCode: CH
        stateCode: CH-ZH
        city: Zurich
        iataCode: ZRH
        icaoCode: LSZH
        faaCode: 
    }
    timeZone: class TimezoneDetails {
        name: Europe/Zurich
        offset: 1
        offsetWithDst: 2
        date: 2025-06-23
        dateTime: 2025-06-23 12:24:08
        dateTimeTxt: Monday, June 23, 2025 12:24:08
        dateTimeWti: Mon, 23 Jun 2025 12:24:08 +0200
        dateTimeYmd: 2025-06-23T12:24:08+0200
        dateTimeUnix: 1.750674248242E9
        time24: 12:24:08
        time12: 12:24:08 PM
        week: 26
        month: 6
        year: 2025
        yearAbbr: 25
        isDst: true
        dstSavings: 1
        dstExists: true
        dstStart: class TimezoneDetailDstStart {
            utcTime: 2025-03-30 TIME 01
            duration: +1H
            gap: true
            dateTimeAfter: 2025-03-30 TIME 03
            dateTimeBefore: 2025-03-30 TIME 02
            overlap: false
        }
        dstEnd: class TimezoneDetailDstEnd {
            utcTime: 2025-10-26 TIME 01
            duration: -1H
            gap: false
            dateTimeAfter: 2025-10-26 TIME 02
            dateTimeBefore: 2025-10-26 TIME 03
            overlap: true
        }
    }
}

Similarly, you can fetch Airport Details and Timezone from using any ICAO code as well

Get Timezone and City Details from UN/LOCODE

java

import io.ipgeolocation.sdk.model.TimezoneResponse;

TimezoneResponse response = api.getTimezone()
        .loCode("ESBCN")
        .execute();

System.out.println(response);

Sample Response:

java

class TimeZoneResponse {
    loCodeDetails: class TimezoneLocode {
        loCode: ESBCN
        city: Barcelona
        stateCode: 
        countryCode: ES
        countryName: 
        locationType: Port, Rail Terminal, Road Terminal, Airport, Postal Exchange
        latitude: 41.38289
        longitude: 2.17743
    }
    timeZone: class TimezoneDetails {
        name: Europe/Madrid
        offset: 1
        offsetWithDst: 2
        date: 2025-06-23
        dateTime: 2025-06-23 12:32:55
        dateTimeTxt: Monday, June 23, 2025 12:32:55
        dateTimeWti: Mon, 23 Jun 2025 12:32:55 +0200
        dateTimeYmd: 2025-06-23T12:32:55+0200
        dateTimeUnix: 1.750674775033E9
        time24: 12:32:55
        time12: 12:32:55 PM
        week: 26
        month: 6
        year: 2025
        yearAbbr: 25
        isDst: true
        dstSavings: 1
        dstExists: true
        dstStart: class TimezoneDetailDstStart {
            utcTime: 2025-03-30 TIME 01
            duration: +1H
            gap: true
            dateTimeAfter: 2025-03-30 TIME 03
            dateTimeBefore: 2025-03-30 TIME 02
            overlap: false
        }
        dstEnd: class TimezoneDetailDstEnd {
            utcTime: 2025-10-26 TIME 01
            duration: -1H
            gap: false
            dateTimeAfter: 2025-10-26 TIME 02
            dateTimeBefore: 2025-10-26 TIME 03
            overlap: true
        }
    }
}

Timezone Converter Examples

This section provides usage examples of the convertTimezone() method from the SDK. The Timezone Converter API allows you to convert a specific time from one timezone to another using timezone identifiers and optional date/time inputs. For more details, refer to official documentation: Timezone Converter API.

Convert Current Time from One Timezone to Another

java

import io.ipgeolocation.sdk.api.TimezoneAPI;
import io.ipgeolocation.sdk.model.TimezoneConversionResponse;

TimezoneAPI api = new TimezoneAPI(client);

TimezoneConversionResponse response = api.convertTimezone()
        .from("America/New_York")
        .to("Asia/Tokyo")
        .execute();

System.out.println(response);

Sample Response:

java

class TimeConversionResponse {
    originalTime: 2024-12-08 11:00
    convertedTime: 2024-12-09 01:00:00
    diffHour: 14.0
    diffMin: 840
}

Similarly, you can convert time from any timezone to another timezone using location coordinates (Latitude and Longitude), location addresses, IATA codes, ICAO codes and UN/LUCODE .

User Agent API Examples

This section provides usage examples of the getUserAgent() method from the SDK. The User Agent API extracts and classifies information from user agent strings, including browser, engine, device, OS, and type metadata. For full explanation, visit the User Agent API documentation.

Parse a Basic User Agent String

java

import io.ipgeolocation.sdk.api.UserAgentAPI;
import io.ipgeolocation.sdk.model.UserAgentResponse;

UserAgentAPI api = new UserAgentAPI(client);

UserAgentResponse response = api.getUserAgent()
        .userAgentString("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36")
        .execute();

System.out.println(response);

Sample Response:

java

class UserAgentData {
    userAgentString: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36
    name: Chrome
    type: Browser
    version: 125
    versionMajor: 125
    device: class UserAgentDataDevice {
        name: Desktop
        type: Desktop
        brand: Unknown
        cpu: Intel x86_64
    }
    engine: class UserAgentDataEngine {
        name: Blink
        type: Browser
        version: 125
        versionMajor: 125
    }
    operatingSystem: class UserAgentDataOperatingSystem {
        name: Windows NT
        type: Desktop
        version: ??
        versionMajor: ??
        build: ??
    }
}

If you don't pass any userAgentString, the API will return the data of device's user agent.

Bulk User Agent Parsing Example

The SDK also supports bulk User Agent parsing using the getBulkUserAgent() method. This allows parsing multiple user agent strings in a single request. All fields available in single-user-agent parsing are returned per entry.

java

import io.ipgeolocation.sdk.api.UserAgentAPI;
import io.ipgeolocation.sdk.model.UserAgentBulkRequest;
import io.ipgeolocation.sdk.model.UserAgentData;

UserAgentAPI api = new UserAgentAPI(client);

UserAgentBulkRequest bulkRequest = new UserAgentBulkRequest();
bulkRequest.addUaString("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36");
bulkRequest.addUaString("Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.0 Mobile/15E148 Safari/604.1");

List<UserAgentData> response = api.getBulkUserAgent()
        .userAgentBulkRequest(bulkRequest)
        .execute();

System.out.println(response);

Astronomy API Examples

This section provides usage examples of the getAstronomy() method from the SDK, allowing developers to fetch sun and moon timings and position data based on coordinates, IP, or location string. Refer to the official Astronomy API documentation for more details.

Retrieving Geolocation Data in Multiple Languages

java

import io.ipgeolocation.sdk.api.AstronomyAPI;
import io.ipgeolocation.sdk.model.AstronomyResponse;

AstronomyAPI api = new AstronomyAPI(client);

AstronomyResponse response = api.getAstronomy()
        .lat(40.7128F)
        ._long(-74.0060F)
        .execute();

System.out.println(response);

Sample Response:

java

class AstronomyResponse {
    location: class TimezoneLocation {
        latitude: 40.71280
        longitude: -74.00600
    }
    astronomy: class Astronomy {
        date: 2025-06-24
        currentTime: 07:30:21.579
        sunrise: 05:26
        sunset: 20:31
        sunStatus: -
        solarNoon: 12:58
        dayLength: 15:05
        sunAltitude: 20.804246588855296
        sunDistance: 152040201.01537988
        sunAzimuth: 76.49892606690912
        moonrise: 04:03
        moonset: 20:23
        moonStatus: -
        moonAltitude: 34.414214378812524
        moonDistance: 364347.463373039
        moonAzimuth: 80.61208284060893
        moonParallacticAngle: -57.93796259578105
        moonPhase: NEW_MOON
        moonIlluminationPercentage: -1.31
        moonAngle: 346.8453135834885
    }
}

Astronomy by IP Address

java

AstronomyResponse response = api.getAstronomy()
        .ip("8.8.8.8")
        .execute();

System.out.println(response);

Sample Response:

java

class AstronomyResponse {
    ip: 8.8.8.8
    location: class TimezoneLocation {
        continentCode: NA
        continentName: North America
        countryCode2: US
        countryCode3: USA
        countryName: United States
        countryNameOfficial: United States of America
        isEu: false
        stateProv: California
        stateCode: US-CA
        district: Santa Clara
        city: Mountain View
        zipcode: 94043-1351
        latitude: 37.42240
        longitude: -122.08421
    }
    astronomy: class Astronomy {
        date: 2025-06-24
        currentTime: 04:34:28.021
        sunrise: 05:48
        sunset: 20:33
        sunStatus: -
        solarNoon: 13:10
        dayLength: 14:45
        sunAltitude: -12.617167576625503
        sunDistance: 152040201.01537988
        sunAzimuth: 46.86985777464207
        moonrise: 04:37
        moonset: 20:30
        moonStatus: -
        moonAltitude: -0.21211874350402243
        moonDistance: 364352.7073377457
        moonAzimuth: 53.468292502889824
        moonParallacticAngle: -46.31833060135301
        moonPhase: NEW_MOON
        moonIlluminationPercentage: -1.30
        moonAngle: 346.8846229043112
    }
}

Astronomy by Location String

java

AstronomyResponse response = api.getAstronomy()
    .location("Milan, Italy")
    .execute();

System.out.println(response);

Sample Response:

java

class AstronomyResponse {
    location: class TimezoneLocation {
        locationString: Milan, Italy
        countryName: Italy
        stateProv: Lombardy
        city: Milan
        locality: 
        latitude: 45.46419
        longitude: 9.18963
    }
    astronomy: class Astronomy {
        date: 2025-06-24
        currentTime: 13:42:31.494
        sunrise: 05:35
        sunset: 21:16
        sunStatus: -
        solarNoon: 13:25
        dayLength: 15:41
        sunAltitude: 67.67235422430544
        sunDistance: 152040201.01537988
        sunAzimuth: 190.14730820895687
        moonrise: 03:55
        moonset: 20:58
        moonStatus: -
        moonAltitude: 67.12458191571332
        moonDistance: 364363.02827482205
        moonAzimuth: 226.96305382114292
        moonParallacticAngle: 35.51972222628293
        moonPhase: NEW_MOON
        moonIlluminationPercentage: -1.29
        moonAngle: 346.9617371469379
    }
}

Astronomy for Specific Date

java

AstronomyResponse response = api.getAstronomy()
        .lat("-27.47")
        ._long("153.02")
        .date("2025-01-01")
        .execute();

System.out.println(response);

Sample Response:

java

class AstronomyResponse {
    location: class TimezoneLocation {
        latitude: -27.47000
        longitude: 153.02000
    }
    astronomy: class Astronomy {
        date: 2025-01-01
        currentTime: 21:52:17.735
        sunrise: 04:56
        sunset: 18:46
        sunStatus: -
        solarNoon: 11:51
        dayLength: 13:50
        sunAltitude: -31.926446962587317
        sunDistance: 147102938.8803657
        sunAzimuth: 212.6674132050822
        moonrise: 05:42
        moonset: 20:08
        moonStatus: -
        moonAltitude: -18.400463391101542
        moonDistance: 380312.3006037494
        moonAzimuth: 228.6071219705199
        moonParallacticAngle: 133.10083951250047
        moonPhase: NEW_MOON
        moonIlluminationPercentage: 2.80
        moonAngle: 19.261001616778085
    }
}

You can also get Astronomy Data in other languages as well. Only paid subscriptions can access this feature.

Astronomy in Different Language

java

AstronomyResponse response = api.getAstronomy()
        .ip("1.1.1.1")
        .lang("fr")
        .execute();

System.out.println(response);

Sample Response:

java

class AstronomyResponse {
    ip: 1.1.1.1
    location: class TimezoneLocation {
        continentCode: OC
        continentName: Océanie
        countryCode2: AU
        countryCode3: AUS
        countryName: Australie
        countryNameOfficial: 
        isEu: false
        stateProv: Queensland
        stateCode: AU-QLD
        district: Brisbane
        city: Brisbane Sud
        locality: null
        zipcode: 4101
        latitude: -27.47306
        longitude: 153.01421
    }
    astronomy: class Astronomy {
        date: 2025-06-24
        currentTime: 21:58:05.865
        sunrise: 06:38
        sunset: 17:02
        sunStatus: -
        solarNoon: 11:50
        dayLength: 10:24
        sunAltitude: -64.35374526473097
        sunDistance: 152040201.0153799
        sunAzimuth: 267.19451980250926
        moonrise: 05:11
        moonset: 15:31
        moonStatus: -
        moonAltitude: -77.90471534790521
        moonDistance: 364383.09958533326
        moonAzimuth: 276.0819890304232
        moonParallacticAngle: 90.30849575969972
        moonPhase: NEW_MOON
        moonIlluminationPercentage: -1.26
        moonAngle: 347.1107575290927
    }
}

Documentation for Models

Each model class provides getters for all fields documented in the official API docs.

IP Geolocation API Java SDK Objects Reference

IP Geolocation API Java SDK has following classes that you can use to fully leverage it.

ASNConnection

Method	Description	Return Type
asNumber	Returns the autonomous system (AS) number of the network connection (e.g., 'AS12345').	String
description	Returns the description of the AS (often the organization name associated with the AS number).	String
country	Returns the two-letter country code where this AS is registered.	String

ASNResponse

Method	Description	Return Type
ip	IP address for which ASN information was retrieved.	String
asn	ASN information for the given IP.	ASNDetails

ASNDetails

Method	Description	Return Type
asNumber	AS number (Autonomous System Number), typically in the format 'AS####'.	String
organization	Name of the organization or ISP that owns the ASN.	String
country	Country code where the ASN is registered (ISO 2-letter).	String
asnName	Official registry name of the ASN.	String
type	Type of organization or network (e.g., 'ISP', 'Business', 'Hosting').	String
domain	Domain name associated with the ASN’s organization.	URI
dateAllocated	Date when this ASN was allocated (in YYYY-MM-DD format).	LocalDate
allocationStatus	Current status of the ASN allocation.	String
numOfIpv4Routes	Number of IPv4 routes announced by this ASN.	Integer
numOfIpv6Routes	Number of IPv6 routes announced by this ASN.	Integer
rir	Regional Internet Registry that issued the ASN.	String
routes	List of route prefixes (CIDR notation) announced by this ASN.	List<String>
upstreams	List of upstream provider connections.	List<ASNConnection>
downstreams	List of downstream AS connections.	List<ASNConnection>
peers	List of lateral peer AS connections.	List<ASNConnection>
whoisResponse	Raw WHOIS response data for this ASN.	String

Abuse

Method	Description	Return Type
route	The network route (CIDR block) that the abuse contact record covers.	String
country	Country code of the abuse contact's organization.	String
handle	Unique identifier/handle of the abuse contact as per WHOIS records.	String
name	Name of the abuse contact person or department.	String
organization	Organization name to which the abuse contact belongs.	String
role	Role or title of the abuse contact (e.g., 'Abuse Manager').	String
kind	Kind of contact (e.g., 'Group' or 'Person').	String
address	Mailing address for the abuse contact.	String
emails	List of email addresses to report abuse incidents.	List<String>
phoneNumbers	List of contact phone numbers for the abuse contact.	List<String>

Astronomy

Method	Description	Return Type
date	Date for which the astronomical data is calculated (YYYY-MM-DD).	LocalDate
currentTime	Current local time at the location (in HH:mm:ss.SSS format).	String
sunrise	Local time of sunrise.	String
sunset	Local time of sunset.	String
sunStatus	Special status of the sun relative to the horizon.	String
solarNoon	Local time of solar noon.	String
dayLength	Total length of daylight for the date (HH:mm).	String
sunAltitude	Sun’s altitude angle at current time.	BigDecimal
sunDistance	Distance from Earth to the Sun at current time (km).	BigDecimal
sunAzimuth	Sun’s azimuth angle at current time.	BigDecimal
moonrise	Local time of moonrise.	String
moonset	Local time of moonset.	String
moonStatus	Special status of the moon relative to the horizon.	String
moonAltitude	Moon’s altitude angle at current time.	BigDecimal
moonDistance	Distance from Earth to the Moon at current time (km).	BigDecimal
moonAzimuth	Moon’s azimuth angle at current time.	BigDecimal
moonParallacticAngle	Moon’s parallactic angle at current time.	BigDecimal
moonPhase	Current phase of the Moon.	String
moonIlluminationPercentage	Percentage of the Moon’s disc that is illuminated.	String
moonAngle	Apparent angular diameter of the Moon as seen from Earth.	BigDecimal

AstronomyResponse

Method	Description	Return Type
ip	IP address for which astronomy information was requested.	String
location	Location details associated with the astronomy data.	TimezoneLocation
astronomy	Astronomical data for the location.	Astronomy

CountryMetadata

Method	Description	Return Type
callingCode	International telephone calling code for the country.	String
tld	Top-level domain for the country.	String
languages	List of languages (locale codes) officially used in the country.	List<String>

Currency

Method	Description	Return Type
code	ISO 4217 currency code (e.g., 'USD').	String
name	Name of the currency (e.g., 'US Dollar').	String
symbol	Symbol of the currency (e.g., '$' or '€').	String

ErrorResponse

Method	Description	Return Type
message	Error message explaining why the request was not successful.	String

GeolocationResponse

Method	Description	Return Type
ip	The IP address that was looked up.	String
hostname	The hostname resolved for the IP.	String
domain	The domain name associated with the IP.	String
location	Geographical location information for the IP.	Location
countryMetadata	Additional country details for the IP's country.	CountryMetadata
network	Network information for the IP.	Network
currency	Local currency information for the IP's country.	Currency
security	Security/threat intelligence details for the IP.	Security
abuse	Abuse contact information for the IP.	Abuse
timeZone	Timezone information for the IP's location.	TimeZone
userAgent	Parsed user agent data if a user agent string was provided.	UserAgentData

BulkGeolocationResponse

Method	Description	Return Type
message	Message or error for this particular IP result.	String
ip	The IP address that was looked up in the bulk request.	String
hostname	Resolved hostname for this IP.	String
domain	Associated domain for this IP.	String
location	Geographical location information for this IP.	Location
countryMetadata	Country metadata for this IP’s country.	CountryMetadata
network	Network information for this IP.	Network
currency	Local currency information for the IP’s country.	Currency
security	Security details for this IP.	Security
abuse	Abuse contact info for this IP.	Abuse
timeZone	Timezone information for this IP.	TimeZone
userAgent	Parsed user agent data for this IP’s entry.	UserAgentData

BulkIPRequest

Method	Description	Return Type
ips	List of IP addresses to query in a bulk lookup request.	List<String>

Location

Method	Description	Return Type
continentCode	Continent code (e.g., 'NA' for North America).	String
continentName	Name of the continent.	String
countryCode2	ISO 2-letter country code.	String
countryCode3	ISO 3-letter country code.	String
countryName	English name of the country.	String
countryNameOfficial	Official name of the country.	String
countryCapital	Capital city of the country.	String
stateProv	Name of the state or province.	String
stateCode	Code of the state or province.	String
district	District or county name.	String
city	City or town name.	String
zipcode	ZIP or postal code of the location.	String
latitude	Latitude coordinate of the location.	String
longitude	Longitude coordinate of the location.	String
isEu	Indicates if the country is a member of the European Union.	Boolean
countryFlag	URL of an image of the country’s flag.	String
geonameId	Geonames.org identifier for the city/location.	String
countryEmoji	Emoji representation of the country’s flag.	String
accuracyRadius	Approximate accuracy radius of the IP geolocation.	String
locality	Locality or neighborhood name.	String
dmaCode	Designated Market Area code.	String

LocationMinimal

Method	Description	Return Type
continentCode	Continent code (e.g., 'AS' for Asia).	String
continentName	Name of the continent.	String
countryCode2	ISO 2-letter country code.	String
countryCode3	ISO 3-letter country code.	String
countryName	Country name.	String
countryNameOfficial	Official country name.	String
countryCapital	Capital city of the country.	String
stateProv	State or province name.	String
stateCode	State or province code.	String
district	District or county name.	String
city	City name.	String
zipcode	Postal code.	String
latitude	Latitude coordinate.	String
longitude	Longitude coordinate.	String
isEu	True if the country is in the EU.	Boolean
countryFlag	URL of the country’s flag image.	String
geonameId	Geoname ID of the location.	String
countryEmoji	Emoji flag of the country.	String

Network

Method	Description	Return Type
asn	ASN information for the IP address.	NetworkAsn
connectionType	Type of internet connection for the IP.	String
company	Company/ISP information for the IP.	NetworkCompany

NetworkAsn

Method	Description	Return Type
asNumber	Autonomous System Number.	String
organization	Organization name associated with the ASN.	String
country	Country code where the ASN is registered.	String
asnName	Name of the ASN.	String
type	Type/category of the ASN’s organization.	String
domain	Associated domain name of the ASN’s organization.	String
dateAllocated	Date the ASN was allocated.	String
allocationStatus	Status of the ASN allocation.	String
numOfIpv4Routes	Number of IPv4 route prefixes announced by this ASN.	String
numOfIpv6Routes	Number of IPv6 route prefixes announced by this ASN.	String
rir	Regional Internet Registry that issued the ASN.	String

NetworkCompany

Method	Description	Return Type
name	Name of the company or ISP that owns the IP address.	String
type	Type of company/organization.	String
domain	Domain name of the company.	String

NetworkMinimal

Method	Description	Return Type
asn	Basic ASN information for the IP.	NetworkMinimalAsn
company	Basic company/ISP information for the IP.	NetworkMinimalCompany

NetworkMinimalAsn

Method	Description	Return Type
asNumber	Autonomous System Number for the IP’s network.	String
organization	Name of the organization/ISP for this ASN.	String
country	Country code of the ASN’s registration.	String

NetworkMinimalCompany

Method	Description	Return Type
name	Name of the ISP or company associated with the IP.	String

Security

Method	Description	Return Type
threatScore	Threat score for the IP (higher score = higher risk).	Integer
isTor	True if the IP is a Tor exit node.	Boolean
isProxy	True if the IP is detected as a proxy.	Boolean
proxyType	Type of proxy if the IP is a proxy (e.g., 'VPN', 'HTTP').	String
proxyProvider	Name of the proxy/VPN provider.	String
isAnonymous	True if the IP is associated with anonymous network usage.	Boolean
isKnownAttacker	True if the IP is a known attacker source.	Boolean
isSpam	True if the IP is known for sending spam.	Boolean
isBot	True if the IP is identified as a bot or crawler.	Boolean
isCloudProvider	True if the IP belongs to a known cloud computing provider.	Boolean
cloudProvider	Name of the cloud provider (if known).	String

SecurityAPIResponse

Method	Description	Return Type
ip	The IP address for which security information was requested.	String
hostname	Resolved hostname for the IP (if available).	String
security	Security details for the IP address.	Security
location	Minimal location information for the IP.	LocationMinimal
network	Minimal network information for the IP.	NetworkMinimal
timeZone	Detailed timezone information for the IP’s location.	TimezoneDetails
userAgent	Parsed user agent data if provided in the request.	UserAgentData
countryMetadata	Country metadata for the IP’s country.	CountryMetadata
currency	Currency information for the IP’s country.	Currency

BulkSecurityResponse

Method	Description	Return Type
ip	The IP address for which the security data is returned.	String
hostname	Resolved hostname for the IP address, if available.	String
security	Detailed security information for the IP address (see Security class).	Security
location	Minimal location information for the IP (see LocationMinimal class).	LocationMinimal
network	Minimal network details for the IP (see NetworkMinimal class).	NetworkMinimal
timeZone	Time zone details for the IP's location (see TimezoneDetails class).	TimezoneDetails
userAgent	Parsed user agent data if a user agent was provided (see UserAgentData class).	UserAgentData
countryMetadata	Additional country metadata (see CountryMetadata class).	CountryMetadata
currency	Currency information relevant to the IP's country (see Currency class).	Currency
message	Error message or additional information for this result.	String

TimeConversionResponse

Method	Description	Return Type
time	The original time value to convert, typically in ISO or standard datetime string format.	String
fromTimezone	Time zone ID (IANA format) to convert from (e.g., 'America/New_York').	String
toTimezone	Time zone ID (IANA format) to convert to (e.g., 'Asia/Kolkata').	String
convertedTime	Time converted into the target time zone, in the same format as the original.	String

TimeZone

Method	Description	Return Type
status	HTTP status code of the geolocation/time zone query (200 indicates success).	Integer
message	Error message if the query was unsuccessful.	String
timezone	Time zone ID in IANA format (e.g., 'America/Los_Angeles').	String
timezoneOffset	Offset from UTC in hours for this time zone (can be negative).	Double
date	Current date in the time zone (format: 'yyyy-MM-dd').	String
dateTime	Current date and time in the time zone (format: 'yyyy-MM-dd HH:mm:ss').	String
dateTimeTxt	Date and time as a formatted text string (e.g., 'Monday, January 01, 2024 15:30:00').	String
dateTimeWti	Date and time in WTI format (e.g., 'Mon, 01 Jan 2024 15:30:00 +0000').	String
dateTimeYmd	Date and time in ISO 8601 format with 'T' (e.g., '2024-01-01T15:30:00Z').	String
time24	Current time in 24-hour format (HH:mm:ss).	String
time12	Current time in 12-hour format with AM/PM (hh:mm:ss aa).	String
week	Current week of the year in this time zone.	String
month	Current month number in this time zone.	String
year	Current year in this time zone.	String
isDST	True if this time zone is currently observing Daylight Saving Time.	Boolean
dstSavings	Daylight Saving Time offset in hours, if applicable.	Double
timezoneGeo	Geolocation object for the time zone if the lookup was IP-based (see TimezoneGeo).	TimezoneGeo

TimezoneResponse

Method	Description	Return Type
timezone	Time zone ID for the queried location or IP.	String
timezoneOffset	Time zone offset from UTC in hours.	Double
dateTime	Current local date and time (format: 'yyyy-MM-dd HH:mm:ss').	String
date	Current date in the queried time zone.	String
time24	Current time in 24-hour format.	String
isDST	True if Daylight Saving Time is in effect.	Boolean
dstSavings	Amount of DST in hours.	Double
timezoneGeo	Geolocation for the time zone (see TimezoneGeo).	TimezoneGeo
status	HTTP status of the response.	Integer
message	Error message if the request failed.	String

TimezoneDstEnd

Method	Description	Return Type
date	The date when Daylight Saving Time ends (format: 'yyyy-MM-dd').	String
time	The time of day when DST ends.	String
dateTime	Combined date and time when DST ends.	String
weekDay	Day of the week when DST ends (e.g., 'Sunday').	String
week	Week of the month when DST ends (e.g., 'First', 'Last').	String
month	Month when DST ends (e.g., 'November').	String

TimezoneDstStart

Method	Description	Return Type
date	The date when Daylight Saving Time starts (format: 'yyyy-MM-dd').	String
time	The time of day when DST starts.	String
dateTime	Combined date and time when DST starts.	String
weekDay	Day of the week when DST starts.	String
week	Week of the month when DST starts.	String
month	Month when DST starts (e.g., 'March').	String

TimezoneAirport

Method	Description	Return Type
icao	ICAO code for the airport (4-letter code, e.g., 'KJFK').	String
iata	IATA code for the airport (3-letter code, e.g., 'JFK').	String
name	Full name of the airport.	String
city	City where the airport is located.	String
stateProv	State or province of the airport.	String
countryCode	2-letter country code of the airport.	String
countryName	Full country name of the airport's location.	String
latitude	Latitude coordinate of the airport.	Double
longitude	Longitude coordinate of the airport.	Double
timezone	Time zone of the airport.	String
gmtOffset	GMT offset for the airport's time zone, in hours.	Double

TimezoneDetails

Method	Description	Return Type
timezone	Time zone ID in IANA format (e.g., 'Europe/Berlin').	String
timezoneAbbreviation	Short abbreviation of the time zone (e.g., 'CET').	String
utcOffset	UTC offset in hours as a string (e.g., '+2').	String
isDST	True if the location is observing Daylight Saving Time.	Boolean
dstSavings	Number of hours of Daylight Saving Time in effect.	String
dateTime	Current local date and time in the time zone.	String
date	Current date (format: 'yyyy-MM-dd').	String
time24	Current time in 24-hour format.	String
time12	Current time in 12-hour format.	String
week	Current week number.	String
month	Current month number.	String
year	Current year.	String
unixTime	Current unix timestamp for the time zone.	Long
dstStart	DST start details object (see TimezoneDetailDstStart).	TimezoneDetailDstStart
dstEnd	DST end details object (see TimezoneDetailDstEnd).	TimezoneDetailDstEnd
airport	Nearest airport details (see TimezoneAirport).	TimezoneAirport
location	Geographic location details (see TimezoneLocation).	TimezoneLocation
locode	UN/LOCODE details for this location (see TimezoneLocode).	TimezoneLocode

TimezoneDetailDstEnd

Method	Description	Return Type
date	Date when Daylight Saving Time ends.	String
time	Time of day when DST ends.	String
dateTime	Combined date and time when DST ends.	String
weekDay	Day of the week DST ends.	String
week	Week of the month DST ends.	String
month	Month DST ends.	String

TimezoneDetailDstStart

Method	Description	Return Type
date	Date when Daylight Saving Time starts.	String
time	Time of day when DST starts.	String
dateTime	Combined date and time when DST starts.	String
weekDay	Day of the week DST starts.	String
week	Week of the month DST starts.	String
month	Month DST starts.	String

TimezoneLocation

Method	Description	Return Type
countryCode2	2-letter ISO country code for the location.	String
countryCode3	3-letter ISO country code for the location.	String
countryName	Country name for the location.	String
stateProvince	State or province of the location.	String
district	District within the state/province.	String
city	City at the location.	String
zipCode	ZIP or postal code for the location.	String
latitude	Latitude of the location.	Double
longitude	Longitude of the location.	Double

TimezoneLocode

Method	Description	Return Type
code	UN/LOCODE for the location (e.g., 'USNYC').	String
name	Location name for the UN/LOCODE.	String
country	Country code for the location.	String
subdivision	Subdivision code (state/province) for the location.	String
function	Function code assigned by UN/LOCODE.	String
status	Status of the UN/LOCODE entry.	String
date	Date the UN/LOCODE was assigned or updated.	String
iata	IATA code for the location if available.	String

UserAgentBulkRequest

Method	Description	Return Type
userAgents	An array of user agent strings to be parsed in a bulk request.	List<String>

UserAgentData

Method	Description	Return Type
userAgentString	The original user agent string as provided in the request.	String
type	The detected type of agent (e.g., 'Browser', 'Bot', 'Mobile App', etc.).	String
name	The detected product name (e.g., 'Chrome', 'Edge', 'WhatsApp').	String
version	Version number of the detected product.	String
engine	Rendering engine details (see UserAgentDataEngine).	UserAgentDataEngine
operatingSystem	Detected operating system details (see UserAgentDataOperatingSystem).	UserAgentDataOperatingSystem
device	Device details (see UserAgentDataDevice).	UserAgentDataDevice
isMobile	True if the agent is recognized as a mobile device/browser.	Boolean
isBot	True if the agent is a crawler, bot, or spider.	Boolean
botName	Name of the bot/crawler, if detected.	String

UserAgentDataDevice

Method	Description	Return Type
brand	Brand/manufacturer of the device, if detectable (e.g., 'Apple', 'Samsung').	String
model	Device model name or number (e.g., 'iPhone 14', 'Pixel 7 Pro').	String
type	Type of device (e.g., 'Smartphone', 'Tablet', 'Desktop', 'Smart TV').	String
isTouch	True if device supports touch input.	Boolean

UserAgentDataEngine

Method	Description	Return Type
name	Name of the rendering engine (e.g., 'Blink', 'WebKit', 'Gecko').	String
version	Version number of the rendering engine.	String
manufacturer	Manufacturer or maintainer of the engine (e.g., 'Google', 'Mozilla').	String
mode	Engine mode if specified (e.g., 'compatibility mode').	String

UserAgentDataOperatingSystem

Method	Description	Return Type
name	Name of the operating system (e.g., 'Windows', 'iOS', 'Android', 'Linux').	String
version	Detected OS version.	String
platform	Platform family (e.g., 'x86', 'ARM', 'Apple').	String
manufacturer	Operating system manufacturer or vendor (e.g., 'Microsoft', 'Apple').	String
isMobile	True if the OS is typically used on mobile devices.	Boolean

UserAgentPostRequest

Method	Description	Return Type
userAgent	A single user agent string to be parsed for device, browser, and OS detection.	String

Source Code

The complete source code for this SDK is available at Github.

Overview
Installation
Authentication
IP Geolocation Examples
IP Security Examples
ASN API Examples
Timezone API Examples
User Agent API Examples
Astronomy Examples
IPGeolocation SDK Objects Reference