IP Geolocation API Java SDK

In this document, you will go through the basic steps to use IP Geolocation API Java SDK.
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.

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.12</version>
</dependency>

Gradle

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

repositories {
...
maven { url "http://dl.bintray.com/ipgeolocation/ipgeolocation" }
}

dependencies {
compile 'io.ipgeolocation:ipgeolocation:1.0.12'
...
}

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.12'>
<artifact name='ipgeolocation' />
</dependency>

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.12.jar

Basic Usage

Setup API

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

Geolocation Lookup

// Get geolocation for IP address (1.1.1.1) and fields (geo, time_zone and currency)
GeolocationParams geoParams = new GeolocationParams();
geoParams.setIPAddress("1.1.1.1");
geoParams.setFields("geo,time_zone,currency");

Geolocation geolocation = api.getGeolocation(geoParams);

// Check if geolocation lookup was successful
if(geolocation.getStatus() == 200) {
    System.out.println(geolocation.getCountryName());
    System.out.println(geolocation.getCurrency().getName());
    System.out.println(geolocation.getTimezone().getCurrentTime());
} else {
    System.out.printf("Status Code: %d, Message: %s\n", geolocation.getStatus(), geolocation.getMessage());
}

// Get geolocation in Russian** for IP address (1.1.1.1) and all fields
GeolocationParams geoParams = new GeolocationParams();
geoParams.setIPAddress("1.1.1.1");
geoParams.setLang("ru");

Geolocation geolocation = api.getGeolocation(geoParams);

// Check if geolocation lookup was successful
if(geolocation.getStatus() == 200) {
    System.out.println(geolocation.getIPAddress());
    System.out.println(geolocation.getCountryName());
} else {
    System.out.printf("Status Code: %d, Message: %s\n", geolocation.getStatus(), geolocation.getMessage());
}

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

if(geolocation.getStatus() == 200) {
    System.out.println(geolocation.getCountryCode2());
    System.out.println(geolocation.getTimezone().getCurrentTime());
} else {
    System.out.printf("Status Code: %d, Message: %s\n", geolocation.getStatus(), geolocation.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 geoParams = new GeolocationParams();
geoParams.setIPAddresses(ips);
geoParams.setLang("de");

List<Geolocation> geolocations = api.getBulkGeolocation(geoParams);

System.out.println(geolocations.size());
System.out.println(geolocations.get(0).getCountryName());
System.out.println(geolocations.get(1).getLanguages());
System.out.println(geolocations.get(2).getTimezone().getCurrentTime());

// 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 geoParams = new GeolocationParams();
geoParams.setIPAddresses(ips);
geoParams.setFields("geo");

List<Geolocation> geolocations = api.getBulkGeolocation(geoParams);

System.out.println(geolocations.size());
System.out.println(geolocations.get(0).getCountryCode2());
System.out.println(geolocations.get(1).getCountryName());
System.out.println(geolocations.get(2).getLatitude());

Timezone API

// Get time zone information by time zone ID
TimezoneParams tzParams = new TimezoneParams();
tzParams.setTimezone("America/New_York");

Timezone tz = api.getTimezone(tzParams);

if(tz.getStatus() == 200) {
    System.out.println(tz.getDateTimeWti());
    System.out.println(tz.getDateTimeTxt());
} else {
    System.out.printf("Status Code: %d, Message: %s\n", geolocation.getStatus(), geolocation.getMessage());
}

// Get time zone information by latitude and longitude of the location
TimezoneParams tzParams = new TimezoneParams();
tzParams.setLocation(37.1838139, -123.8105225);

Timezone tz = api.getTimezone(tzParams);

if(tz.getStatus() == 200) {
    System.out.println(tz.getTimezone());
} else {
    System.out.printf("Status Code: %d, Message: %s\n", geolocation.getStatus(), geolocation.getMessage());
}

// Get time zone information for IP address (1.1.1.1) and geolocation information Japanese**
TimezoneParams tzParams = new TimezoneParams();
tzParams.setIPAddress("1.1.1.1");
tzParams.setLang("ja");

Timezone tz = api.getTimezone(tzParams);

if(tz.getStatus() == 200) {
    System.out.println(tz.getTimezone());
} else {
    System.out.printf("Status Code: %d, Message: %s\n", geolocation.getStatus(), geolocation.getMessage());
}

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

if(tz.getMessage()) {
    System.out.println(tz.getTimezone());
    System.out.println(tz.getDateTimeYmd());
} else {
    System.out.printf("Status Code: %d, Message: %s\n", geolocation.getStatus(), geolocation.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 in English. Response in a language other than English is available to paid users only.

IP Geolocation API Java SDK Objects Reference

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

Class: io.ipgeolocation.api.IPGeolocationAPI

Class: io.ipgeolocation.api.GeolocationParams

Class: io.ipgeolocation.api.Geolocation

Class: io.ipgeolocation.api.GeolocationCurrency

Class: io.ipgeolocation.api.GeolocationTimezone

Class: io.ipgeolocation.api.TimezoneParams

Class: io.ipgeolocation.api.Timezone

Class: io.ipgeolocation.api.TimezoneGeo

Source Code

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