IPGeolocation-Logo

IPGeolocation.io API Java SDK

Overview

The official Java SDK provides streamlined access to IPGeolocation.io, a comprehensive platform offering RESTful IP-based APIs and downloadable databases delivering precise Geolocation, Network, Timezone, Currency, Abuse Contacts, ASN, and Company/ISP details for IPv4 and IPv6 addresses and User-Agent string parsing.

With built-in support for VPN, proxy, TOR detection, and threat detection (via the IPGeolocation's Security API for threat intelligence), this SDK also enables developers to integrate threat intelligence, personalization, fraud prevention, compliance, and analytics features into Java applications.

Whether you're enriching signup forms with ip geolocation data, localizing content, embedding threat intelligence in back-end systems, or converting time zones and currencies, the SDK ensures seamless, scalable integration with IPGeolocation.io’s global API infrastructure.

Based on:

  • API version: 2.0

Official Release:

Requirements

  • Java: 1.8 or higher
  • Build Tools: Maven 3.8.3+ or Gradle 7.2+
  • API Key: Sign up IPGeolocation.io

Installation

1.Using Maven

Add the following dependency to your pom.xml file located at :

2.Using Gradle

Add this to your build.gradle file:

3.Manual Installation

To build the SDK manually:

Then include the following JARs in your classpath:

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

API Plan Tiers and Documentation

The documentation below corresponds to the four available API tier plans:

For a detailed comparison of what each plan offers, visit the Pricing Page.

API Endpoints

All URIs are relative to https://api.ipgeolocation.io/v2

ClassMethodHTTP requestDescription
IPGeolocationAPIgetIPGeolocationGET /ipgeoGet geolocation data for a single IP address
IPGeolocationAPIgetBulkIPGeolocationPOST /ipgeo-bulkGet geolocation data for multiple IP addresses in a single API request
IPSecurityAPIgetIPSecurityGET /securityRetrieve security information (VPN, TOR, proxy, etc.) for a single IP
IPSecurityAPIgetBulkIPSecurityPOST /security-bulkRetrieve security threat intelligence for multiple IPs
ASNLookupAPIgetAsnDetailsGET /asnGet details of any AS number or associated IP address
AbuseContactAPIgetAbuseContactInfoGET /abuseRetrieve abuse reporting contact information for a given IP address
AstronomyAPIgetAstronomyGET /astronomyGet sunrise, sunset, moonrise, moonset, and related data for a location
TimezoneAPIgetTimezoneGET /timezoneGet timezone information details
TimeConversionAPIconvertTimezoneGET /timezone/convertConvert time between two specified timezones
UserAgentAPIgetUserAgentGET /user-agentGet details of user-agent
UserAgentAPIgetBulkUserAgentPOST /user-agent-bulkHandle multiple user-agent string lookups
UserAgentAPIgetUserAgentOfCustomStringPOST /user-agentHandle single User-Agent string

Fields and Methods Availability

IP Geolocation offers four plans from billing point of view: Free, Standard, Security, Advance. The availability of each method calling from the respective class, over all plans are presented below.

ClassMethodFreeStandardSecurityAdvance
IPGeolocationAPIgetIPGeolocationTickTickCrossTick
IPGeolocationAPIgetBulkIPGeolocationCrossTickCrossTick
IPSecurityAPIgetIPSecurityCrossCrossTickCross
IPSecurityAPIgetBulkIPSecurityCrossCrossTickCross
ASNLookupAPIgetAsnDetailsCrossCrossCrossTick
AbuseContactAPIgetAbuseContactInfoCrossCrossCrossTick
AstronomyAPIgetAstronomyTickTickTickTick
TimezoneAPIgetTimezoneTickTickTickTick
TimeConversionAPIconvertTimezoneTickTickTickTick
UserAgentAPIgetUserAgentTickTickTickTick
UserAgentAPIgetBulkUserAgentCrossTickTickTick
UserAgentAPIgetUserAgentOfCustomStringCrossTickTickTick
Tip

The availability of fields in every API endpoint across all API plans is provided in the Reference Table within each respective API Documentation. e.g., for IPGeolocationApi, please visit https://ipgeolocation.io/ip-location-api.html#reference-to-ipgeolocation-api-response.

Authentication Setup

To authenticate API requests, you need an API key from ipgeolocation.io.

1.How to Get Your API Key

  1. Sign up here: https://app.ipgeolocation.io/signup
  2. (optional) Verify your email, if you signed up using email.
  3. Log in to your account: https://app.ipgeolocation.io/login
  4. After logging in, navigate to your Dashboard to find your API key: https://app.ipgeolocation.io/dashboard

2.Setup API Key

Once you've obtained the api key, configure your API client as follows:

Important

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

IP Geolocation Examples

This section provides usage examples of the getIPGeolocation() method from the SDK across Free, Standard, and Advanced subscription tiers. Each example highlights different combinations of parameters: fields , include , and excludes .

Parameters

  • fields : Use this parameter to include specific fields in the response.
  • excludes : Use this parameter to omit specific fields from the response.
  • include : Use this parameter to add optional modules to the response, such as:
    • security
    • user_agent
    • hostname
    • liveHostname
    • hostnameFallbackLive
    • abuse
    • dma
    • time_zone

For complete details, refer to the official documentation: IP Geolocation API Documentation

The ip parameter in the SDK can accept any valid IPv4 address, IPv6 address, or domain name. If the ip() method is not used or the parameter is omitted, the API will return information about the public IP address of the device or server where the SDK is executed.

1.Developer Plan Examples

a.Get Default Fields

Sample Response:

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

Sample Response

2.Standard Plan Examples

a.Get Default Fields

Sample Response:

b.Retrieving Geolocation Data in Multiple Languages

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

Sample Response

c.Include HostName, Timezone and User-Agent

Sample Response

Note

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

a.Include DMA, Abuse and Security

Sample Response:

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.

Note

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.

4.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.

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.

1.Get Security only fields

Sample Response

2.Include Multiple Optional Fields

Note

You can get all the available fields in standard plan in combination with security data, when subscribed to security plan.

3.Request with Field Filtering

Sample Response

4.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.

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

ASN API is only available in the Advanced Plan.

Refer to the ASN API documentation for a detailed list of supported fields and behaviors.

1.Get ASN Information by IP Address

Sample Response

2.Get ASN Information by ASN Number

Sample Response

3.Combine All objects using Include

Sample Response

Abuse Contact API Examples

This section demonstrates how to use the getAbuseContactInfo() method of the AbuseContact API. This API helps security teams, hosting providers, and compliance professionals quickly identify the correct abuse reporting contacts for any IPv4 or IPv6 address. You can retrieve data like the responsible organization, role, contact emails, phone numbers, and address to take appropriate mitigation action against abusive or malicious activity.

Note

Abuse Contact API is only available in the Advanced Plan.

Refer to the official Abuse Contact API documentation for details on all available fields.

1.Lookup Abuse Contact by IP

Sample Response:

2.Lookup Abuse Contact with Specific Fields

Sample Response:

3.Lookup Abuse Contact while Excluding Fields

Sample Response:

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.

1.Get Timezone by IP Address

Sample Response

2.Get Timezone by Timezone Name

Sample Response

3.Get Timezone from Any Address

Sample Response

4.Get Timezone from Location Coordinates

Sample Response

5.Get Timezone and Airport Details from IATA Code

Sample Response

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

6.Get Timezone and City Details from UN/LOCODE

Sample Response

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; coordinates; city; IATA/ICAO code or UN/LOCODE and optional date/time inputs.

For more details, refer to official documentation: Timezone Converter API.

1.Convert Current Time from One Timezone to Another

Sample Response

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.

1.Parse a Basic User Agent String

Sample Response

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

2.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.

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.

1.Lookup Astronomy by Coordinates

Sample Response

2.Lookup Astronomy by IP Address

Sample Response

3.Lookup Astronomy by Location String

Sample Response

4.Lookup Astronomy for Specific Date

Sample Response

5.Lookup Astronomy in Different Language

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

Sample Response

Documentation for Models

Subscribe Our Newsletter

Get the latest in geolocation tech, straight to your inbox.