Feature/geohash proto

README.md

@@ -235,6 +235,7 @@ The SDK provides both synchronous (`Client`) and asynchronous (`AsyncClient`) ve
 - [`h3_fast()`](https://docs.traveltime.com/api/reference/h3-fast) - Fast H3 analysis
 - [`geohash()`](https://docs.traveltime.com/api/reference/geohash) - Geohash analysis
 - [`geohash_fast()`](https://docs.traveltime.com/api/reference/geohash-fast) - Fast geohash analysis
+- [`geohash_fast_proto()`](https://docs.traveltime.com/api/reference/geohash-fast) - Ultra-fast protocol buffer geohash analysis (requires `pip install 'traveltimepy[proto]'`)
 - [`postcodes()`](https://docs.traveltime.com/api/reference/postcode-search) - UK postcode analysis
 - [`postcode_districts()`](https://docs.traveltime.com/api/reference/postcode-district-filter) - UK postcode district analysis
 - [`postcode_sectors()`](https://docs.traveltime.com/api/reference/postcode-sector-filter) - UK postcode sector analysis
@@ -317,7 +318,7 @@ See [examples/README.md](examples/README.md) for setup instructions and detailed
 ## Performance Tips
 
 - Use `*_fast()` methods for high-volume use cases
-- Use `time_filter_proto()` for maximum performance with large datasets (install with `pip install 'traveltimepy[proto]'`)
+- Use `time_filter_proto()` and `geohash_fast_proto()` for maximum performance with large datasets (install with `pip install 'traveltimepy[proto]'`)
 - Use async methods for I/O-bound applications
 
 ## Documentation

examples/README.md

@@ -34,6 +34,13 @@ Find the 3 closest shops by driving time using the Protocol Buffers API for maxi
 python examples/time_filter_fast_proto.py
 ```
 
+### geohash_fast_proto.py - Geohash Travel Time Analysis
+High-performance geohash-based travel time calculation using the Protocol Buffers API. Finds reachable geohash cells within a travel time limit and returns min/max/mean travel times per cell.
+
+```bash
+python examples/geohash_fast_proto.py
+```
+
 ### geocoding.py - London Walking Tour Planner
 Plan a walking tour of famous London landmarks. Uses geocoding to get coordinates, then calculates total walking time including 30-minute stops at each location.
 
@@ -48,6 +55,7 @@ Each example can be run directly from the project root:
 ```bash
 PYTHONPATH=. python examples/time_filter.py
 PYTHONPATH=. python examples/time_filter_fast_proto.py
+PYTHONPATH=. python examples/geohash_fast_proto.py
 PYTHONPATH=. python examples/geocoding.py
 ```
 

examples/geohash_fast_proto.py

@@ -0,0 +1,58 @@
+#!/usr/bin/env python3
+"""Geohash travel time analysis using Protocol Buffers API.
+
+High-performance geohash-based travel time calculation.
+"""
+
+import asyncio
+import os
+from traveltimepy import AsyncClient
+from traveltimepy.requests.common import Coordinates
+from traveltimepy.requests.time_filter_proto import (
+    ProtoTransportation,
+    ProtoCountry,
+    RequestType,
+)
+from traveltimepy.requests.geohash_fast_proto import ProtoCellProperty
+
+
+async def main():
+    app_id = os.environ.get("TRAVELTIME_APP_ID")
+    api_key = os.environ.get("TRAVELTIME_API_KEY")
+
+    if not app_id or not api_key:
+        print(
+            "Error: Please set TRAVELTIME_APP_ID and TRAVELTIME_API_KEY environment variables"
+        )
+        exit(1)
+
+    origin = Coordinates(lat=51.4107, lng=-0.1554)
+
+    async with AsyncClient(app_id, api_key) as client:
+        response = await client.geohash_fast_proto(
+            origin_coordinate=origin,
+            transportation=ProtoTransportation.DRIVING_FERRY,
+            travel_time=3600,  # 1 hour max
+            request_type=RequestType.ONE_TO_MANY,
+            country=ProtoCountry.UNITED_KINGDOM,
+            resolution=4,
+            properties=[
+                ProtoCellProperty.MIN,
+                ProtoCellProperty.MAX,
+                ProtoCellProperty.MEAN,
+            ],
+        )
+
+        print(f"Found {len(response.ids)} reachable geohash cells")
+        for i, cell_id in enumerate(response.ids[:5]):
+            print(
+                f"  {cell_id}: min={response.min_travel_times[i]}s, "
+                f"max={response.max_travel_times[i]}s, "
+                f"mean={response.mean_travel_times[i]}s"
+            )
+        if len(response.ids) > 5:
+            print(f"  ... and {len(response.ids) - 5} more")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

proto/GeohashFastRequest.proto

@@ -0,0 +1,28 @@
+syntax = "proto3";
+
+package com.igeolise.traveltime.rabbitmq.requests;
+
+import "RequestsCommon.proto";
+
+message GeohashFastRequest {
+  message OneToMany {
+    Coords departureLocation = 1;
+    Transportation transportation = 2;
+    TimePeriod arrivalTimePeriod = 3;
+    sint32 travelTime = 4;
+    uint32 resolution = 5;
+    repeated CellPropertyType properties = 6;
+  }
+
+  message ManyToOne {
+    Coords arrivalLocation = 1;
+    Transportation transportation = 2;
+    TimePeriod arrivalTimePeriod = 3;
+    sint32 travelTime = 4;
+    uint32 resolution = 5;
+    repeated CellPropertyType properties = 6;
+  }
+
+  OneToMany oneToManyRequest = 1;
+  ManyToOne manyToOneRequest = 2;
+}

proto/GeohashFastResponse.proto

@@ -0,0 +1,14 @@
+syntax = "proto3";
+
+package com.igeolise.traveltime.rabbitmq.responses;
+
+message GeohashFastResponse {
+  message Cells {
+    repeated string ids = 1;
+    repeated sint32 minTravelTimes = 2;
+    repeated sint32 maxTravelTimes = 3;
+    repeated sint32 meanTravelTimes = 4;
+  }
+
+  Cells cells = 1;
+}

proto/RequestsCommon.proto

@@ -25,7 +25,7 @@ message PublicTransportDetails {
   // travel time limit
   //
   // walkingTimeToStation must be 0 > and <= 1800
-  // if walkingTimeToStation is not set: use service default
+  // if walkingTimeToStation is not set: use service default 
   // if walkingTimeToStation > 0: limit the path to at most this value
   OptionalPositiveUInt32 walkingTimeToStation = 1;
 }
@@ -68,10 +68,10 @@ enum TransportationType {
   // Considers all paths found by the following steps:
   // * up to 30 minutes of walking (always included even if no stops found)
   // * all connections in the 30 minute walking range from public transport
-  //   stops to other public transport stops in travel_time_limit, AND
+  //   stops to other public transport stops in travel_time_limit, AND 
   // * up to 30 minutes of walking from public transport stops that were visited
   //   by public transport (IOW a path
-  //     [origin]--walking->[stop]--walking-->[destination] is not possible but
+  //     [origin]--walking->[stop]--walking-->[destination] is not possible but 
   //     [origin]--walking->[stop]--public_transport-->[stop]--walking--> is.
   PUBLIC_TRANSPORT = 0;
   // Considers all paths found traveling by car from origin(s) to
@@ -83,9 +83,9 @@ enum TransportationType {
   //   to other public transport stops in travel_time_limit, AND
   // * up to 30 minutes of walking from public transport stops that were visited
   //   by public transport (IOW a path
-  //     [origin]--driving->[stop]--walking-->[destination] is not possible but
+  //     [origin]--driving->[stop]--walking-->[destination] is not possible but 
   //     [origin]--driving->[stop]--public_transport-->[stop]--walking--> is.
-  // AND/OR
+  // AND/OR 
   // * up to 30 minutes of walking
   //
   DRIVING_AND_PUBLIC_TRANSPORT = 2;
@@ -133,4 +133,4 @@ message OptionalPositiveUInt32 {
 // be verified by the server
 message OptionalNonNegativeUInt32 {
   uint32 value = 1;
-}
+}

proto/TimeFilterFastRequest.proto

@@ -55,4 +55,4 @@ message TimeFilterFastRequest {
 
   OneToMany oneToManyRequest = 1;
   ManyToOne manyToOneRequest = 2;
-}
+}