IP Geolocation API Java SDK

Introduction

IPGeolocation API is the solution to identify country code (ISO2 and ISO3 standard), country name, continent code, continent name, country capital, state/province, district, city, zip code, latitude and longitude of city, is country belongs to European Union, calling code, top level domain (TLD), languages, country flag, internet service provider (ISP), connection type, organization, geo name ID, currency code, currency name, time zone ID, time zone offset, current time in the time zone, is time zone in daylight saving time, total daylight savings and user agent details. This document provides important information to help you get up to speed with IPGeolocation API using IP Geolocation API Java SDK.

Developers can use this Java SDK for software and web projects related to, but not limited to:

Display native language and currency
Redirect based on the country
Digital rights management
Web log stats and analysis
Auto-selection of country, state/province and city on forms
Filter access from countries you do not do business with
Geo-targeting for increased sales and click-through

Quick Start Guide

You need a valid 'IPGeolocation API key' to use this SDK. Sign up here and get your free API key if you don’t have one.

Note: Complete documentation to use this SDK is also available at IP Geolocation API Website .

System Requirements

IP Geolocation API Java SDK has been developed and tested on JDK version 8.
Note: Internet connection is required to run this component.

Installation

Our Java SDK can be installed by various methods given below:

Maven

Add the following dependency in 'pom.xml' file to use the IP Geolocation API Java SDK.

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

Gradle

Add the following dependency in 'build.gradle' file to use the IP Geolocation API Java SDK.

implementation 'io.ipgeolocation:ipgeolocation:1.0.16'

Ivy

Add the following dependency code in 'ivy.xml' file to use the IP Geolocation API Java SDK.

<dependency org="io.ipgeolocation" name="ipgeolocation" rev="1.0.16"/>

JAR File

Use the following URL to download the latest JAR file for IP Geolocation API Java SDK.

https://ipgeolocation.io/downloads/ip-geolocation-api-java-1.0.16.jar

Documentation

Use the following URL to visit documentation

https://ipgeolocation.io/documentation.html

Basic Usage

Setup API

// Create IPGeolocationAPI object, passing your valid API key
IPGeolocationAPI ipGeolocationAPI = new IPGeolocationAPI("YOUR_API_KEY");

Geolocation Lookup

// Get geolocation for IP address (1.1.1.1) and fields (geo, time_zone and currency)
GeolocationParams geolocationParams =
        GeolocationParams.builder()
            .withIPAddress("1.1.1.1")
            .withFields("geo,time_zone,currency")
            .includeSecurity()
            .build();

try {
    Geolocation geolocation = ipGeolocationAPI.getGeolocation(geolocationParams);

    // Geolocation Info
    System.out.println("Country: " + geolocation.getCountryName());
    System.out.println("Currency: " + geolocation.getCurrency().getName());
    System.out.println("Location time: " + geolocation.getTimezone().getCurrentTime());

    // Security Info
    System.out.println("Is Anonymous: " + geolocation.getGeolocationSecurity().isAnonymous());
    System.out.println("Is Known Attacker: " + geolocation.getGeolocationSecurity().isKnownAttacker());
    System.out.println("Is Proxy: " + geolocation.getGeolocationSecurity().isProxy());
    System.out.println("Proxy Type: " + geolocation.getGeolocationSecurity().getProxyType());
    System.out.println("IP Threat Score: " + geolocation.getGeolocationSecurity().getThreatScore());
    System.out.println("Is Bot: " + geolocation.getGeolocationSecurity().isBot());
    System.out.println("Is Spam: " + geolocation.getGeolocationSecurity().isSpam());
    System.out.println("Is Tor: " + geolocation.getGeolocationSecurity().isTor());
    System.out.println("Is Cloud Provider: " + geolocation.getGeolocationSecurity().isCloudProvider());
} catch (IPGeolocationError e) {
    // on unsuccessful lookup or invalid input IPGeolocationError is thrown
    System.err.println("HTTP status: " + e.getStatus() + " Error: " + e.getMessage());
}

