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.