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

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

@@ -7,6 +7,12 @@ 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: geocodio-library-python
-Version: 1.5.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
@@ -340,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)
 )
 ```
 
@@ -466,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")
 
@@ -505,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
@@ -557,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")
 
@@ -583,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.5.0 → geocodio_library_python-1.6.0}/README.md

@@ -305,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)
 )
 ```
 
@@ -431,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")
 
@@ -470,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
@@ -522,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")
 
@@ -548,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.5.0 → geocodio_library_python-1.6.0}/pyproject.toml

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

{geocodio_library_python-1.5.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.5.0 → geocodio_library_python-1.6.0}/src/geocodio/_version.py

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

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

@@ -1168,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).
@@ -1186,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.
@@ -1234,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
@@ -1255,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.
@@ -1273,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.
@@ -1331,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())

{geocodio_library_python-1.5.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.5.0 → geocodio_library_python-1.6.0}/src/geocodio/models.py

@@ -749,6 +749,7 @@ class DistanceJobResponse:
         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
@@ -763,6 +764,7 @@ class DistanceJobResponse:
     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":
@@ -792,6 +794,7 @@ class DistanceJobResponse:
             calculations_completed=data.get("calculations_completed"),
             progress=data.get("progress"),
             warnings=warnings,
+            calculation_type=data.get("calculation_type"),
         )
 
 

{geocodio_library_python-1.5.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.5.0 → geocodio_library_python-1.6.0}/uv.lock

@@ -149,7 +149,7 @@ wheels = [
 
 [[package]]
 name = "geocodio-library-python"
-version = "1.5.0"
+version = "1.6.0"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },