✨ add support for full address fields (#244)

sebastianMindee · web-flow · commit 7e106bc6230d · 2025-06-02T15:39:23.000+02:00
diff --git a/docs/financial_document_v1.md b/docs/financial_document_v1.md
@@ -107,12 +107,12 @@ public class SimpleMindeeClient {
 ########
 Document
 ########
-:Mindee ID: f52333ab-811e-4647-993e-ad79e072afa3
+:Mindee ID: 6dd26385-719b-4527-bf6f-87d9da619de5
 :Filename: default_sample.jpg
 
 Inference
 #########
-:Product: mindee/financial_document v1.12
+:Product: mindee/financial_document v1.14
 :Rotation applied: Yes
 
 Prediction
@@ -237,6 +237,21 @@ A typical `BaseField` object will have the following attributes:
 
 Aside from the previous attributes, all basic fields have access to a custom `toString` method that can be used to print their value as a string.
 
+
+### AddressField
+Aside from the basic `BaseField` attributes, the address field `AddressField` also implements the following:
+
+* **streetNumber** (`string`): String representation of the string number. Can be `null`.
+* **streetName** (`string`): Name of the street. Can be `null`.
+* **poBox** (`string`): String representation of the PO Box number. Can be `null`.
+* **addressComplement** (`string`): Address complement. Can be `null`.
+* **city** (`string`): City name. Can be `null`.
+* **postalcode** (`string`): String representation of the postal code. Can be `null`.
+* **state** (`string`): State name. Can be `null`.
+* **country** (`string`): Country name. Can be `null`.
+
+Note: The `value` field of an AddressField should be a concatenation of the rest of the values.
+
 ### AmountField
 An amount field `AmountField` extends `BaseField`, but also implements:
 * **value** (`Double`): corresponds to the field value. Can be `null` if no value was extracted.
diff --git a/docs/invoices_v4.md b/docs/invoices_v4.md
@@ -107,12 +107,12 @@ public class SimpleMindeeClient {
 ########
 Document
 ########
-:Mindee ID: 3e524d26-f7dc-4852-9bbf-833a127a9570
+:Mindee ID: 744748d5-9051-461c-b70c-bbf81f5ff943
 :Filename: default_sample.jpg
 
 Inference
 #########
-:Product: mindee/invoices v4.10
+:Product: mindee/invoices v4.11
 :Rotation applied: Yes
 
 Prediction
@@ -148,6 +148,8 @@ Prediction
 :Billing Address: 1954 Bloor Street West Toronto, ON, M6P 3K9 Canada
 :Document Type: INVOICE
 :Document Type Extended: INVOICE
+:Purchase Subcategory:
+:Purchase Category: miscellaneous
 :Line Items:
   +--------------------------------------+--------------+----------+------------+--------------+--------------+-----------------+------------+
   | Description                          | Product code | Quantity | Tax Amount | Tax Rate (%) | Total Amount | Unit of measure | Unit Price |
@@ -195,6 +197,8 @@ Page 0
 :Billing Address: 1954 Bloor Street West Toronto, ON, M6P 3K9 Canada
 :Document Type: INVOICE
 :Document Type Extended: INVOICE
+:Purchase Subcategory:
+:Purchase Category: miscellaneous
 :Line Items:
   +--------------------------------------+--------------+----------+------------+--------------+--------------+-----------------+------------+
   | Description                          | Product code | Quantity | Tax Amount | Tax Rate (%) | Total Amount | Unit of measure | Unit Price |
@@ -225,6 +229,21 @@ A typical `BaseField` object will have the following attributes:
 
 Aside from the previous attributes, all basic fields have access to a custom `toString` method that can be used to print their value as a string.
 
+
+### AddressField
+Aside from the basic `BaseField` attributes, the address field `AddressField` also implements the following:
+
+* **streetNumber** (`string`): String representation of the string number. Can be `null`.
+* **streetName** (`string`): Name of the street. Can be `null`.
+* **poBox** (`string`): String representation of the PO Box number. Can be `null`.
+* **addressComplement** (`string`): Address complement. Can be `null`.
+* **city** (`string`): City name. Can be `null`.
+* **postalcode** (`string`): String representation of the postal code. Can be `null`.
+* **state** (`string`): State name. Can be `null`.
+* **country** (`string`): Country name. Can be `null`.
+
+Note: The `value` field of an AddressField should be a concatenation of the rest of the values.
+
 ### AmountField
 An amount field `AmountField` extends `BaseField`, but also implements:
 * **value** (`Double`): corresponds to the field value. Can be `null` if no value was extracted.
diff --git a/docs/us_healthcare_cards_v1.md b/docs/us_healthcare_cards_v1.md
@@ -60,17 +60,18 @@ public class SimpleMindeeClient {
 ########
 Document
 ########
-:Mindee ID: 1e71d5f0-dedb-4070-9d94-9207cd9570b5
+:Mindee ID: 5e917fc8-5c13-42b2-967f-954f4eed9959
 :Filename: default_sample.jpg
 
 Inference
 #########
-:Product: mindee/us_healthcare_cards v1.2
+:Product: mindee/us_healthcare_cards v1.3
 :Rotation applied: Yes
 
 Prediction
 ==========
 :Company Name: UnitedHealthcare
+:Plan Name: Choice Plus
 :Member Name: SUBSCRIBER SMITH
 :Member ID: 123456789
 :Issuer 80840:
@@ -84,14 +85,14 @@ Prediction
 :RX ID:
 :RX GRP: UHEALTH
 :RX PCN: 9999
-:copays:
+:Copays:
   +--------------+----------------------+
   | Service Fees | Service Name         |
   +==============+======================+
-  | 300.00       | emergency_room       |
-  +--------------+----------------------+
   | 20.00        | office_visit         |
   +--------------+----------------------+
+  | 300.00       | emergency_room       |
+  +--------------+----------------------+
   | 75.00        | urgent_care          |
   +--------------+----------------------+
   | 30.00        | specialist           |
diff --git a/src/main/java/com/mindee/parsing/standard/AddressField.java b/src/main/java/com/mindee/parsing/standard/AddressField.java
@@ -0,0 +1,96 @@
+package com.mindee.parsing.standard;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
+import com.mindee.geometry.Polygon;
+import com.mindee.geometry.PolygonDeserializer;
+import lombok.Getter;
+
+/**
+ * Represent a postal address field broken down into its individual components.
+ */
+@Getter
+@JsonIgnoreProperties(ignoreUnknown = true)
+public final class AddressField extends StringField {
+  /** The address exactly as it appears on the document. */
+  private final String rawValue;
+
+  /** Street number. */
+  private final String streetNumber;
+
+  /** Street name. */
+  private final String streetName;
+
+  /** PO-box number. */
+  private final String poBox;
+
+  /** Additional address complement. */
+  private final String addressComplement;
+
+  /** City or locality. */
+  private final String city;
+
+  /** Postal or ZIP code. */
+  private final String postalCode;
+
+  /** State, province or region. */
+  private final String state;
+
+  /** Country. */
+  private final String country;
+
+  public AddressField(
+      @JsonProperty("value")
+      String value,
+      @JsonProperty("raw_value")
+      String rawValue,
+      @JsonProperty("street_number")
+      String streetNumber,
+      @JsonProperty("street_name")
+      String streetName,
+      @JsonProperty("po_box")
+      String poBox,
+      @JsonProperty("address_complement")
+      String addressComplement,
+      @JsonProperty("city")
+      String city,
+      @JsonProperty("postal_code")
+      String postalCode,
+      @JsonProperty("state")
+      String state,
+      @JsonProperty("country")
+      String country,
+      @JsonProperty("confidence")
+      Double confidence,
+      @JsonProperty("polygon")
+      @JsonDeserialize(using = PolygonDeserializer.class)
+      Polygon polygon,
+      @JsonProperty("page_id")
+      Integer pageId
+  ) {
+    super(value, rawValue, confidence, polygon, pageId);
+    this.rawValue = rawValue;
+    this.streetNumber = streetNumber;
+    this.streetName = streetName;
+    this.poBox = poBox;
+    this.addressComplement = addressComplement;
+    this.city = city;
+    this.postalCode = postalCode;
+    this.state = state;
+    this.country = country;
+  }
+
+  /**
+   * Address field constructor only containing the value.
+   */
+  public AddressField(
+      String value,
+      Double confidence,
+      Polygon polygon
+  ) {
+    this(value, null, null, null, null,
+        null, null, null, null, null,
+        confidence, polygon, null);
+  }
+}
diff --git a/src/main/java/com/mindee/parsing/standard/StringField.java b/src/main/java/com/mindee/parsing/standard/StringField.java
@@ -13,7 +13,7 @@
  */
 @Getter
 @JsonIgnoreProperties(ignoreUnknown = true)
-public final class StringField extends BaseField {
+public class StringField extends BaseField {
 
   /**
    * The value of the field.
diff --git a/src/main/java/com/mindee/product/financialdocument/FinancialDocumentV1Document.java b/src/main/java/com/mindee/product/financialdocument/FinancialDocumentV1Document.java
@@ -5,6 +5,7 @@
 import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
 import com.mindee.parsing.SummaryHelper;
 import com.mindee.parsing.common.Prediction;
+import com.mindee.parsing.standard.AddressField;
 import com.mindee.parsing.standard.AmountField;
 import com.mindee.parsing.standard.ClassificationField;
 import com.mindee.parsing.standard.CompanyRegistrationField;
@@ -31,7 +32,7 @@ public class FinancialDocumentV1Document extends Prediction {
    * The customer's address used for billing.
    */
   @JsonProperty("billing_address")
-  protected StringField billingAddress;
+  protected AddressField billingAddress;
   /**
    * The purchase category.
    */
@@ -41,7 +42,7 @@ public class FinancialDocumentV1Document extends Prediction {
    * The address of the customer.
    */
   @JsonProperty("customer_address")
-  protected StringField customerAddress;
+  protected AddressField customerAddress;
   /**
    * List of company registration numbers associated to the customer.
    */
@@ -121,7 +122,7 @@ public class FinancialDocumentV1Document extends Prediction {
    * The customer's address used for shipping.
    */
   @JsonProperty("shipping_address")
-  protected StringField shippingAddress;
+  protected AddressField shippingAddress;
   /**
    * The purchase subcategory for transport, food and shooping.
    */
@@ -131,7 +132,7 @@ public class FinancialDocumentV1Document extends Prediction {
    * The address of the supplier or merchant.
    */
   @JsonProperty("supplier_address")
-  protected StringField supplierAddress;
+  protected AddressField supplierAddress;
   /**
    * List of company registration numbers associated to the supplier.
    */
diff --git a/src/main/java/com/mindee/product/invoice/InvoiceV4Document.java b/src/main/java/com/mindee/product/invoice/InvoiceV4Document.java
@@ -5,6 +5,7 @@
 import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
 import com.mindee.parsing.SummaryHelper;
 import com.mindee.parsing.common.Prediction;
+import com.mindee.parsing.standard.AddressField;
 import com.mindee.parsing.standard.AmountField;
 import com.mindee.parsing.standard.ClassificationField;
 import com.mindee.parsing.standard.CompanyRegistrationField;
@@ -31,7 +32,7 @@ public class InvoiceV4Document extends Prediction {
    * The customer billing address.
    */
   @JsonProperty("billing_address")
-  protected StringField billingAddress;
+  protected AddressField billingAddress;
   /**
    * The purchase category.
    */
@@ -41,7 +42,7 @@ public class InvoiceV4Document extends Prediction {
    * The address of the customer.
    */
   @JsonProperty("customer_address")
-  protected StringField customerAddress;
+  protected AddressField customerAddress;
   /**
    * List of company registration numbers associated to the customer.
    */
@@ -111,7 +112,7 @@ public class InvoiceV4Document extends Prediction {
    * Customer's delivery address.
    */
   @JsonProperty("shipping_address")
-  protected StringField shippingAddress;
+  protected AddressField shippingAddress;
   /**
    * The purchase subcategory for transport, food and shopping.
    */
@@ -121,7 +122,7 @@ public class InvoiceV4Document extends Prediction {
    * The address of the supplier or merchant.
    */
   @JsonProperty("supplier_address")
-  protected StringField supplierAddress;
+  protected AddressField supplierAddress;
   /**
    * List of company registration numbers associated to the supplier.
    */
