geocodio-library-python 1.4.0__tar.gz → 1.6.0__tar.gz

{geocodio_library_python-1.4.0 → geocodio_library_python-1.6.0}/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.6.0] - 2026-10-12
+
+### Added
+- `calculation_type` parameter on `distance_matrix()` and `create_distance_matrix_job()`, with new `DISTANCE_CALCULATION_TYPE_MATRIX` and `DISTANCE_CALCULATION_TYPE_PAIRS` constants. `"pairs"` measures origin i against destination i only, instead of every origin against every destination.
+- `DistanceJobResponse.calculation_type`, read from job create, status and list responses (`None` when the API does not send it).
+
+## [1.5.0] - 2026-10-06
+
+### Added
+- Warnings support: the API's `_warnings` response key is now parsed into a `warnings` list on `GeocodingResponse`, `GeocodingResult`, `ListResponse`, `DistanceJobResponse` and `PaginatedResponse` (empty when the API sent none). Previously the key was only reachable through `GeocodingResponse.raw`, and was dropped entirely for list and distance matrix job responses. For batch requests, `GeocodingResult.warnings` includes the warnings attached to that query and `GeocodingResponse.warnings` holds the de-duplicated set across all queries.
+- `GeocodioError.warnings` (and `GeocodioErrorDetail.warnings`), exposing warnings attached to error responses.
+
 ## [1.4.0] - 2026-08-28
 
 ### Added

{geocodio_library_python-1.4.0 → geocodio_library_python-1.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: geocodio-library-python
-Version: 1.4.0
+Version: 1.6.0
 Summary: A Python client for the Geocodio API
 Project-URL: Homepage, https://www.geocod.io
 Project-URL: Documentation, https://www.geocod.io/docs/?python
@@ -207,6 +207,49 @@ response.rate_limit.reset      # unix timestamp, when sent by the API
 client.rate_limit              # the most recent rate limit state seen
 ```
 
+### Warnings
+
+The API reports non-fatal advisories under a `_warnings` key — a misspelled
+field name, an unexpected query parameter, a superseded API version, or an
+append that had to be skipped. The request still succeeds, so nothing is raised
+or logged; the warnings are parsed onto the response as a `warnings` list, which
+is empty when the API sent none:
+
+```python
+response = client.geocode("1109 N Highland St, Arlington VA", fields=["congress"])
+
+for warning in response.warnings:
+    print(warning)
+    # "The field congress is not recognized. Did you mean cd?"
+```
+
+Warnings show up in a few places, depending on what raised them:
+
+| Where | Applies to |
+| -- | -- |
+| `response.warnings` | Single `geocode()` and `reverse()`. For batch requests, the de-duplicated warnings from every query |
+| `response.results[i].warnings` | An individual result, e.g. an `ffiec` append skipped because the match is not street-level. For batch requests, this also includes the warnings attached to that query |
+| `list_response.warnings` | `create_list()`, `get_list()` and `get_lists()` |
+| `job.warnings` | `create_distance_matrix_job()`, `distance_matrix_job_status()` and `distance_matrix_jobs()` |
+
+Warnings are also attached to error responses, where they are available on the
+exception:
+
+```python
+from geocodio.exceptions import GeocodioError
+
+try:
+    response = client.geocode("1109 N Highland St", fields=["congress"])
+except GeocodioError as e:
+    for warning in e.warnings:
+        print(warning)  # "The field congress is not recognized. Did you mean cd?"
+```
+
+> [!TIP]
+> Warnings are worth logging during development — they are how the API tells
+> you a field append was silently skipped, which otherwise looks like missing
+> data.
+
 ### Address components
 
 For forward geocoding requests it is possible to supply [individual address components](https://www.geocod.io/docs/#single-address) instead of a full address string:
@@ -297,6 +340,8 @@ from geocodio import (
     DISTANCE_ORDER_BY_DURATION,
     DISTANCE_SORT_ASC,           # Default
     DISTANCE_SORT_DESC,
+    DISTANCE_CALCULATION_TYPE_MATRIX,  # Default - every origin × every destination (distance matrix only)
+    DISTANCE_CALCULATION_TYPE_PAIRS,   # Origin i to destination i only (distance matrix only)
 )
 ```
 
@@ -423,7 +468,13 @@ response = client.distance(
 #### Distance matrix (multiple origins × destinations)
 
 ```python
-from geocodio import Geocodio, Coordinate, DISTANCE_MODE_DRIVING, DISTANCE_UNITS_KM
+from geocodio import (
+    Geocodio,
+    Coordinate,
+    DISTANCE_MODE_DRIVING,
+    DISTANCE_UNITS_KM,
+    DISTANCE_CALCULATION_TYPE_PAIRS,
+)
 
 client = Geocodio("YOUR_API_KEY")
 
@@ -462,8 +513,18 @@ destinations = [
     Coordinate(37.7949, -122.3994, "customer_2")
 ]
 response = client.distance_matrix(origins=origins, destinations=destinations)
+
+# One-to-one pairs: origin i is measured against destination i only,
+# so each result has a single destination
+response = client.distance_matrix(
+    origins=["38.8977,-77.0365,home", "38.886672,-77.094735,office"],
+    destinations=["38.9072,-77.0369,capitol", "38.8814,-77.0916,pentagon"],
+    calculation_type=DISTANCE_CALCULATION_TYPE_PAIRS
+)
 ```
 
+> **Note:** With `DISTANCE_CALCULATION_TYPE_PAIRS`, `origins` and `destinations` must be the same length, and the `max_results`, `max_distance`, `max_duration`, `min_distance` and `min_duration` filters are not supported. The API returns a 422 error otherwise.
+
 #### Nearest mode (find closest destinations)
 
 ```python
@@ -514,7 +575,12 @@ response = client.distance_matrix(
 For large distance matrix calculations, use async jobs that process in the background.
 
 ```python
-from geocodio import Geocodio, DISTANCE_MODE_DRIVING, DISTANCE_UNITS_MILES
+from geocodio import (
+    Geocodio,
+    DISTANCE_MODE_DRIVING,
+    DISTANCE_UNITS_MILES,
+    DISTANCE_CALCULATION_TYPE_PAIRS,
+)
 
 client = Geocodio("YOUR_API_KEY")
 
@@ -540,6 +606,15 @@ job = client.create_distance_matrix_job(
     mode=DISTANCE_MODE_STRAIGHTLINE
 )
 
+# One-to-one pairs instead of a full matrix
+job = client.create_distance_matrix_job(
+    name="Commutes",
+    origins=["38.8977,-77.0365,home", "38.886672,-77.094735,office"],
+    destinations=["38.9072,-77.0369,capitol", "38.8814,-77.0916,pentagon"],
+    calculation_type=DISTANCE_CALCULATION_TYPE_PAIRS
+)
+print(job.calculation_type)  # "pairs"
+
 # Check job status
 status = client.distance_matrix_job_status(job.id)
 print(status.status)     # "ENQUEUED", "PROCESSING", "COMPLETED", or "FAILED"

{geocodio_library_python-1.4.0 → geocodio_library_python-1.6.0}/README.md

@@ -172,6 +172,49 @@ response.rate_limit.reset      # unix timestamp, when sent by the API
 client.rate_limit              # the most recent rate limit state seen
 ```
 
+### Warnings
+
+The API reports non-fatal advisories under a `_warnings` key — a misspelled
+field name, an unexpected query parameter, a superseded API version, or an
+append that had to be skipped. The request still succeeds, so nothing is raised
+or logged; the warnings are parsed onto the response as a `warnings` list, which
+is empty when the API sent none:
+
+```python
+response = client.geocode("1109 N Highland St, Arlington VA", fields=["congress"])
+
+for warning in response.warnings:
+    print(warning)
+    # "The field congress is not recognized. Did you mean cd?"
+```
+
+Warnings show up in a few places, depending on what raised them:
+
+| Where | Applies to |
+| -- | -- |
+| `response.warnings` | Single `geocode()` and `reverse()`. For batch requests, the de-duplicated warnings from every query |
+| `response.results[i].warnings` | An individual result, e.g. an `ffiec` append skipped because the match is not street-level. For batch requests, this also includes the warnings attached to that query |
+| `list_response.warnings` | `create_list()`, `get_list()` and `get_lists()` |
+| `job.warnings` | `create_distance_matrix_job()`, `distance_matrix_job_status()` and `distance_matrix_jobs()` |
+
+Warnings are also attached to error responses, where they are available on the
+exception:
+
+```python
+from geocodio.exceptions import GeocodioError
+
+try:
+    response = client.geocode("1109 N Highland St", fields=["congress"])
+except GeocodioError as e:
+    for warning in e.warnings:
+        print(warning)  # "The field congress is not recognized. Did you mean cd?"
+```
+
+> [!TIP]
+> Warnings are worth logging during development — they are how the API tells
+> you a field append was silently skipped, which otherwise looks like missing
+> data.
+
 ### Address components
 
 For forward geocoding requests it is possible to supply [individual address components](https://www.geocod.io/docs/#single-address) instead of a full address string:
@@ -262,6 +305,8 @@ from geocodio import (
     DISTANCE_ORDER_BY_DURATION,
     DISTANCE_SORT_ASC,           # Default
     DISTANCE_SORT_DESC,
+    DISTANCE_CALCULATION_TYPE_MATRIX,  # Default - every origin × every destination (distance matrix only)
+    DISTANCE_CALCULATION_TYPE_PAIRS,   # Origin i to destination i only (distance matrix only)
 )
 ```
 
@@ -388,7 +433,13 @@ response = client.distance(
 #### Distance matrix (multiple origins × destinations)
 
 ```python
-from geocodio import Geocodio, Coordinate, DISTANCE_MODE_DRIVING, DISTANCE_UNITS_KM
+from geocodio import (
+    Geocodio,
+    Coordinate,
+    DISTANCE_MODE_DRIVING,
+    DISTANCE_UNITS_KM,
+    DISTANCE_CALCULATION_TYPE_PAIRS,
+)
 
 client = Geocodio("YOUR_API_KEY")
 
@@ -427,8 +478,18 @@ destinations = [
     Coordinate(37.7949, -122.3994, "customer_2")
 ]
 response = client.distance_matrix(origins=origins, destinations=destinations)
+
+# One-to-one pairs: origin i is measured against destination i only,
+# so each result has a single destination
+response = client.distance_matrix(
+    origins=["38.8977,-77.0365,home", "38.886672,-77.094735,office"],
+    destinations=["38.9072,-77.0369,capitol", "38.8814,-77.0916,pentagon"],
+    calculation_type=DISTANCE_CALCULATION_TYPE_PAIRS
+)
 ```
 
+> **Note:** With `DISTANCE_CALCULATION_TYPE_PAIRS`, `origins` and `destinations` must be the same length, and the `max_results`, `max_distance`, `max_duration`, `min_distance` and `min_duration` filters are not supported. The API returns a 422 error otherwise.
+
 #### Nearest mode (find closest destinations)
 
 ```python
@@ -479,7 +540,12 @@ response = client.distance_matrix(
 For large distance matrix calculations, use async jobs that process in the background.
 
 ```python
-from geocodio import Geocodio, DISTANCE_MODE_DRIVING, DISTANCE_UNITS_MILES
+from geocodio import (
+    Geocodio,
+    DISTANCE_MODE_DRIVING,
+    DISTANCE_UNITS_MILES,
+    DISTANCE_CALCULATION_TYPE_PAIRS,
+)
 
 client = Geocodio("YOUR_API_KEY")
 
@@ -505,6 +571,15 @@ job = client.create_distance_matrix_job(
     mode=DISTANCE_MODE_STRAIGHTLINE
 )
 
+# One-to-one pairs instead of a full matrix
+job = client.create_distance_matrix_job(
+    name="Commutes",
+    origins=["38.8977,-77.0365,home", "38.886672,-77.094735,office"],
+    destinations=["38.9072,-77.0369,capitol", "38.8814,-77.0916,pentagon"],
+    calculation_type=DISTANCE_CALCULATION_TYPE_PAIRS
+)
+print(job.calculation_type)  # "pairs"
+
 # Check job status
 status = client.distance_matrix_job_status(job.id)
 print(status.status)     # "ENQUEUED", "PROCESSING", "COMPLETED", or "FAILED"

{geocodio_library_python-1.4.0 → geocodio_library_python-1.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "geocodio-library-python"
-version = "1.4.0"
+version = "1.6.0"
 description = "A Python client for the Geocodio API"
 readme = "README.md"
 requires-python = ">=3.11"

{geocodio_library_python-1.4.0 → geocodio_library_python-1.6.0}/src/geocodio/__init__.py

@@ -8,6 +8,8 @@ from .client import Geocodio
 
 # Distance API exports
 from .distance import (
+    DISTANCE_CALCULATION_TYPE_MATRIX,
+    DISTANCE_CALCULATION_TYPE_PAIRS,
     DISTANCE_MODE_DRIVING,
     DISTANCE_MODE_HAVERSINE,
     DISTANCE_MODE_STRAIGHTLINE,
@@ -52,4 +54,7 @@ __all__ = [
     # Distance sort constants
     "DISTANCE_SORT_ASC",
     "DISTANCE_SORT_DESC",
+    # Distance calculation type constants
+    "DISTANCE_CALCULATION_TYPE_MATRIX",
+    "DISTANCE_CALCULATION_TYPE_PAIRS",
 ]

{geocodio_library_python-1.4.0 → geocodio_library_python-1.6.0}/src/geocodio/_version.py

@@ -1,3 +1,3 @@
 """Version information for geocodio package."""
 
-__version__ = "1.4.0"
+__version__ = "1.6.0"

{geocodio_library_python-1.4.0 → geocodio_library_python-1.6.0}/src/geocodio/client.py

@@ -66,6 +66,7 @@ from geocodio.models import (
     Timezone,
     UKLegislativeDistrict,
     ZIP4Data,
+    parse_warnings,
 )
 
 
@@ -370,12 +371,19 @@ class Geocodio:
         exception_mappings = self.get_status_exception_mappings()
         # dump the type and content of the exception mappings for debugging
         logger.error(f"Error response: {resp.status_code} - {resp.text}")
+
+        try:
+            warnings = parse_warnings(resp.json())
+        except ValueError:
+            warnings = []
+
         if resp.status_code in exception_mappings:
             exception_class = exception_mappings[resp.status_code]
-            raise exception_class(resp.text)
+            raise exception_class(resp.text, warnings=warnings)
         else:
             raise GeocodioServerError(
-                f"Unrecognized status code {resp.status_code}: {resp.text}"
+                f"Unrecognized status code {resp.status_code}: {resp.text}",
+                warnings=warnings,
             )
 
     def _parse_geocoding_response(
@@ -395,9 +403,14 @@ class Geocodio:
             and "response" in response_json["results"][0]
         ):
             results = []
+            batch_warnings: List[str] = parse_warnings(response_json)
             for res in response_json["results"]:
                 query = res.get("query", "")
                 matches = res.get("response", {}).get("results") or []
+                query_warnings = parse_warnings(res.get("response"))
+                batch_warnings.extend(
+                    w for w in query_warnings if w not in batch_warnings
+                )
 
                 # Unmatched query (e.g. an unparseable address): keep an entry
                 # so the result list stays aligned with the submitted addresses,
@@ -412,6 +425,7 @@ class Geocodio:
                             accuracy_type="",
                             source="",
                             query=query,
+                            warnings=query_warnings,
                         )
                     )
                     continue
@@ -433,10 +447,14 @@ class Geocodio:
                         match_type=top.get("match_type"),
                         address_lines=top.get("address_lines"),
                         raw=top,
+                        warnings=query_warnings + parse_warnings(top),
                     )
                 )
             return GeocodingResponse(
-                results=results, raw=response_json, rate_limit=rate_limit
+                results=results,
+                raw=response_json,
+                rate_limit=rate_limit,
+                warnings=batch_warnings,
             )
 
         # Handle single response format
@@ -455,11 +473,15 @@ class Geocodio:
                 match_type=res.get("match_type"),
                 address_lines=res.get("address_lines"),
                 raw=res,
+                warnings=parse_warnings(res),
             )
             for res in response_json.get("results", [])
         ]
         return GeocodingResponse(
-            results=results, raw=response_json, rate_limit=rate_limit
+            results=results,
+            raw=response_json,
+            rate_limit=rate_limit,
+            warnings=parse_warnings(response_json),
         )
 
     # ──────────────────────────────────────────────────────────────────────────
