From 917fb133d23e3e4686abc157752e47797a95e7f2 Mon Sep 17 00:00:00 2001
From: Jacob McKenzie <jacob.mckenzie@smarty.com>
Date: Tue, 3 Mar 2026 11:13:53 -0700
Subject: [PATCH] Added three new fields to the Metadata struct: IANATimeZone
 (string), IANAUTCOffset (float32), and IANADST (bool). These three new fields
 are accessible via setting a new feature flag "iana-timezone"

---
 .../com/smartystreets/api/ClientBuilder.java  | 12 +++++++++
 .../smartystreets/api/us_street/Metadata.java | 20 +++++++++++++--
 .../smartystreets/api/ClientBuilderTest.java  | 25 +++++++++++++++++++
 .../api/us_street/CandidateTest.java          |  6 +++++
 4 files changed, 61 insertions(+), 2 deletions(-)
 create mode 100644 src/test/java/com/smartystreets/api/ClientBuilderTest.java

diff --git a/src/main/java/com/smartystreets/api/ClientBuilder.java b/src/main/java/com/smartystreets/api/ClientBuilder.java
index 88e5488..648cefd 100644
--- a/src/main/java/com/smartystreets/api/ClientBuilder.java
+++ b/src/main/java/com/smartystreets/api/ClientBuilder.java
@@ -209,6 +209,18 @@ public ClientBuilder withFeatureComponentAnalysis() {
         return withCustomCommaSeparatedQuery("features", "component-analysis");
     }
 
+    /**
+     * Adds to the request query to use the IANA timezone feature.
+     * @return Returns <b>this</b> to accommodate method chaining.
+     */
+    public ClientBuilder withFeatureIANATimeZone() {
+        return withCustomCommaSeparatedQuery("features", "iana-timezone");
+    }
+
+    // Package-private for testing
+    Map<String, String> getCustomQueries() {
+        return this.customQueries;
+    }
 
     public com.smartystreets.api.international_street.Client buildInternationalStreetApiClient() {
         this.ensureURLPrefixNotNull(INTERNATIONAL_STREET_API_URL);
diff --git a/src/main/java/com/smartystreets/api/us_street/Metadata.java b/src/main/java/com/smartystreets/api/us_street/Metadata.java
index f1a22e6..af51359 100644
--- a/src/main/java/com/smartystreets/api/us_street/Metadata.java
+++ b/src/main/java/com/smartystreets/api/us_street/Metadata.java
@@ -27,6 +27,9 @@ public class Metadata implements Serializable {
     private String timeZone;
     private double utcOffset;
     private boolean obeysDst;
+    private String ianaTimeZone;
+    private double ianaUtcOffset;
+    private boolean ianaDst;
     private boolean ewsMatch;
 
     //endregion
@@ -106,8 +109,6 @@ public String getTimeZone() {
         return this.timeZone;
     }
 
-    // TODO: Coordinate Licensei
-
     @JsonProperty("utc_offset")
     public double getUtcOffset() {
         return this.utcOffset;
@@ -118,6 +119,21 @@ public boolean obeysDst() {
         return this.obeysDst;
     }
 
+    @JsonProperty("iana_time_zone")
+    public String getIanaTimeZone() {
+        return this.ianaTimeZone;
+    }
+
+    @JsonProperty("iana_utc_offset")
+    public double getIanaUtcOffset() {
+        return this.ianaUtcOffset;
+    }
+
+    @JsonProperty("iana_dst")
+    public boolean isIanaDst() {
+        return this.ianaDst;
+    }
+
     @JsonProperty("ews_match")
     public boolean isEwsMatch() {
         return this.ewsMatch;
diff --git a/src/test/java/com/smartystreets/api/ClientBuilderTest.java b/src/test/java/com/smartystreets/api/ClientBuilderTest.java
new file mode 100644
index 0000000..e8fe7f8
--- /dev/null
+++ b/src/test/java/com/smartystreets/api/ClientBuilderTest.java
@@ -0,0 +1,25 @@
+package com.smartystreets.api;
+
+import org.junit.Test;
+
+import static org.junit.Assert.assertEquals;
+
+public class ClientBuilderTest {
+
+    @Test
+    public void testWithFeatureIANATimeZone() {
+        ClientBuilder builder = new ClientBuilder("id", "token")
+                .withFeatureIANATimeZone();
+
+        assertEquals("iana-timezone", builder.getCustomQueries().get("features"));
+    }
+
+    @Test
+    public void testWithFeatureIANATimeZoneAppendsWhenCombinedWithComponentAnalysis() {
+        ClientBuilder builder = new ClientBuilder("id", "token")
+                .withFeatureComponentAnalysis()
+                .withFeatureIANATimeZone();
+
+        assertEquals("component-analysis,iana-timezone", builder.getCustomQueries().get("features"));
+    }
+}
diff --git a/src/test/java/com/smartystreets/api/us_street/CandidateTest.java b/src/test/java/com/smartystreets/api/us_street/CandidateTest.java
index b5616d8..2b98f82 100644
--- a/src/test/java/com/smartystreets/api/us_street/CandidateTest.java
+++ b/src/test/java/com/smartystreets/api/us_street/CandidateTest.java
@@ -60,6 +60,9 @@ public void testFullJSONDeserialization() throws Exception {
                 + "\"time_zone\": \"Mountain\",\n"
                 + "\"utc_offset\": -7,\n"
                 + "\"dst\": true,\n"
+                + "\"iana_time_zone\": \"America/Denver\",\n"
+                + "\"iana_utc_offset\": -7,\n"
+                + "\"iana_dst\": true,\n"
                 + "\"ews_match\": true\n"
                 + "},\n"
                 + "\"analysis\": {\n"
@@ -168,6 +171,9 @@ public void testFullJSONDeserialization() throws Exception {
         assertEquals("Mountain", candidates[0].getMetadata().getTimeZone());
         assertEquals(-7, candidates[0].getMetadata().getUtcOffset(), 1);
         assertEquals(true, candidates[0].getMetadata().obeysDst());
+        assertEquals("America/Denver", candidates[0].getMetadata().getIanaTimeZone());
+        assertEquals(-7, candidates[0].getMetadata().getIanaUtcOffset(), 1);
+        assertEquals(true, candidates[0].getMetadata().isIanaDst());
         assertEquals(true, candidates[0].getMetadata().isEwsMatch());
         assertEquals("S", candidates[0].getAnalysis().getDpvMatchCode());
         assertEquals("AACCRR", candidates[0].getAnalysis().getDpvFootnotes());