added support for time conversion using timezone/convert API

Author: DaudAhmadJF

src/main/java/io/ipgeolocation/api/IPGeolocationAPI.java

@@ -193,6 +193,37 @@ public Timezone getTimezone(TimezoneParams params) {
     return timezone;
   }
 
+  /**
+   * Converts a time from one timezone to another using the IP Geolocation API.
+   *
+   * @param params The parameters for timezone conversion, including the source and target timezones,
+   *               as well as the time to convert.
+   * @return A {@code TimezoneConvert} object representing the converted time.
+   * @throws IPGeolocationError If an error occurs during the timezone conversion process,
+   *                            such as an invalid API response or parameters.
+   * @see TimezoneConvertParams
+   * @see TimezoneConvert
+   */
+  public TimezoneConvert convertTimeZone(TimezoneConvertParams params) {
+    final JSONObject apiResponse =
+        (JSONObject)
+            callAPIEndpoint(
+                "timezone/convert",
+                buildTimezoneConvertUrlParams(params),
+                "GET",
+                null,
+                false);
+    final TimezoneConvert timezoneConvert;
+
+    try {
+      timezoneConvert = new TimezoneConvert(apiResponse);
+    } catch (IllegalArgumentException e) {
+      throw new IPGeolocationError(e);
+    }
+
+    return timezoneConvert;
+  }
+
   /**
    * Retrieves user-agent information based on the provided user-agent string.
    *
@@ -398,6 +429,51 @@ private String buildTimezoneUrlParams(final TimezoneParams params) {
     return urlParams.toString();
   }
 
+  private String buildTimezoneConvertUrlParams(final TimezoneConvertParams params) {
+    final StringBuilder urlParams = new StringBuilder();
+
+    urlParams.append("apiKey=");
+    urlParams.append(apiKey);
+
+    if (!Objects.isNull(params)) {
+      if ((!Strings.isNullOrEmpty(params.getTimezoneFrom())) && (!Strings.isNullOrEmpty(params.getTimezoneTo()))) {
+        urlParams.append("&tz_from=");
+        urlParams.append(params.getTimezoneFrom());
+
+        urlParams.append("&tz_to=");
+        urlParams.append(params.getTimezoneTo());
+      }
+
+      if ((!Objects.isNull(params.getLatitudeFrom()) && !Objects.isNull(params.getLongitudeFrom()))
+              && ((!Objects.isNull(params.getLatitudeTo()) && !Objects.isNull(params.getLongitudeTo())))) {
+        urlParams.append("&lat_from=");
+        urlParams.append(params.getLatitudeFrom());
+        urlParams.append("&long_from=");
+        urlParams.append(params.getLongitudeFrom());
+
+        urlParams.append("&lat_to=");
+        urlParams.append(params.getLatitudeTo());
+        urlParams.append("&long_to=");
+        urlParams.append(params.getLongitudeTo());
+      }
+
+      if ((!Strings.isNullOrEmpty(params.getLocationFrom())) && (!Strings.isNullOrEmpty(params.getLocationTo()))) {
+        urlParams.append("&location_from=");
+        urlParams.append(params.getLocationFrom());
+
+        urlParams.append("&location_to=");
+        urlParams.append(params.getLocationTo());
+      }
+
+      if (!Strings.isNullOrEmpty(params.getTime())) {
+        urlParams.append("&time=");
+        urlParams.append(params.getTime());
+      }
+    }
+
+    return urlParams.toString();
+  }
+
   private String buildAstronomyUrlParams(final AstronomyParams params) {
     final StringBuilder urlParams = new StringBuilder();
 

src/main/java/io/ipgeolocation/api/TimezoneConvert.java

@@ -0,0 +1,91 @@
+package io.ipgeolocation.api;
+
+import org.json.JSONObject;
+
+import java.math.BigDecimal;
+import java.util.Objects;
+
+/**
+ * The TimezoneConvert class represents the result of a timezone conversion, including the original time, converted time,
+ * and the difference in hours and minutes between the two timezones.
+ *
+ * <p>The TimezoneConvert class provides methods to access the information stored in the TimezoneConvert object.
+ * For example, you can use the {@link #getConvertedTime()} method to get the converted time.
+ */
+public class TimezoneConvert {
+    private final String originalTime;
+    private final String convertedTime;
+    private final BigDecimal diffHour;
+    private final BigDecimal diffMin;
+    private final JSONObject json;
+
+    /**
+     * Constructs a new TimezoneConvert object with the given JSON data.
+     *
+     * @param json The JSON object containing the timezone conversion information.
+     * @throws IllegalArgumentException If the provided JSON object is null or empty.
+     */
+    TimezoneConvert(JSONObject json) {
+        if (Objects.isNull(json)) {
+            throw new IllegalArgumentException("'json' must not be null");
+        }
+
+        if (json.isEmpty()) {
+            throw new IllegalArgumentException("'json' must not be empty");
+        }
+
+        this.originalTime = json.optString("original_time");
+        this.convertedTime = json.optString("converted_time");
+        this.diffHour = json.getBigDecimal("diff_hour");
+        this.diffMin = json.getBigDecimal("diff_min");
+
+        this.json = json;
+    }
+
+    /**
+     * Returns the DateTime for which conversion is performed, if the time is not provided,
+     * the time of request will return.
+     *
+     * @return Queried time or request time as a string.
+     */
+    public String getOriginalTime() {
+        return originalTime;
+    }
+
+    /**
+     * Returns the dateTime after conversion to the target timezone/location.
+     *
+     * @return The converted dateTime as a string.
+     */
+    public String getConvertedTime() {
+        return convertedTime;
+    }
+
+    /**
+     * Gets the difference in hours between the original and converted timezones.
+     *
+     * @return The difference in hours as a {@code BigDecimal}.
+     */
+    public BigDecimal getDiffHour() {
+        return diffHour;
+    }
+
+    /**
+     * Gets the difference in minutes between the original and converted timezones.
+     *
+     * @return The difference in minutes as a {@code BigDecimal}.
+     */
+    public BigDecimal getDiffMin() {
+        return diffMin;
+    }
+
+    /**
+     * Returns a string representation of the TimezoneConvert object, formatted JSON.
+     *
+     * @return A string containing the JSON representation of the timezone conversion result.
+     */
+    @Override
+    public String toString() {
+        return json.toString(2);
+    }
+}