@@ -566,6 +588,7 @@ class Geocodio:
             first_page_url=pagination_info.get("first_page_url"),
             next_page_url=pagination_info.get("next_page_url"),
             prev_page_url=pagination_info.get("prev_page_url"),
+            warnings=parse_warnings(pagination_info),
         )
 
     def get_list(self, list_id: str) -> ListResponse:
@@ -617,6 +640,7 @@ class Geocodio:
             download_url=response_json.get("download_url"),
             expires_at=response_json.get("expires_at"),
             http_response=response,
+            warnings=parse_warnings(response_json),
         )
 
     @staticmethod
@@ -1144,6 +1168,7 @@ class Geocodio:
         min_duration: Optional[int] = None,
         order_by: str = DISTANCE_ORDER_BY_DISTANCE,
         sort_order: str = DISTANCE_SORT_ASC,
+        calculation_type: Optional[str] = None,
     ) -> DistanceMatrixResponse:
         """
         Calculate distance matrix (multiple origins × destinations).
@@ -1162,6 +1187,10 @@ class Geocodio:
             min_duration: Minimum duration filter (seconds, driving mode only).
             order_by: Sort results by 'distance' or 'duration'.
             sort_order: Sort direction ('asc' or 'desc').
+            calculation_type: 'matrix' (default, every origin × every destination)
+                or 'pairs' (origin i to destination i only; origins and
+                destinations must be the same length and the max/min filters
+                are not allowed).
 
         Returns:
             DistanceMatrixResponse with results for each origin.
@@ -1210,6 +1239,8 @@ class Geocodio:
             body["order_by"] = order_by
         if sort_order != DISTANCE_SORT_ASC:
             body["sort"] = sort_order
+        if calculation_type is not None:
+            body["calculation_type"] = calculation_type
 
         response = self._request(
             "POST", endpoint, json=body, timeout=self.batch_timeout
@@ -1231,6 +1262,7 @@ class Geocodio:
         min_duration: Optional[int] = None,
         order_by: str = DISTANCE_ORDER_BY_DISTANCE,
         sort_order: str = DISTANCE_SORT_ASC,
+        calculation_type: Optional[str] = None,
     ) -> DistanceJobResponse:
         """
         Create an async distance matrix job for large calculations.