// Get geolocation in Russian** for IP address (1.1.1.1) and all fields
GeolocationParams geolocationParams =
        GeolocationParams.builder()
            .withIPAddress("1.1.1.1")
            .withLang("ru")
            .build();

try {
    Geolocation geolocation = ipGeolocationAPI.getGeolocation(geolocationParams);

    System.out.println("IP Address: " + geolocation.getIP());
    System.out.println("Country: " + geolocation.getCountryName());
} catch (IPGeolocationError e) {
    // on unsuccessful lookup or invalid input IPGeolocationError is thrown
    System.err.println("HTTP status: " + e.getStatus() + " Error: " + e.getMessage());
}

// Get geolocation for the calling machine's IP address for all fields
try {
    Geolocation geolocation = ipGeolocationAPI.getGeolocation();

    System.out.println("IP Address: " + geolocation.getIP());
    System.out.println("Country Code ISO2: " + geolocation.getCountryCode2());
    System.out.println("Location time: " + geolocation.getTimezone().getCurrentTime());
} catch (IPGeolocationError e) {
    // on unsuccessful lookup or invalid input IPGeolocationError is thrown
    System.err.println("HTTP status: " + e.getStatus() + " Error: " + e.getMessage());
}

Bulk Geolocations Lookup

// Query geolocation in German** for multiple IP addresses and all fields
String[] ips = new String[]{"1.1.1.1", "2.2.2.2", "3.3.3.3"};
GeolocationParams geolocationParams =
        GeolocationParams.builder()
            .withLang("de")
            .build();

try {
    List<Geolocation> geolocations = ipGeolocationAPI.getBulkGeolocation(ips, geolocationParams);

    System.out.println("No. of Requests: " + geolocations.size());
    System.out.println("1st IP's Country: " + geolocations.get(0).getCountryName());
    System.out.println("2nd IP's Language: " + geolocations.get(1).getLanguages());
    System.out.println("3rd IP's location time: " + geolocations.get(2).getTimezone().getCurrentTime());
} catch (IPGeolocationError e) {
    // on unsuccessful lookup or invalid input IPGeolocationError is thrown
    System.err.println("HTTP status: " + e.getStatus() + " Error: " + e.getMessage());
}

// Query geolocations for multiple IP addresses but only geo field
String[] ips = new String[]{"1.1.1.1", "2.2.2.2", "3.3.3.3"};
GeolocationParams geolocationParams =
        GeolocationParams.builder()
            .withFields("geo")
            .build();

try {
    List<Geolocation> geolocations = ipGeolocationAPI.getBulkGeolocation(ips, geolocationParams);

    System.out.println("No. of Requests: " + geolocations.size());
    System.out.println("1st IP's Country: " + geolocations.get(0).getCountryName());
    System.out.println("2nd IP's City: "+geolocations.get(1).getCity());
    System.out.println("3rd IP's City Zipcode: " + geolocations.get(2).getZipCode());
} catch (IPGeolocationError e) {
    // on unsuccessful lookup or invalid input IPGeolocationError is thrown
    System.err.println("HTTP status: " + e.getStatus() + " Error: " + e.getMessage());
}

Timezone API

// Get time zone information by time zone ID
TimezoneParams timezoneParams =
        TimezoneParams.builder().withTimeZone("America/New_York").build();

try {
    Timezone tz = ipGeolocationAPI.getTimezone(timezoneParams);
    
    System.out.println("Format 'EEEE, MMMM dd, yyyy HH:mm:ss': " + tz.getDateTimeTxt());
    System.out.println("Format 'EEE, dd MMM yyyy HH:mm:ss Z': " + tz.getDateTimeWti());
} catch (IPGeolocationError e) {
    // on unsuccessful lookup or invalid input IPGeolocationError is thrown
    System.err.println("HTTP status: " + e.getStatus() + " Error: " + e.getMessage());
}

// Get time zone information by coordinates (latitude and longitude) of the location
TimezoneParams timezoneParams =
        TimezoneParams.builder()
            .withCoordinates(BigDecimal.valueOf(37.1838139), BigDecimal.valueOf(-123.8105225))
            .build();

try {
    Timezone tz = ipGeolocationAPI.getTimezone(timezoneParams);

    System.out.println("Timezone: " + tz.getTimezone());
    System.out.println("Timezone in Unix: " + tz.getDateTimeUnix());
    System.out.println("Time in 24 format: " + tz.getTime24());
} catch (IPGeolocationError e) {
    // on unsuccessful lookup or invalid input IPGeolocationError is thrown
    System.err.println("HTTP status: " + e.getStatus() + " Error: " + e.getMessage());
}

// Get time zone information for IP address (1.1.1.1) and geolocation information in Japanese**
TimezoneParams timezoneParams =
        TimezoneParams.builder()
            .withIPAddress("1.1.1.1")
            .withLang("ja")
            .build();

try {
    Timezone tz = ipGeolocationAPI.getTimezone(timezoneParams);

    // Timezone Info
    System.out.println("Timezone: " + tz.getTimezone());
    System.out.println("Format 'EEEE, MMMM dd, yyyy HH:mm:ss': " + tz.getDateTimeTxt());
    System.out.println("Format 'yyyy-MM-dd'T'HH:mm:ssZ': " + tz.getDateTimeYmd());

    // Geo Info
    System.out.println("City: " + tz.getGeo().getCity());
    System.out.println("State/Province: " + tz.getGeo().getStateProvince());
    System.out.println("Country: " + tz.getGeo().getCountryName());
} catch (IPGeolocationError e) {
    // on unsuccessful lookup or invalid input IPGeolocationError is thrown
    System.err.println("HTTP status: " + e.getStatus() + " Error: " + e.getMessage());
}

// Query time zone information for calling machine's IP address
try {
    Timezone tz = ipGeolocationAPI.getTimezone();

    // Timezone Info
    System.out.println("Timezone Offset: " + tz.getTimezoneOffset());
    System.out.println("Date: " + tz.getDate());
    System.out.println("Month (No.): " + tz.getMonth());

    // Geo Info
    System.out.println("City: " + tz.getGeo().getCity());
    System.out.println("Country Code ISO3: " + tz.getGeo().getCountryCode3());
    System.out.println("Lat/Lon: " + tz.getGeo().getLatitude() + "/" + tz.getGeo().getLongitude());
} catch (IPGeolocationError e) {
    // on unsuccessful lookup or invalid input IPGeolocationError is thrown
    System.err.println("HTTP status: " + e.getStatus() + " Error: " + e.getMessage());
}

// Get time zone information by location (city, country, etc.)
TimezoneParams timezoneParams = 
        TimezoneParams.builder().withLocation("Syria, Damascus").build();

try {
    Timezone tz = ipGeolocationAPI.getTimezone(timezoneParams);

    System.out.println("Format 'EEEE, MMMM dd, yyyy HH:mm:ss': " + tz.getDateTimeTxt());
    System.out.println("Country: " + tz.getGeo().getCountryName());
} catch (IPGeolocationError e) {
    // on unsuccessful lookup or invalid input IPGeolocationError is thrown
    System.err.println("HTTP status: " + e.getStatus() + " Error: " + e.getMessage());
}

UserAgent API

// Query/Parse user agent information for Provided the provided string
try {
    String uaString = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_2) AppleWebKit/601.3.9 (KHTML, like Gecko) Version/9.0.2 Safari/601.3.9";
    UserAgent ua = ipGeolocationAPI.getUserAgent(uaString);

    System.out.println("Device name: " + ua.getDevice().getName());
    System.out.println("OS name: " + ua.getOperatingSystem().getName());
    System.out.println("OS version: " + ua.getOperatingSystem().getVersion());
    System.out.println("CPU: " + ua.getDevice().getCpu());
} catch (IPGeolocationError e) {
    // on unsuccessful lookup or invalid input IPGeolocationError is thrown
    System.err.println("HTTP status: " + e.getStatus() + " Error: " + e.getMessage());
}

// Query/Parse user agent information for the provided strings
String[] uaStrings = new String[]
        {"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_2) AppleWebKit/601.3.9 (KHTML, like Gecko) Version/9.0.2 Safari/601.3.9",
                "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.111 Safari/537.36",
                "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:40.0) Gecko/20100101 Firefox/40.1"};

try {
    List<UserAgent> uas = ipGeolocationAPI.getBulkUserAgent(uaStrings);

    System.out.println("No. of Requests: " + uas.size());
    System.out.println("1st UA's Device name: " + uas.get(0).getDevice().getName());
    System.out.println("2nd UA's OS name: " + uas.get(1).getOperatingSystem().getName());
    System.out.println("3rd UA's Browser: " + uas.get(2).getName());
} catch (IPGeolocationError e) {
    System.err.println("HTTP status: " + e.getStatus() + " Error: " + e.getMessage());
}

// Query useragent of the machine IP Address along with Geolocation
GeolocationParams geolocationParams = 
        GeolocationParams.builder()
                .includeUserAgentDetail()
               .build();
try {
    Geolocation geolocation = ipGeolocationAPI.getGeolocation(geolocationParams);

    System.out.println("IP: " + geolocation.getIP());
    System.out.println("City: " + geolocation.getCity());
    System.out.println("UserAgent OS: " + geolocation.getUserAgent().getOperatingSystem().getName());
    System.out.println("UserAgent Browser:" + geolocation.getUserAgent().getName());
    System.out.println("UserAgent Device: " + geolocation.getUserAgent().getDevice().getName());

} catch (IPGeolocationError e) {
    // on unsuccessful lookup or invalid input IPGeolocationError is thrown
    System.err.println("HTTP status: " + e.getStatus() + " Error: " + e.getMessage());
}

Astronomy API

// Query astronomy information for location (city, country, etc.)
AstronomyParams astronomyParams =
        AstronomyParams.builder()
                .withLocation("Amsterdam, Netherlands")
                .build();

try {
    Astronomy astronomy = ipGeolocationAPI.getAstronomy(astronomyParams);

    System.out.println("City: " + astronomy.getLocation().getCity());
    System.out.println("Country: " + astronomy.getLocation().getCountryName());
    System.out.println("Locality: " + astronomy.getLocation().getLocality());

    System.out.println("Sun Distance: " + astronomy.getSunDistance());
    System.out.println("Sun Altitude: " + astronomy.getSunAltitude());
    System.out.println("Day length: " + astronomy.getDayLength());
} catch (IPGeolocationError e) {
    // on unsuccessful lookup or invalid input IPGeolocationError is thrown
    System.err.println("HTTP status: " + e.getStatus() + " Error: " + e.getMessage());
}

// Query astronomy information for given geo coordinates (latitude/longitude)
AstronomyParams astronomyParams = 
        AstronomyParams.builder()
                .withCoordinates(BigDecimal.valueOf(51.507277), BigDecimal.valueOf(-0.1290644))
                .withDate("2024-02-29")
                .build();

try {
    Astronomy astronomy = ipGeolocationAPI.getAstronomy(astronomyParams);

    System.out.println("Lat/Lon: " + astronomy.getLocation().getLatitude() + "/" + astronomy.getLocation().getLongitude());

    System.out.println("Date: " + astronomy.getDate());
    System.out.println("Moonset: " + astronomy.getMoonset());
    System.out.println("Sun Azimuth: " + astronomy.getSunAzimuth());
} catch (IPGeolocationError e) {
    // on unsuccessful lookup or invalid input IPGeolocationError is thrown
    System.err.println("HTTP status: " + e.getStatus() + " Error: " + e.getMessage());
}

// Query astronomy information for machine IP
try {
    Astronomy astronomy = ipGeolocationAPI.getAstronomy();

    System.out.println("Zipcode: " + astronomy.getLocation().getCity());
    System.out.println("State code: " + astronomy.getLocation().getStateCode());
    System.out.println("City: " + astronomy.getLocation().getCity());

    System.out.println("Sunrise: " + astronomy.getSunrise());
    System.out.println("Sunset: " + astronomy.getSunset());
    System.out.println("Moonrise: " + astronomy.getMoonrise());
} catch (IPGeolocationError e) {
    // on unsuccessful lookup or invalid input IPGeolocationError is thrown
    System.err.println("HTTP status: " + e.getStatus() + " Error: " + e.getMessage());
}

// Query astronomy information for specific IP in Chinese Language
AstronomyParams astronomyParams = AstronomyParams.builder()
        .withIPAddress("1.1.1.1")
        .withLang("cn")
        .build();

try {
    Astronomy astronomy = ipGeolocationAPI.getAstronomy(astronomyParams);

    System.out.println("Zipcode: " + astronomy.getLocation().getCity());
    System.out.println("Country Name: " + astronomy.getLocation().getCountryName());

    System.out.println("Sun distance: " + astronomy.getSunDistance());
    System.out.println("Moonrise: " + astronomy.getMoonrise());
    System.out.println("Moon Parallactic Angle: " + astronomy.getMoonParallacticAngle());
} catch (IPGeolocationError e) {
    // on unsuccessful lookup or invalid input IPGeolocationError is thrown
    System.err.println("HTTP status: " + e.getStatus() + " Error: " + e.getMessage());
}

Time Conversion API

// Convert time using timezone ID with the provided time
TimezoneConvertParams timezoneConvertParams =
        TimezoneConvertParams.builder()
                .withTimeZone("America/New_York", "Asia/Karachi")
                .withDateTime("2024-02-29 16:40")
                .build();

try {
    TimezoneConvert tzConverted = ipGeolocationAPI.convertTimeZone(timezoneConvertParams);

    System.out.println("Original time: " + tzConverted.getOriginalTime());
    System.out.println("Converted time: " + tzConverted.getConvertedTime());
    System.out.println("Difference in hours: " + tzConverted.getDiffHour());
}catch (IPGeolocationError e) {
    // on unsuccessful lookup or invalid input IPGeolocationError is thrown
    System.err.println("HTTP status: " + e.getStatus() + " Error: " + e.getMessage());
}

// Convert time using locations with current time
TimezoneConvertParams timezoneConvertParams =
        TimezoneConvertParams.builder()
                .withLocation("Lahore, Pakistan", "London, United Kingdom")
                .build();

try {
    TimezoneConvert tzConverted = ipGeolocationAPI.convertTimeZone(timezoneConvertParams);

    System.out.println("Original time: " + tzConverted.getOriginalTime());
    System.out.println("Converted time: " + tzConverted.getConvertedTime());
    System.out.println("Difference in minutes: " + tzConverted.getDiffMin());
}catch (IPGeolocationError e) {
    // on unsuccessful lookup or invalid input IPGeolocationError is thrown
    System.err.println("HTTP status: " + e.getStatus() + " Error: " + e.getMessage());
}

// Convert time using Geo Coordinates of locations with the provided time
TimezoneConvertParams timezoneConvertParams =
        TimezoneConvertParams.builder()
                .withCoordinates(
                        BigDecimal.valueOf(31.522165), BigDecimal.valueOf(74.358422),
                        BigDecimal.valueOf(38.907084), BigDecimal.valueOf(-77.03449))
                .withDateTime("2024-02-29 16:40:40")
                .build();

try {
    TimezoneConvert tzConverted = ipGeolocationAPI.convertTimeZone(timezoneConvertParams);

    System.out.println("Original time: " + tzConverted.getOriginalTime());
    System.out.println("Converted time: " + tzConverted.getConvertedTime());
    System.out.println("Difference in hours: " + tzConverted.getDiffHour());
}catch (IPGeolocationError e) {
    // on unsuccessful lookup or invalid input IPGeolocationError is thrown
    System.err.println("HTTP status: " + e.getStatus() + " Error: " + e.getMessage());
}

** IPGeolocation provides geolocation information in the following languages:

English (en)
German (de)
Russian (ru)
Japanese (ja)
French (fr)
Chinese Simplified (cn)
Spanish (es)
Czech (cs)
Italian (it)

By default, geolocation information is returned into English. Response in a language other than English is available to paid users only.