fix: fallback to libpostal on US validation failure

Author: github-actions

README.md

@@ -60,6 +60,7 @@ make docker-run-api
 - Strict rules: international results must include a road plus at least one location element (city/state/postal/country) or parsing fails.
 - Returned structure includes `InternationalAddress` fields (`HouseNumber`, `Road`, `City`, `State`, `PostalCode`, `Country`, `CountryCode`) and raw libpostal `Components`.
 - Requires libpostal installed; the provided Docker image already bundles it. Outside Docker, install libpostal first.
+- Heuristics: if the input clearly names a non-US country or contains non-ASCII, it skips US parsing and goes straight to libpostal; otherwise, US is attempted first and any US validation failure triggers libpostal fallback.
 
 Notes:
 - Image name: `ghcr.io/abstract-data/ryandata-addr-utils-libpostal` (configurable via `DOCKER_IMAGE`, `DOCKER_TAG`, `DOCKER_REF`).

src/ryandata_address_utils/api.py

@@ -70,13 +70,15 @@ def parse_auto(address: str = Query(..., min_length=3), validate: bool = True) -
                 "address": intl.to_dict() if intl else None,
                 "components": intl.Components if intl else {},
                 "errors": [],
+                "source": result.source,
             }
         return {
             "mode": "us",
             "is_valid": True,
             "is_parsed": True,
             "address": result.to_dict(),
             "errors": [],
+            "source": result.source,
         }
 
     if result.error:
@@ -89,13 +91,15 @@ def parse_auto(address: str = Query(..., min_length=3), validate: bool = True) -
             "is_valid": False,
             "is_parsed": False,
             "errors": ["International parse failed"],
+            "source": result.source,
         }
 
     return {
         "mode": "us",
         "is_valid": False,
         "is_parsed": False,
         "errors": ["US parse failed"],
+        "source": result.source,
     }
 
 

src/ryandata_address_utils/service.py

@@ -22,6 +22,47 @@
 except ImportError:
     lp_parse_address = None
 
+
+def _is_probably_international(address_string: str) -> bool:
+    """Lightweight heuristic to detect likely international addresses."""
+
+    lower = address_string.lower()
+    intl_keywords = [
+        "united kingdom",
+        "uk",
+        "england",
+        "scotland",
+        "wales",
+        "ireland",
+        "germany",
+        "france",
+        "japan",
+        "россия",
+        "russia",
+        "india",
+        "australia",
+        "brazil",
+        "canada",
+        "mexico",
+        "spain",
+        "italy",
+        "netherlands",
+        "belgium",
+        "switzerland",
+        "sweden",
+        "norway",
+        "denmark",
+        "finland",
+    ]
+
+    if any(keyword in lower for keyword in intl_keywords) and (
+        "united states" not in lower and "usa" not in lower
+    ):
+        return True
+
+    return bool(any(ord(ch) > 127 for ch in address_string))
+
+
 if TYPE_CHECKING:
     import pandas as pd
 
@@ -258,7 +299,7 @@ def parse_international(self, address_string: str) -> ParseResult:
                 error=RuntimeError("libpostal not available"),
                 address=None,
                 international_address=None,
-                validation=None,
+                validation=ValidationResult(is_valid=False, errors=[]),
                 source="international",
             )
 
@@ -289,13 +330,36 @@ def parse_international(self, address_string: str) -> ParseResult:
             )
 
     def parse_auto_route(self, address_string: str, *, validate: bool = True) -> ParseResult:
-        """Try US parse first; if invalid and libpostal is available, fall back to international."""
-        us_result = self.parse(address_string, validate=validate)
+        """Try US parse first; if invalid or fails and libpostal is available, fall back."""
+        # If clearly international, skip US path
+        if _is_probably_international(address_string) and lp_parse_address is not None:
+            return self.parse_international(address_string)
+
+        try:
+            us_result = self.parse(address_string, validate=validate)
+        except Exception as exc:
+            if lp_parse_address is not None:
+                intl_result = self.parse_international(address_string)
+                if intl_result.is_valid or intl_result.international_address is not None:
+                    return intl_result
+            # Return error as a ParseResult to avoid raising in auto route
+            return ParseResult(
+                raw_input=address_string,
+                address=None,
+                international_address=None,
+                error=exc,
+                validation=ValidationResult(is_valid=False, errors=[]),
+                source="us",
+            )
+
         if us_result.is_valid:
             return us_result
+
         if lp_parse_address is None:
             return us_result
-        return self.parse_international(address_string)
+
+        intl_result = self.parse_international(address_string)
+        return intl_result
 
     # -------------------------------------------------------------------------
     # Pandas integration methods

tests/test_address_parser.py

@@ -958,3 +958,24 @@ def test_parse_auto_international_missing_components_fails_strict() -> None:
     assert result.source == "international"
     assert not result.is_valid
     assert isinstance(result.error, RyanDataAddressError)
+
+
+def test_parse_auto_international_skips_us_when_probably_international() -> None:
+    _require_libpostal()
+    service = AddressService()
+    result = service.parse_auto_route("Potsdamer Straße 3, 10785 Berlin, Germany", validate=True)
+    assert result.source == "international"
+    assert result.is_valid
+    assert result.international_address is not None
+    assert result.international_address.Road is not None
+
+
+def test_parse_auto_fallback_on_us_validation_error() -> None:
+    _require_libpostal()
+    service = AddressService()
+    result = service.parse_auto_route(
+        "1-1-2 Oshiage, Sumida-ku, Tokyo 131-0045, Japan", validate=True
+    )
+    assert result.source == "international"
+    assert result.is_valid
+    assert result.international_address is not None