@@ -1249,6 +1281,10 @@ class Geocodio:
             min_duration: Minimum duration filter (seconds, driving mode only).
             order_by: Sort results by 'distance' or 'duration'.
             sort_order: Sort direction ('asc' or 'desc').
+            calculation_type: 'matrix' (default, every origin × every destination)
+                or 'pairs' (origin i to destination i only; origins and
+                destinations must be the same length and the max/min filters
+                are not allowed).
 
         Returns:
             DistanceJobResponse with job ID and status.
@@ -1307,6 +1343,8 @@ class Geocodio:
             body["order_by"] = order_by
         if sort_order != DISTANCE_SORT_ASC:
             body["sort"] = sort_order
+        if calculation_type is not None:
+            body["calculation_type"] = calculation_type
 
         response = self._request("POST", endpoint, json=body, timeout=self.list_timeout)
         return DistanceJobResponse.from_api(response.json())
@@ -1365,6 +1403,7 @@ class Geocodio:
             first_page_url=pagination_info.get("first_page_url"),
             next_page_url=pagination_info.get("next_page_url"),
             prev_page_url=pagination_info.get("prev_page_url"),
+            warnings=parse_warnings(pagination_info),
         )
 
     def get_distance_matrix_job_results(

{geocodio_library_python-1.4.0 → geocodio_library_python-1.6.0}/src/geocodio/distance.py

@@ -37,6 +37,13 @@ DISTANCE_ORDER_BY_DURATION = "duration"
 DISTANCE_SORT_ASC = "asc"
 DISTANCE_SORT_DESC = "desc"
 
+# ──────────────────────────────────────────────────────────────────────────────
+# Calculation Type Constants (distance matrix and distance matrix jobs only)
+# ──────────────────────────────────────────────────────────────────────────────
+
+DISTANCE_CALCULATION_TYPE_MATRIX = "matrix"  # Every origin × every destination
+DISTANCE_CALCULATION_TYPE_PAIRS = "pairs"  # Origin i to destination i only
+
 
 # ──────────────────────────────────────────────────────────────────────────────
 # Coordinate Class
@@ -263,6 +270,9 @@ __all__ = [
     # Sort constants
     "DISTANCE_SORT_ASC",
     "DISTANCE_SORT_DESC",
+    # Calculation type constants
+    "DISTANCE_CALCULATION_TYPE_MATRIX",
+    "DISTANCE_CALCULATION_TYPE_PAIRS",
     # Classes
     "Coordinate",
     # Functions

{geocodio_library_python-1.4.0 → geocodio_library_python-1.6.0}/src/geocodio/exceptions.py

@@ -5,7 +5,7 @@ Structured exception hierarchy for the Geocodio Python client.
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import List, Optional, Union
 
 # ──────────────────────────────────────────────────────────────────────────────
@@ -22,6 +22,7 @@ class GeocodioErrorDetail:
     message: str
     code: Optional[int] = None  # e.g. HTTP status or internal
     errors: Optional[List[str]] = None  # field‑specific validation messages
+    warnings: List[str] = field(default_factory=list)  # from ``_warnings``
 
 
 # ──────────────────────────────────────────────────────────────────────────────
@@ -32,13 +33,30 @@ class GeocodioErrorDetail:
 class GeocodioError(Exception):
     """Root of the library’s exception hierarchy."""
 
-    def __init__(self, detail: Union[str, GeocodioErrorDetail]):
+    def __init__(
+        self,
+        detail: Union[str, GeocodioErrorDetail],
+        warnings: Optional[List[str]] = None,
+    ):
         if isinstance(detail, str):
-            self.detail = GeocodioErrorDetail(message=detail)
+            self.detail = GeocodioErrorDetail(
+                message=detail, warnings=list(warnings or [])
+            )
         else:
             self.detail = detail
         super().__init__(self.detail.message)
 
+    @property
+    def warnings(self) -> List[str]:
+        """
+        Non-fatal advisories the API returned alongside the error.
+
+        The API appends a ``_warnings`` key to error responses just as it does
+        to successful ones, e.g. to point out a misspelled field name in a
+        request that failed for an unrelated reason.
+        """
+        return self.detail.warnings
+
     def __str__(self) -> str:  # prettier default printing
         return self.detail.message
 

{geocodio_library_python-1.4.0 → geocodio_library_python-1.6.0}/src/geocodio/models.py

@@ -14,6 +14,21 @@ import httpx
 T = TypeVar("T", bound="ExtrasMixin")
 
 
+def parse_warnings(data: Any) -> List[str]:
+    """
+    Read the ``_warnings`` key from an API payload.
+
+    The API only sends the key when at least one warning was raised, so a
+    missing key (or a payload that is not an object) yields an empty list.
+    """
+    if not isinstance(data, dict):
+        return []
+    warnings = data.get("_warnings")
+    if not isinstance(warnings, list):
+        return []
+    return [str(warning) for warning in warnings]
+
+
 class ExtrasMixin:
     """Mixin to provide additional functionality for API response models."""
 
@@ -733,6 +748,8 @@ class DistanceJobResponse:
         total_calculations: Total number of distance calculations.
         download_url: URL to download results (when completed).
         calculations_completed: Number of completed calculations.
+        warnings: Non-fatal advisories from the API's ``_warnings`` key.
+        calculation_type: 'matrix' or 'pairs' (None if the API did not send it).
     """
 
     id: int
@@ -746,10 +763,15 @@ class DistanceJobResponse:
     download_url: Optional[str] = None
     calculations_completed: Optional[int] = None
     progress: Optional[int] = None
+    warnings: List[str] = field(default_factory=list)
+    calculation_type: Optional[str] = None
 
     @classmethod
     def from_api(cls, data: Dict[str, Any]) -> "DistanceJobResponse":
         """Create from API response data."""
+        # Warnings sit beside the nested "data" key, so read them first
+        warnings = parse_warnings(data)
+
         # Handle nested "data" key for status responses
         if "data" in data and isinstance(data["data"], dict):
             data = data["data"]
@@ -771,6 +793,8 @@ class DistanceJobResponse:
             download_url=data.get("download_url"),
             calculations_completed=data.get("calculations_completed"),
             progress=data.get("progress"),
+            warnings=warnings,
+            calculation_type=data.get("calculation_type"),
         )
 
 
@@ -793,6 +817,9 @@ class GeocodingResult:
     match_type: Optional[str] = None
     address_lines: Optional[List[str]] = None
     raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+    # This result's ``_warnings`` (e.g. a skipped ffiec append). For batch
+    # requests, also the warnings attached to this query's response.
+    warnings: List[str] = field(default_factory=list)
 
     @property
     def matched(self) -> bool:
@@ -820,11 +847,15 @@ class GeocodingResponse:
         results: Flat list of results, one per submitted query.
         raw: The untouched JSON payload as returned by the API.
         rate_limit: Rate limit state from the response headers, when present.
+        warnings: Non-fatal advisories from the API's ``_warnings`` key, e.g.
+            an unrecognized field name. For batch requests, the de-duplicated
+            warnings from every query's response.
     """
 
     results: List[GeocodingResult] = field(default_factory=list)
     raw: Dict[str, Any] = field(default_factory=dict, repr=False)
     rate_limit: Optional[RateLimit] = None
+    warnings: List[str] = field(default_factory=list)
 
     def to_dict(self) -> Dict[str, Any]:
         """
@@ -851,6 +882,8 @@ class ListProcessingState:
 class ListResponse:
     """
     status, download_url, expires_at are not always present.
+
+    warnings holds non-fatal advisories from the API's ``_warnings`` key.
     """
 
     id: str
@@ -859,6 +892,7 @@ class ListResponse:
     download_url: Optional[str] = None
     expires_at: Optional[str] = None
     http_response: Optional[httpx.Response] = None
+    warnings: List[str] = field(default_factory=list)
 
 
 @dataclass(slots=True, frozen=True)
@@ -876,3 +910,4 @@ class PaginatedResponse:
     first_page_url: str
     next_page_url: Optional[str] = None
     prev_page_url: Optional[str] = None
+    warnings: List[str] = field(default_factory=list)

{geocodio_library_python-1.4.0 → geocodio_library_python-1.6.0}/tests/unit/test_distance.py

@@ -8,6 +8,7 @@ import httpx
 import pytest
 
 from geocodio import (
+    DISTANCE_CALCULATION_TYPE_PAIRS,
     DISTANCE_MODE_DRIVING,
     DISTANCE_MODE_HAVERSINE,
     DISTANCE_MODE_STRAIGHTLINE,
@@ -441,6 +442,39 @@ class TestDistanceMatrix:
             destinations=[Coordinate(38.8895, -77.0353, "dest1")],
         )
 
+    def test_distance_matrix_sends_calculation_type(self, client, httpx_mock):
+        """Test that calculation_type is sent in the POST body when given."""
+
+        def response_callback(request):
+            body = json.loads(request.content)
+            assert body["calculation_type"] == "pairs"
+            return httpx.Response(200, json=sample_distance_matrix_response())
+
+        httpx_mock.add_callback(callback=response_callback)
+
+        client.distance_matrix(
+            origins=["38.8977,-77.0365,home", "38.886672,-77.094735,office"],
+            destinations=["38.9072,-77.0369,capitol", "38.8814,-77.0916,pentagon"],
+            calculation_type=DISTANCE_CALCULATION_TYPE_PAIRS,
+        )
+
+    def test_distance_matrix_omits_calculation_type_by_default(
+        self, client, httpx_mock
+    ):
+        """Test that calculation_type is left out when not given."""
+
+        def response_callback(request):
+            body = json.loads(request.content)
+            assert "calculation_type" not in body
+            return httpx.Response(200, json=sample_distance_matrix_response())
+
+        httpx_mock.add_callback(callback=response_callback)
+
+        client.distance_matrix(
+            origins=["38.8977,-77.0365"],
+            destinations=["38.9072,-77.0369"],
+        )
+
 
 # ──────────────────────────────────────────────────────────────────────────────
 # Distance Job Method Tests
@@ -572,6 +606,57 @@ class TestDistanceJobs:
             callback_url="https://example.com/webhook",
         )
 
+    def test_create_job_sends_calculation_type(self, client, httpx_mock):
+        """Test creating a job with calculation_type."""
+
+        def response_callback(request):
+            body = json.loads(request.content)
+            assert body["calculation_type"] == "pairs"
+            return httpx.Response(200, json=sample_job_create_response())
+
+        httpx_mock.add_callback(callback=response_callback)
+
+        client.create_distance_matrix_job(
+            name="Commutes",
+            origins=[(38.8977, -77.0365), (38.886672, -77.094735)],
+            destinations=[(38.9072, -77.0369), (38.8814, -77.0916)],
+            calculation_type=DISTANCE_CALCULATION_TYPE_PAIRS,
+        )
+
+    def test_create_job_omits_calculation_type_by_default(self, client, httpx_mock):
+        """Test that calculation_type is left out of the job when not given."""
+
+        def response_callback(request):
+            body = json.loads(request.content)
+            assert "calculation_type" not in body
+            return httpx.Response(200, json=sample_job_create_response())
+
+        httpx_mock.add_callback(callback=response_callback)
+
+        client.create_distance_matrix_job(
+            name="My Job",
+            origins=[(38.8977, -77.0365)],
+            destinations=[(38.8895, -77.0353)],
+        )
+
+    def test_job_status_parses_calculation_type(self, client, httpx_mock):
+        """Test that calculation_type is read from the job response."""
+        payload = sample_job_status_response()
+        payload["data"]["calculation_type"] = "pairs"
+        httpx_mock.add_callback(
+            callback=lambda request: httpx.Response(200, json=payload)
+        )
+
+        response = client.distance_matrix_job_status(123)
+
+        assert response.calculation_type == "pairs"
+
+    def test_job_without_calculation_type_defaults_to_none(self):
+        """Test that responses predating calculation_type still parse."""
+        response = DistanceJobResponse.from_api(sample_job_create_response())
+
+        assert response.calculation_type is None
+
     def test_job_status(self, client, httpx_mock):
         """Test getting job status."""
         httpx_mock.add_callback(

geocodio_library_python-1.6.0/tests/unit/test_warnings.py

@@ -0,0 +1,364 @@
+"""
+The API reports non-fatal advisories under a `_warnings` key -- an
+unrecognized field name, a superseded API version, an append that was
+skipped. These tests lock in that the key is parsed onto every response
+shape, so a future model refactor cannot silently drop it.
+
+The shapes are the ones the OpenAPI specification models (see the `Warnings`
+schema): top-level on single geocode/reverse, per result, per batch item,
+and on the lists and distance-jobs responses.
+"""
+
+import pytest
+
+from geocodio.exceptions import (
+    AuthenticationError,
+    GeocodioError,
+    InvalidRequestError,
+)
+
+FIELD_WARNING = "The field congress is not recognized. Did you mean cd?"
+VERSION_WARNING = (
+    "There is a newer API version available, please consider upgrading to v2."
+)
+FIELDS_FORMAT_WARNING = (
+    "The fields parameter should contain a comma-separated list of fields "
+    "instead of an array"
+)
+FFIEC_WARNING = "ffiec field was skipped since result is not street-level"
+
+
+def result(formatted_address: str, **extra) -> dict:
+    return {
+        "address_components": {"city": "Arlington", "country": "US"},
+        "formatted_address": formatted_address,
+        "location": {"lat": 38.886665, "lng": -77.094733},
+        "accuracy": 1,
+        "accuracy_type": "rooftop",
+        "source": "Arlington",
+        **extra,
+    }
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Geocoding responses
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+def test_single_forward_geocode_warnings(client, httpx_mock):
+    httpx_mock.add_response(
+        json={
+            "results": [result("1109 N Highland St, Arlington, VA 22201")],
+            "_warnings": [FIELD_WARNING],
+        }
+    )
+
+    response = client.geocode("1109 N Highland St, Arlington VA", fields=["congress"])
+
+    assert response.warnings == [FIELD_WARNING]
+    assert response.results[0].warnings == []
+
+
+def test_single_reverse_geocode_warnings(client, httpx_mock):
+    warning = (
+        "Ignoring parameter zipcode as it was not expected. Did you mean postal_code?"
+    )
+    httpx_mock.add_response(
+        json={
+            "results": [result("1109 N Highland St, Arlington, VA 22201")],
+            "_warnings": [warning],
+        }
+    )
+
+    response = client.reverse("38.886665,-77.094733")
+
+    assert response.warnings == [warning]
+
+
+def test_per_result_warnings(client, httpx_mock):
+    httpx_mock.add_response(
+        json={
+            "results": [
+                result(
+                    "Arlington, VA 22201",
+                    accuracy_type="place",
+                    _warnings=[FFIEC_WARNING],
+                )
+            ],
+        }
+    )
+
+    response = client.geocode("22201", fields=["ffiec"])
+
+    assert response.warnings == []
+    assert response.results[0].warnings == [FFIEC_WARNING]
+
+
+def test_batch_forward_geocode_warnings(client, httpx_mock):
+    httpx_mock.add_response(
+        json={
+            "results": [
+                {
+                    "query": "1109 N Highland St, Arlington VA",
+                    "response": {
+                        "results": [
+                            result(
+                                "1109 N Highland St, Arlington, VA 22201",
+                                _warnings=[FFIEC_WARNING],
+                            )
+                        ],
+                        "_warnings": [FIELD_WARNING],
+                    },
+                },
+                {
+                    "query": "525 University Ave, Toronto, ON, Canada",
+                    "response": {
+                        "results": [result("525 University Ave, Toronto, ON M5G")],
+                        "_warnings": [FIELD_WARNING],
+                    },
+                },
+            ]
+        }
+    )
+
+    response = client.geocode(
+        [
+            "1109 N Highland St, Arlington VA",
+            "525 University Ave, Toronto, ON, Canada",
+        ],
+        fields=["congress"],
+    )
+
+    # Per query: that query's warnings, then the result's own
+    assert response.results[0].warnings == [FIELD_WARNING, FFIEC_WARNING]
+    assert response.results[1].warnings == [FIELD_WARNING]
+    # Across the batch: each warning once
+    assert response.warnings == [FIELD_WARNING]
+
+
+def test_batch_reverse_geocode_warnings(client, httpx_mock):
+    httpx_mock.add_response(
+        json={
+            "results": [
+                {
+                    "query": "35.9746000,-77.9658000",
+                    "response": {
+                        "results": [result("101 W Washington St, Nashville, NC 27856")],
+                        "_warnings": [VERSION_WARNING],
+                    },
+                }
+            ]
+        }
+    )
+
+    response = client.reverse(["35.9746000,-77.9658000"])
+
+    assert response.results[0].warnings == [VERSION_WARNING]
+    assert response.warnings == [VERSION_WARNING]
+
+
+def test_batch_warnings_kept_for_unmatched_query(client, httpx_mock):
+    httpx_mock.add_response(
+        json={
+            "results": [
+                {
+                    "query": "not an address",
+                    "response": {"results": [], "_warnings": [FIELD_WARNING]},
+                },
+            ]
+        }
+    )
+
+    response = client.geocode(["not an address"], fields=["congress"])
+
+    assert response.results[0].matched is False
+    assert response.results[0].warnings == [FIELD_WARNING]
+    assert response.warnings == [FIELD_WARNING]
+
+
+def test_no_warnings_when_api_sends_none(client, httpx_mock):
+    httpx_mock.add_response(
+        json={"results": [result("1109 N Highland St, Arlington, VA 22201")]}
+    )
+
+    response = client.geocode("1109 N Highland St, Arlington VA")
+
+    assert response.warnings == []
+    assert response.results[0].warnings == []
+    assert "_warnings" not in response.raw
+
+
+def test_warnings_remain_on_raw_payload(client, httpx_mock):
+    httpx_mock.add_response(
+        json={
+            "results": [result("1109 N Highland St, Arlington, VA 22201")],
+            "_warnings": [FIELD_WARNING],
+        }
+    )
+
+    response = client.geocode("1109 N Highland St, Arlington VA", fields=["congress"])
+
+    assert response.raw["_warnings"] == [FIELD_WARNING]
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Lists responses
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+def test_create_list_warnings(client, httpx_mock):
+    warning = (
+        "The following field was not recognized and has been skipped: "
+        "congressional_district"
+    )
+    httpx_mock.add_response(
+        json={
+            "id": 42,
+            "file": {"filename": "inline.csv"},
+            "status": {"state": "PROCESSING"},
+            "_warnings": [warning],
+        }
+    )
+
+    response = client.create_list(
+        file="address\n1109 N Highland St, Arlington VA",
+        filename="inline.csv",
+        fields=["congressional_district"],
+    )
+
+    assert response.warnings == [warning]
+
+
+def test_get_list_warnings(client, httpx_mock):
+    httpx_mock.add_response(
+        json={
+            "id": 42,
+            "file": {"filename": "inline.csv"},
+            "status": {"state": "COMPLETED"},
+            "_warnings": [FIELDS_FORMAT_WARNING],
+        }
+    )
+
+    assert client.get_list("42").warnings == [FIELDS_FORMAT_WARNING]
+
+
+def test_get_lists_warnings(client, httpx_mock):
+    httpx_mock.add_response(
+        json={
+            "current_page": 1,
+            "data": [],
+            "from": 0,
+            "to": 0,
+            "path": "/v2/lists",
+            "per_page": 15,
+            "first_page_url": "/v2/lists?page=1",
+            "_warnings": [FIELDS_FORMAT_WARNING],
+        }
+    )
+
+    assert client.get_lists().warnings == [FIELDS_FORMAT_WARNING]
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Distance matrix job responses
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+def test_create_distance_matrix_job_warnings(client, httpx_mock):
+    httpx_mock.add_response(
+        json={
+            "id": 123,
+            "identifier": "dmj_abc123",
+            "status": "ENQUEUED",
+            "name": "Store coverage",
+            "created_at": "2026-09-25T12:00:00.000000Z",
+            "origins_count": 1,
+            "destinations_count": 1,
+            "total_calculations": 1,
+            "_warnings": [VERSION_WARNING],
+        }
+    )
+
+    response = client.create_distance_matrix_job(
+        name="Store coverage",
+        origins=[(38.886665, -77.094733)],
+        destinations=[(38.897675, -77.036547)],
+    )
+
+    assert response.warnings == [VERSION_WARNING]
+
+
+def test_distance_matrix_job_status_warnings(client, httpx_mock):
+    # Warnings sit beside the nested "data" key, not inside it
+    httpx_mock.add_response(
+        json={
+            "data": {"id": 123, "identifier": "dmj_abc123", "status": "COMPLETED"},
+            "_warnings": [FIELDS_FORMAT_WARNING],
+        }
+    )
+
+    response = client.distance_matrix_job_status("dmj_abc123")
+
+    assert response.status == "COMPLETED"
+    assert response.warnings == [FIELDS_FORMAT_WARNING]
+
+
+def test_distance_matrix_jobs_warnings(client, httpx_mock):
+    httpx_mock.add_response(
+        json={
+            "current_page": 1,
+            "data": [],
+            "from": 0,
+            "to": 0,
+            "path": "/v2/distance-jobs",
+            "per_page": 10,
+            "first_page_url": "/v2/distance-jobs?page=1",
+            "_warnings": [FIELDS_FORMAT_WARNING],
+        }
+    )
+
+    assert client.distance_matrix_jobs().warnings == [FIELDS_FORMAT_WARNING]
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Error responses
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+def test_error_response_warnings(client, httpx_mock):
+    httpx_mock.add_response(
+        status_code=422,
+        json={
+            "error": "Could not geocode address. Postal code or city required.",
+            "_warnings": [FIELD_WARNING],
+        },
+    )
+
+    with pytest.raises(InvalidRequestError) as exc_info:
+        client.geocode("1109 N Highland St", fields=["congress"])
+
+    assert exc_info.value.warnings == [FIELD_WARNING]
+    assert exc_info.value.detail.warnings == [FIELD_WARNING]
+
+
+def test_error_response_without_warnings(client, httpx_mock):
+    httpx_mock.add_response(status_code=403, json={"error": "Invalid API key"})
+
+    with pytest.raises(AuthenticationError) as exc_info:
+        client.geocode("1109 N Highland St, Arlington VA")
+
+    assert exc_info.value.warnings == []
+
+
+def test_non_json_error_response_has_no_warnings(client, httpx_mock):
+    httpx_mock.add_response(status_code=502, text="<html>Bad Gateway</html>")
+
+    with pytest.raises(GeocodioError) as exc_info:
+        client.geocode("1109 N Highland St, Arlington VA")
+
+    assert exc_info.value.warnings == []
+
+
+def test_error_constructed_directly_has_no_warnings():
+    assert GeocodioError("boom").warnings == []
+    assert GeocodioError("boom", warnings=[FIELD_WARNING]).warnings == [FIELD_WARNING]

{geocodio_library_python-1.4.0 → geocodio_library_python-1.6.0}/uv.lock

@@ -1,5 +1,5 @@
 version = 1
-revision = 3
+revision = 5
 requires-python = ">=3.11"
 
 [[package]]
@@ -149,7 +149,7 @@ wheels = [
 
 [[package]]
 name = "geocodio-library-python"
-version = "1.4.0"
+version = "1.6.0"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },