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

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

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+- United Kingdom data append support. The `uk-westminster`, `uk-devolved`, and `uk-local` appends (and their `-next` variants) are now parsed into a typed `UKLegislativeDistrict` model, exposed via `fields.uk_westminster`, `fields.uk_devolved`, and `fields.uk_local`.
+
 ## [1.0.0] - 2026-06-05
 
 ### Changed
@@ -79,7 +92,8 @@ When ready to release:
 5. Push tags: `git push --tags`
 6. GitHub Actions will automatically publish to PyPI
 
-[Unreleased]: https://github.com/Geocodio/geocodio-library-python/compare/v1.0.0...HEAD
+[Unreleased]: https://github.com/Geocodio/geocodio-library-python/compare/v1.3.0...HEAD
+[1.3.0]: https://github.com/Geocodio/geocodio-library-python/compare/v1.2.0...v1.3.0
 [1.0.0]: https://github.com/Geocodio/geocodio-library-python/compare/v0.7.0...v1.0.0
 [0.7.0]: https://github.com/Geocodio/geocodio-library-python/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/Geocodio/geocodio-library-python/compare/v0.5.1...v0.6.0

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: geocodio-library-python
-Version: 1.0.0
+Version: 1.4.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
@@ -100,6 +100,7 @@ To batch geocode, simply pass a list of addresses or coordinates instead of a si
 response = client.geocode([
     "1109 N Highland St, Arlington VA",
     "525 University Ave, Toronto, ON, Canada",
+    "10 Downing St, London, United Kingdom",
     "4410 S Highway 17 92, Casselberry FL",
     "15000 NE 24th Street, Redmond WA",
     "17015 Walnut Grove Drive, Morgan Hill CA"
@@ -116,15 +117,16 @@ response = client.reverse([
 response = client.geocode({
     "MyId1": "1109 N Highland St, Arlington VA",
     "MyId2": "525 University Ave, Toronto, ON, Canada",
-    "MyId3": "4410 S Highway 17 92, Casselberry FL",
-    "MyId4": "15000 NE 24th Street, Redmond WA",
-    "MyId5": "17015 Walnut Grove Drive, Morgan Hill CA"
+    "MyId3": "10 Downing St, London, United Kingdom",
+    "MyId4": "4410 S Highway 17 92, Casselberry FL",
+    "MyId5": "15000 NE 24th Street, Redmond WA",
+    "MyId6": "17015 Walnut Grove Drive, Morgan Hill CA"
 })
 ```
 
 ### Field appends
 
-Geocodio allows you to append additional data points such as congressional districts, census codes, timezone, ACS survey results and [much more](https://www.geocod.io/docs/#fields).
+Geocodio allows you to append additional data points such as congressional districts, census codes, timezone, ACS survey results, UK constituencies and wards, and [much more](https://www.geocod.io/docs/#fields).
 
 To request additional fields, simply supply them as a list:
 
@@ -138,6 +140,71 @@ response = client.geocode(
 )
 
 response = client.reverse("38.9002898,-76.9990361", fields=["census2010"])
+
+# United Kingdom addresses support UK-specific appends such as Westminster and
+# devolved parliament constituencies, and local authority wards
+response = client.geocode(
+    "10 Downing St, London, United Kingdom",
+    fields=["uk-westminster", "uk-local"]
+)
+```
+
+#### 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
 ```
 
 ### Address components
@@ -163,6 +230,12 @@ response = client.geocode([
         "city": "Toronto",
         "state": "ON",
         "country": "Canada"
+    },
+    {
+        "street": "10 Downing St",
+        "city": "London",
+        "postal_code": "SW1A 2AA",
+        "country": "United Kingdom"
     }
 ])
 ```

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

@@ -65,6 +65,7 @@ To batch geocode, simply pass a list of addresses or coordinates instead of a si
 response = client.geocode([
     "1109 N Highland St, Arlington VA",
     "525 University Ave, Toronto, ON, Canada",
+    "10 Downing St, London, United Kingdom",
     "4410 S Highway 17 92, Casselberry FL",
     "15000 NE 24th Street, Redmond WA",
     "17015 Walnut Grove Drive, Morgan Hill CA"
@@ -81,15 +82,16 @@ response = client.reverse([
 response = client.geocode({
     "MyId1": "1109 N Highland St, Arlington VA",
     "MyId2": "525 University Ave, Toronto, ON, Canada",
-    "MyId3": "4410 S Highway 17 92, Casselberry FL",
-    "MyId4": "15000 NE 24th Street, Redmond WA",
-    "MyId5": "17015 Walnut Grove Drive, Morgan Hill CA"
+    "MyId3": "10 Downing St, London, United Kingdom",
+    "MyId4": "4410 S Highway 17 92, Casselberry FL",
+    "MyId5": "15000 NE 24th Street, Redmond WA",
+    "MyId6": "17015 Walnut Grove Drive, Morgan Hill CA"
 })
 ```
 
 ### Field appends
 
-Geocodio allows you to append additional data points such as congressional districts, census codes, timezone, ACS survey results and [much more](https://www.geocod.io/docs/#fields).
+Geocodio allows you to append additional data points such as congressional districts, census codes, timezone, ACS survey results, UK constituencies and wards, and [much more](https://www.geocod.io/docs/#fields).
 
 To request additional fields, simply supply them as a list:
 
@@ -103,6 +105,71 @@ response = client.geocode(
 )
 
 response = client.reverse("38.9002898,-76.9990361", fields=["census2010"])
+
+# United Kingdom addresses support UK-specific appends such as Westminster and
+# devolved parliament constituencies, and local authority wards
+response = client.geocode(
+    "10 Downing St, London, United Kingdom",
+    fields=["uk-westminster", "uk-local"]
+)
+```
+
+#### 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
 ```
 
 ### Address components
@@ -128,6 +195,12 @@ response = client.geocode([
         "city": "Toronto",
         "state": "ON",
         "country": "Canada"
+    },
+    {
+        "street": "10 Downing St",
+        "city": "London",
+        "postal_code": "SW1A 2AA",
+        "country": "United Kingdom"
     }
 ])
 ```

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

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

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

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

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

@@ -58,11 +58,13 @@ from geocodio.models import (
     Location,
     PaginatedResponse,
     ProvincialRiding,
+    RateLimit,
     SchoolDistrict,
     Social,
     StateLegislativeDistrict,
     StatisticsCanadaData,
     Timezone,
+    UKLegislativeDistrict,
     ZIP4Data,
 )
 
@@ -116,6 +118,7 @@ class Geocodio:
         self._http = httpx.Client(
             base_url=f"https://{self.hostname}", verify=verify_ssl
         )
+        self.rate_limit: Optional[RateLimit] = None
 
     # ──────────────────────────────────────────────────────────────────────────
     # Public methods
@@ -225,7 +228,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,
@@ -305,7 +308,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
@@ -349,6 +352,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
@@ -369,9 +378,15 @@ class Geocodio:
                 f"Unrecognized status code {resp.status_code}: {resp.text}"
             )
 
-    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
@@ -379,27 +394,50 @@ class Geocodio:
             and response_json["results"]
             and "response" in response_json["results"][0]
         ):
-            results = [
-                GeocodingResult(
-                    address_components=AddressComponents.from_api(
-                        res["response"]["results"][0]["address_components"]
-                    ),
-                    formatted_address=res["response"]["results"][0][
-                        "formatted_address"
-                    ],
-                    location=Location(**res["response"]["results"][0]["location"]),
-                    accuracy=res["response"]["results"][0].get("accuracy", 0.0),
-                    accuracy_type=res["response"]["results"][0].get(
-                        "accuracy_type", ""
-                    ),
-                    source=res["response"]["results"][0].get("source", ""),
-                    fields=self._parse_fields(
-                        res["response"]["results"][0].get("fields")
-                    ),
+            results = []
+            for res in response_json["results"]:
+                query = res.get("query", "")
+                matches = res.get("response", {}).get("results") or []
+
+                # Unmatched query (e.g. an unparseable address): keep an entry
+                # so the result list stays aligned with the submitted addresses,
+                # but with no coordinates.
+                if not matches:
+                    results.append(
+                        GeocodingResult(
+                            address_components=AddressComponents.from_api({}),
+                            formatted_address="",
+                            location=None,
+                            accuracy=0.0,
+                            accuracy_type="",
+                            source="",
+                            query=query,
+                        )
+                    )
+                    continue
+
+                top = matches[0]
+                results.append(
+                    GeocodingResult(
+                        address_components=AddressComponents.from_api(
+                            top["address_components"]
+                        ),
+                        formatted_address=top["formatted_address"],
+                        location=Location(**top["location"]),
+                        accuracy=top.get("accuracy", 0.0),
+                        accuracy_type=top.get("accuracy_type", ""),
+                        source=top.get("source", ""),
+                        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,
+                    )
                 )
-                for res in response_json["results"]
-            ]
-            return GeocodingResponse(results=results)
+            return GeocodingResponse(
+                results=results, raw=response_json, rate_limit=rate_limit
+            )
 
         # Handle single response format
         results = [
@@ -413,10 +451,16 @@ class Geocodio:
                 accuracy_type=res.get("accuracy_type", ""),
                 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,
             )
             for res in response_json.get("results", [])
         ]
-        return GeocodingResponse(results=results)
+        return GeocodingResponse(
+            results=results, raw=response_json, rate_limit=rate_limit
+        )
 
     # ──────────────────────────────────────────────────────────────────────────
     # List API methods
@@ -452,6 +496,7 @@ class Geocodio:
                    - acs, acs-demographics, acs-economics, acs-families, acs-housing, acs-social
                    - riding, provriding, provriding-next (Canadian data)
                    - statcan (Statistics Canada data)
+                   - uk-westminster, uk-westminster-next, uk-devolved, uk-devolved-next, uk-local, uk-local-next (UK legislative districts)
                    - zip4 (ZIP+4 data)
                    - ffiec (FFIEC data, beta)
 
@@ -832,6 +877,35 @@ class Geocodio:
             else None
         )
 
+        # United Kingdom fields (each append returns a list of districts). The
+        # ``-next`` request variants fold into these same response keys.
+        uk_westminster = (
+            [
+                UKLegislativeDistrict.from_api(district)
+                for district in fields_data["uk_westminster"]
+            ]
+            if "uk_westminster" in fields_data
+            else None
+        )
+
+        uk_devolved = (
+            [
+                UKLegislativeDistrict.from_api(district)
+                for district in fields_data["uk_devolved"]
+            ]
+            if "uk_devolved" in fields_data
+            else None
+        )
+
+        uk_local = (
+            [
+                UKLegislativeDistrict.from_api(district)
+                for district in fields_data["uk_local"]
+            ]
+            if "uk_local" in fields_data
+            else None
+        )
+
         # Collect all known field keys that were parsed
         parsed_keys = {
             "timezone",
@@ -856,6 +930,9 @@ class Geocodio:
             "provriding",
             "provriding-next",
             "statcan",
+            "uk_westminster",
+            "uk_devolved",
+            "uk_local",
         }
         # Add flat census keys that were parsed (census2000, census2020, etc.)
         # All census years are now stored in _census dict for dynamic access
@@ -878,6 +955,9 @@ class Geocodio:
             provriding=provriding,
             provriding_next=provriding_next,
             statcan=statcan,
+            uk_westminster=uk_westminster,
+            uk_devolved=uk_devolved,
+            uk_local=uk_local,
             extras=extras,
             _census=census_data_dict,  # All census years stored here
             **acs_fields,  # Dynamically include all ACS metric fields