geocodio-library-python 1.3.0__tar.gz → 1.5.0__tar.gz

{geocodio_library_python-1.3.0 → geocodio_library_python-1.5.0}/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+- Public census accessors on `GeocodioFields`: `fields.census` (the requested append, most recent vintage when several are present), `fields.get_census(year)` (accepts `2023`, `"2023"` or `"census2023"`), `fields.census_years` and `fields.census_data`. The private `fields._census` dict and the dynamic `fields.census2023` attributes are unchanged.
+- `GeocodingResult.match_type` and `GeocodingResult.address_lines`, both of which the API returns on every result and the model previously dropped.
+- Raw response access: `GeocodingResponse.raw` / `.to_dict()` for the full untouched JSON payload, and `GeocodingResult.raw` / `.to_dict()` for a single result. Unlike `dataclasses.asdict()` these keep every key the API sent.
+- Rate limit headers are parsed into a `RateLimit` model, exposed as `GeocodingResponse.rate_limit` and `Geocodio.rate_limit` (updated on every request, including ones that raise).
+
 ## [1.3.0] - 2026-08-25
 
 ### Added

{geocodio_library_python-1.3.0 → geocodio_library_python-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: geocodio-library-python
-Version: 1.3.0
+Version: 1.5.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
@@ -149,6 +149,107 @@ response = client.geocode(
 )
 ```
 
+#### Census appends
+
+Census data is keyed by vintage. `fields.census` gives you the append you
+requested, and `fields.get_census(year)` picks a specific vintage when you
+requested more than one:
+
+```python
+response = client.geocode("1109 N Highland St, Arlington VA", fields=["census2023"])
+census = response.results[0].fields.census
+
+print(census.full_fips)   # "510131018012004"
+print(census.census_year)  # 2023
+
+# When several vintages were requested
+fields = response.results[0].fields
+fields.get_census(2023)      # also accepts "2023" or "census2023"
+fields.census_years          # [2023]
+fields.census_data           # {"census2023": CensusData(...)}
+```
+
+`fields.census` returns the most recent vintage present. Accessing a vintage
+directly (`fields.census2023`) continues to work.
+
+### Raw API responses
+
+Every geocoding response keeps the untouched JSON payload the API returned, so
+you can cache the full response and derive new columns later without paying for
+another lookup:
+
+```python
+response = client.geocode("1109 N Highland St, Arlington VA")
+
+response.raw          # the full JSON payload, exactly as returned
+response.to_dict()    # a deep copy of the same payload
+
+result = response.results[0]
+result.raw            # the JSON object for this result
+result.match_type     # "rooftop", "unit", "building_centroid" or None
+result.address_lines  # ["1109 N Highland St", "", "Arlington, VA 22201"]
+```
+
+### Rate limits
+
+The `X-RateLimit-*` response headers are parsed onto every geocoding response,
+and the most recent values are kept on the client (including for requests that
+raise):
+
+```python
+response = client.geocode("1109 N Highland St, Arlington VA")
+
+response.rate_limit.limit      # 1000
+response.rate_limit.remaining  # 999
+response.rate_limit.period     # 60 (seconds), when sent by the API
+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:

{geocodio_library_python-1.3.0 → geocodio_library_python-1.5.0}/README.md

@@ -114,6 +114,107 @@ response = client.geocode(
 )
 ```
 
+#### Census appends
+
+Census data is keyed by vintage. `fields.census` gives you the append you
+requested, and `fields.get_census(year)` picks a specific vintage when you
+requested more than one:
+
+```python
+response = client.geocode("1109 N Highland St, Arlington VA", fields=["census2023"])
+census = response.results[0].fields.census
+
+print(census.full_fips)   # "510131018012004"
+print(census.census_year)  # 2023
+
+# When several vintages were requested
+fields = response.results[0].fields
+fields.get_census(2023)      # also accepts "2023" or "census2023"
+fields.census_years          # [2023]
+fields.census_data           # {"census2023": CensusData(...)}
+```
+
+`fields.census` returns the most recent vintage present. Accessing a vintage
+directly (`fields.census2023`) continues to work.
+
+### Raw API responses
+
+Every geocoding response keeps the untouched JSON payload the API returned, so
+you can cache the full response and derive new columns later without paying for
+another lookup:
+
+```python
+response = client.geocode("1109 N Highland St, Arlington VA")
+
+response.raw          # the full JSON payload, exactly as returned
+response.to_dict()    # a deep copy of the same payload
+
+result = response.results[0]
+result.raw            # the JSON object for this result
+result.match_type     # "rooftop", "unit", "building_centroid" or None
+result.address_lines  # ["1109 N Highland St", "", "Arlington, VA 22201"]
+```
+
+### Rate limits
+
+The `X-RateLimit-*` response headers are parsed onto every geocoding response,
+and the most recent values are kept on the client (including for requests that
+raise):
+
+```python
+response = client.geocode("1109 N Highland St, Arlington VA")
+
+response.rate_limit.limit      # 1000
+response.rate_limit.remaining  # 999
+response.rate_limit.period     # 60 (seconds), when sent by the API
+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:

{geocodio_library_python-1.3.0 → geocodio_library_python-1.5.0}/pyproject.toml

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

{geocodio_library_python-1.3.0 → geocodio_library_python-1.5.0}/src/geocodio/_version.py

@@ -1,3 +1,3 @@
 """Version information for geocodio package."""
 
-__version__ = "1.3.0"
+__version__ = "1.5.0"

{geocodio_library_python-1.3.0 → geocodio_library_python-1.5.0}/src/geocodio/client.py

@@ -58,6 +58,7 @@ from geocodio.models import (
     Location,
     PaginatedResponse,
     ProvincialRiding,
+    RateLimit,
     SchoolDistrict,
     Social,
     StateLegislativeDistrict,
@@ -65,6 +66,7 @@ from geocodio.models import (
     Timezone,
     UKLegislativeDistrict,
     ZIP4Data,
+    parse_warnings,
 )
 
 
@@ -117,6 +119,7 @@ class Geocodio:
         self._http = httpx.Client(
             base_url=f"https://{self.hostname}", verify=verify_ssl
         )
+        self.rate_limit: Optional[RateLimit] = None
 
     # ──────────────────────────────────────────────────────────────────────────
     # Public methods
@@ -226,7 +229,7 @@ class Geocodio:
         response = self._request(
             "POST" if data else "GET", endpoint, params, json=data, timeout=timeout
         )
-        return self._parse_geocoding_response(response.json())
+        return self._parse_geocoding_response(response.json(), response=response)
 
     def reverse(
         self,
@@ -306,7 +309,7 @@ class Geocodio:
         response = self._request(
             "POST" if data else "GET", endpoint, params, json=data, timeout=timeout
         )
-        return self._parse_geocoding_response(response.json())
+        return self._parse_geocoding_response(response.json(), response=response)
 
     # ──────────────────────────────────────────────────────────────────────────
     # Internal helpers
@@ -350,6 +353,12 @@ class Geocodio:
         logger.debug(f"Response headers: {resp.headers}")
         logger.debug(f"Response body: {resp.content}")
 
+        # Keep the most recent rate limit state available to callers, including
+        # for responses that raise below.
+        rate_limit = RateLimit.from_headers(resp.headers)
+        if rate_limit is not None:
+            self.rate_limit = rate_limit
+
         resp = self._handle_error_response(resp)
 
         return resp
@@ -362,17 +371,30 @@ 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(self, response_json: dict) -> GeocodingResponse:
+    def _parse_geocoding_response(
+        self,
+        response_json: dict,
+        response: Optional[httpx.Response] = None,
+    ) -> GeocodingResponse:
         logger.debug(f"Raw response: {response_json}")
 
+        rate_limit = RateLimit.from_headers(response.headers) if response else None
+
         # Handle batch response format
         if (
             "results" in response_json
@@ -381,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,
@@ -398,6 +425,7 @@ class Geocodio:
                             accuracy_type="",
                             source="",
                             query=query,
+                            warnings=query_warnings,
                         )
                     )
                     continue
@@ -416,9 +444,18 @@ class Geocodio:
                         query=query,
                         fields=self._parse_fields(top.get("fields")),
                         stable_address_key=top.get("stable_address_key"),
+                        match_type=top.get("match_type"),
+                        address_lines=top.get("address_lines"),
+                        raw=top,
+                        warnings=query_warnings + parse_warnings(top),
                     )
                 )
-            return GeocodingResponse(results=results)
+            return GeocodingResponse(
+                results=results,
+                raw=response_json,
+                rate_limit=rate_limit,
+                warnings=batch_warnings,
+            )
 
         # Handle single response format
         results = [
@@ -433,10 +470,19 @@ class Geocodio:
                 source=res.get("source", ""),
                 fields=self._parse_fields(res.get("fields")),
                 stable_address_key=res.get("stable_address_key"),
+                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)
+        return GeocodingResponse(
+            results=results,
+            raw=response_json,
+            rate_limit=rate_limit,
+            warnings=parse_warnings(response_json),
+        )
 
     # ──────────────────────────────────────────────────────────────────────────
     # List API methods
@@ -542,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:
@@ -593,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
@@ -1341,6 +1389,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.3.0 → geocodio_library_python-1.5.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