Release v1.5.1: Refine trip metrics and reduce API load

Syax89 · Syax89 · commit 84d03c83cb92 · 2026-03-18T11:29:34.000+01:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,16 @@
 
 All notable changes to this project are documented in this file.
 
+## [1.5.1] - 2026-03-18
+
+### Changed
+- **Trip Metrics**: Updated the 7-day average speed sensor to use Geotab's trip `averageSpeed` so it now represents true driving speed instead of averaging peak speeds.
+- **API Load**: Reduced trip and fault fetch limits, and moved Go fault diagnostic lookups to on-demand loading so normal polling avoids an unnecessary extra multi-call payload.
+
+### Fixed
+- **Developer Documentation**: Added README instructions for running `debug_geotab.py` safely with environment variables.
+- **Translations**: Renamed the average speed sensor labels across all bundled translations to match the corrected metric.
+
 ## [1.5.0] - 2026-03-18
 
 ### Changed
diff --git a/README.md b/README.md
@@ -42,7 +42,7 @@ Entities are logically categorized to ensure a streamlined user interface and ef
 
 ### Trip Statistics
 * **Aggregated Metrics**: Daily, weekly, and monthly distance tracking.
-* **Operational Analysis**: Trip counts and weekly idle time reports.
+* **Operational Analysis**: Trip counts, average driving speed, and weekly idle time reports.
 * **Last Journey**: Comprehensive data on the most recently completed trip.
 
 ---
@@ -81,12 +81,27 @@ Entities are logically categorized to ensure a streamlined user interface and ef
 
 ## 🛡️ Technical Integrity & Security
 
-* **API Optimization**: Utilizes an asynchronous architecture to minimize blocking calls and optimize performance during high-volume data retrieval.
+* **API Optimization**: Utilizes an asynchronous architecture, cached fault metadata, and a reduced trip window to minimize unnecessary API load during high-volume polling.
 * **Resilience**: Features a robust circuit breaker mechanism and automated error recovery to handle API outages or connectivity fluctuations gracefully.
 * **Privacy**: Implements data masking protocols for sensitive account information within the public-facing user interface.
 
 ---
 
+## 🧪 Local Debug
+
+The repository includes `debug_geotab.py` for manual local checks against the Geotab API.
+
+Before running it, export your credentials as environment variables instead of editing the file:
+
+```bash
+export GEOTAB_USERNAME="your@email.com"
+export GEOTAB_PASSWORD="your-password"
+export GEOTAB_DATABASE="your-database"
+python3 debug_geotab.py
+```
+
+---
+
 ## 📖 Further Documentation
 
 For comprehensive technical specifications, automation templates, and advanced troubleshooting, please refer to the [Documentation folder](docs/).
diff --git a/custom_components/geotab/api.py b/custom_components/geotab/api.py
@@ -16,8 +16,8 @@
 _LOGGER = logging.getLogger(__name__)
 
 TRIP_HISTORY_DAYS = 30
-TRIP_RESULTS_LIMIT = 500
-FAULT_RESULTS_PER_DEVICE = 20
+TRIP_RESULTS_LIMIT = 250
+FAULT_RESULTS_PER_DEVICE = 10
 
 
 class GeotabApiClientError(Exception):
@@ -102,24 +102,12 @@ def _blocking_fetch_all(self, include_trips: bool = True) -> tuple[list, list, l
                         "deviceSearch": {"deviceIds": device_ids},
                         "state": "Active",
                     },
-                    "resultsLimit": max(len(device_ids) * FAULT_RESULTS_PER_DEVICE, 100),
+                    "resultsLimit": max(len(device_ids) * FAULT_RESULTS_PER_DEVICE, 20),
                 },
             ),
         ]
         call_map = ["status", "faults"]
 
-        if not self._diagnostics_lookup_cache:
-            calls.append(
-                (
-                    "Get",
-                    {
-                        "typeName": "Diagnostic",
-                        "search": {"diagnosticType": "GoFault"},
-                    },
-                )
-            )
-            call_map.append("diagnostics_lookup")
-
         if include_trips:
             from_date = (
                 datetime.now(timezone.utc) - timedelta(days=TRIP_HISTORY_DAYS)
@@ -143,6 +131,19 @@ def _blocking_fetch_all(self, include_trips: bool = True) -> tuple[list, list, l
         results = self.client.multi_call(calls)
         return devices, results, call_map
 
+    def _blocking_load_fault_diagnostics(self) -> dict[str, str]:
+        """Load diagnostic names for Geotab Go faults on demand."""
+        result = self.client.get("Diagnostic", search={"diagnosticType": "GoFault"})
+        lookup: dict[str, str] = {}
+        for diagnostic in result:
+            if not isinstance(diagnostic, dict):
+                continue
+            diagnostic_id = diagnostic.get("id")
+            diagnostic_name = diagnostic.get("name")
+            if diagnostic_id and diagnostic_name:
+                lookup[diagnostic_id] = diagnostic_name
+        return lookup
+
     def _extract_status_diagnostics(self, status_info: dict[str, Any]) -> dict[str, Any]:
         """Extract latest diagnostics already embedded in DeviceStatusInfo."""
         diagnostics: dict[str, Any] = {}
@@ -178,6 +179,7 @@ async def async_get_full_device_data(
             fault_map: defaultdict[str, list[dict[str, Any]]] = defaultdict(list)
             trip_results_dict: dict[str, list[dict[str, Any]]] = {}
             diagnostics_lookup = dict(self._diagnostics_lookup_cache)
+            unknown_fault_diagnostic_ids: set[str] = set()
 
             for index, key in enumerate(call_map):
                 result = results[index]
@@ -205,15 +207,11 @@ async def async_get_full_device_data(
                         device = fault.get("device")
                         if isinstance(device, dict) and device.get("id"):
                             fault_map[device["id"]].append(fault)
-
-                elif key == "diagnostics_lookup" and isinstance(result, list):
-                    for diagnostic in result:
-                        if not isinstance(diagnostic, dict):
-                            continue
-                        diagnostic_id = diagnostic.get("id")
-                        diagnostic_name = diagnostic.get("name")
-                        if diagnostic_id and diagnostic_name:
-                            diagnostics_lookup[diagnostic_id] = diagnostic_name
+                            diagnostic = fault.get("diagnostic")
+                            if isinstance(diagnostic, dict):
+                                diagnostic_id = diagnostic.get("id")
+                                if diagnostic_id and diagnostic_id not in diagnostics_lookup:
+                                    unknown_fault_diagnostic_ids.add(diagnostic_id)
 
                 elif key.startswith("trip_") and isinstance(result, list):
                     device_id = key[5:]
@@ -229,6 +227,14 @@ async def async_get_full_device_data(
                             reverse=True,
                         )
 
+            if unknown_fault_diagnostic_ids:
+                diagnostics_lookup.update(
+                    await asyncio.wait_for(
+                        loop.run_in_executor(None, self._blocking_load_fault_diagnostics),
+                        timeout=20,
+                    )
+                )
+
             self._diagnostics_lookup_cache = diagnostics_lookup
 
             total_diagnostics = sum(len(values) for values in diagnostics_map.values())
diff --git a/custom_components/geotab/manifest.json b/custom_components/geotab/manifest.json
@@ -7,5 +7,5 @@
   "iot_class": "cloud_polling",
   "issue_tracker": "https://github.com/Syax89/geotab-hacs-integration/issues",
   "requirements": ["mygeotab>=0.9.1,<1.0.0"],
-  "version": "1.5.0"
+  "version": "1.5.1"
 }
diff --git a/custom_components/geotab/strings.json b/custom_components/geotab/strings.json
@@ -52,7 +52,7 @@
       "monthly_distance": { "name": "Monthly Distance" },
       "daily_trip_count": { "name": "Daily Trip Count" },
       "weekly_trip_count": { "name": "Weekly Trip Count" },
-      "average_trip_speed": { "name": "Average Trip Speed (7d)" },
+      "average_trip_speed": { "name": "Average Driving Speed (7d)" },
       "weekly_idle_time": { "name": "Weekly Idle Time" },
       "last_update": { "name": "Last Update" }
     },
diff --git a/custom_components/geotab/translations/de.json b/custom_components/geotab/translations/de.json
@@ -52,7 +52,7 @@
       "monthly_distance": { "name": "Fahrten: Monatliche Strecke" },
       "daily_trip_count": { "name": "Fahrten: Anzahl täglicher Fahrten" },
       "weekly_trip_count": { "name": "Fahrten: Anzahl wöchentlicher Fahrten" },
-      "average_trip_speed": { "name": "Fahrten: Durchschnittsgeschwindigkeit (7t)" },
+      "average_trip_speed": { "name": "Fahrten: Durchschnittliche Fahrgeschwindigkeit (7t)" },
       "weekly_idle_time": { "name": "Fahrten: Wöchentliche Leerlaufzeit" },
       "last_update": { "name": "Letzte Aktualisierung" }
     },
diff --git a/custom_components/geotab/translations/en.json b/custom_components/geotab/translations/en.json
@@ -52,7 +52,7 @@
       "monthly_distance": { "name": "Trips: Monthly Distance" },
       "daily_trip_count": { "name": "Trips: Daily Trip Count" },
       "weekly_trip_count": { "name": "Trips: Weekly Trip Count" },
-      "average_trip_speed": { "name": "Trips: Avg Speed (7d)" },
+      "average_trip_speed": { "name": "Trips: Avg Driving Speed (7d)" },
       "weekly_idle_time": { "name": "Trips: Weekly Idle Time" },
       "last_update": { "name": "Last Update" }
     },
diff --git a/custom_components/geotab/translations/es.json b/custom_components/geotab/translations/es.json
@@ -52,7 +52,7 @@
       "monthly_distance": { "name": "Viajes: Distancia mensual" },
       "daily_trip_count": { "name": "Viajes: Contador de viajes diario" },
       "weekly_trip_count": { "name": "Viajes: Contador de viajes semanal" },
-      "average_trip_speed": { "name": "Viajes: Velocidad media (7d)" },
+      "average_trip_speed": { "name": "Viajes: Velocidad media de marcha (7d)" },
       "weekly_idle_time": { "name": "Viajes: Tiempo al ralentí semanal" },
       "last_update": { "name": "Última actualización" }
     },
diff --git a/custom_components/geotab/translations/fr.json b/custom_components/geotab/translations/fr.json
@@ -52,7 +52,7 @@
       "monthly_distance": { "name": "Trajets : Distance mensuelle" },
       "daily_trip_count": { "name": "Trajets : Nombre de trajets quotidiens" },
       "weekly_trip_count": { "name": "Trajets : Nombre de trajets hebdomadaires" },
-      "average_trip_speed": { "name": "Trajets : Vitesse moyenne (7j)" },
+      "average_trip_speed": { "name": "Trajets : Vitesse moyenne de conduite (7j)" },
       "weekly_idle_time": { "name": "Trajets : Temps au ralenti hebdomadaire" },
       "last_update": { "name": "Dernière mise à jour" }
     },
diff --git a/custom_components/geotab/translations/it.json b/custom_components/geotab/translations/it.json
@@ -52,7 +52,7 @@
       "monthly_distance": { "name": "Viaggi: Distanza Mensile" },
       "daily_trip_count": { "name": "Viaggi: Numero Viaggi Giornalieri" },
       "weekly_trip_count": { "name": "Viaggi: Numero Viaggi Settimanali" },
-      "average_trip_speed": { "name": "Viaggi: Velocità Media (7g)" },
+      "average_trip_speed": { "name": "Viaggi: Velocità Media di Marcia (7g)" },
       "weekly_idle_time": { "name": "Viaggi: Tempo al Minimo Settimanale" },
       "last_update": { "name": "Ultimo Aggiornamento" }
     },
diff --git a/custom_components/geotab/translations/nl.json b/custom_components/geotab/translations/nl.json
@@ -52,7 +52,7 @@
       "monthly_distance": { "name": "Ritten: Maandelijkse afstand" },
       "daily_trip_count": { "name": "Ritten: Aantal ritten per dag" },
       "weekly_trip_count": { "name": "Ritten: Aantal ritten per week" },
-      "average_trip_speed": { "name": "Ritten: Gemiddelde snelheid (7d)" },
+      "average_trip_speed": { "name": "Ritten: Gemiddelde rijsnelheid (7d)" },
       "weekly_idle_time": { "name": "Ritten: Wekelijkse stationaire tijd" },
       "last_update": { "name": "Laatste update" }
     },
diff --git a/custom_components/geotab/translations/pt.json b/custom_components/geotab/translations/pt.json
@@ -52,7 +52,7 @@
       "monthly_distance": { "name": "Viagens: Distância mensal" },
       "daily_trip_count": { "name": "Viagens: Número de viagens diárias" },
       "weekly_trip_count": { "name": "Viagens: Número de viagens semanais" },
-      "average_trip_speed": { "name": "Viagens: Velocidade média (7d)" },
+      "average_trip_speed": { "name": "Viagens: Velocidade média em condução (7d)" },
       "weekly_idle_time": { "name": "Viagens: Tempo em marcha lenta semanal" },
       "last_update": { "name": "Última atualização" }
     },
diff --git a/custom_components/geotab/trip_stats.py b/custom_components/geotab/trip_stats.py
@@ -83,9 +83,9 @@ def weekly_trip_count(trips: list[dict]) -> int:
 
 
 def average_trip_speed(trips: list[dict]) -> float | None:
-    """Average of maximumSpeed across trips in the last 7 days (km/h)."""
+    """Average driving speed across trips in the last 7 days (km/h)."""
     recent = _filter_trips_since(trips, 7 * 24)
-    speeds = [t["maximumSpeed"] for t in recent if t.get("maximumSpeed") is not None]
+    speeds = [t["averageSpeed"] for t in recent if t.get("averageSpeed") is not None]
     if not speeds:
         return None
     return round(sum(speeds) / len(speeds), 1)
diff --git a/tests/conftest.py b/tests/conftest.py
@@ -17,10 +17,16 @@ def mock_geotab_api():
         instance = mock.return_value
         instance.authenticate.return_value = True
 
-        # Mock for .get("Device")
-        instance.get.return_value = [{"id": "device1", "name": "Test Vehicle", "deviceType": "GO9"}]
+        def _mock_get(type_name, *args, **kwargs):
+            if type_name == "Device":
+                return [{"id": "device1", "name": "Test Vehicle", "deviceType": "GO9"}]
+            if type_name == "Diagnostic":
+                return [{"id": "diag1", "name": "Test Diagnostic"}]
+            return []
 
-        # Prepare mock results for multi_call: status, faults, diagnostics lookup, and trips.
+        instance.get.side_effect = _mock_get
+
+        # Prepare mock results for multi_call: status, faults, and trips.
         # Order MUST match api.py _blocking_fetch_all.
         instance.multi_call.return_value = [
             # 0. Status
@@ -67,9 +73,7 @@ def mock_geotab_api():
                 "diagnostic": {"id": "diag1"},
                 "faultDescription": "Test fault"
             }],
-            # 2. Diagnostics Lookup
-            [{"id": "diag1", "name": "Test Diagnostic"}],
-            # 3. Trip Result for device1
+            # 2. Trip Result for device1
             [
                 {"id": "trip1", "distance": 15.0, "start": "2026-03-08T10:00:00Z", "stop": "2026-03-08T10:30:00Z", "maximumSpeed": 80, "drivingDuration": "PT25M", "idlingDuration": "PT5M"},
                 {"id": "trip2", "distance": 22.5, "start": "2026-03-07T08:00:00Z", "stop": "2026-03-07T08:45:00Z", "maximumSpeed": 100, "drivingDuration": "PT40M", "idlingDuration": "PT3M"},
diff --git a/tests/test_api.py b/tests/test_api.py
@@ -67,7 +67,7 @@ async def test_api_get_data(mock_geotab_api):
 @pytest.mark.asyncio
 async def test_api_get_data_empty_devices(mock_geotab_api):
     """Test that empty dict is returned when no devices exist."""
-    mock_geotab_api.get.return_value = []
+    mock_geotab_api.get.side_effect = lambda type_name, *args, **kwargs: [] if type_name == "Device" else []
     session = MagicMock()
     client = GeotabApiClient("user", "pass", "db", session)
     data = await client.async_get_full_device_data()
diff --git a/tests/test_trip_stats.py b/tests/test_trip_stats.py
@@ -32,6 +32,7 @@ def _make_trip(
     distance: float = 10.0,
     hours_ago: float = 1.0,
     max_speed: float = 80.0,
+    avg_speed: float = 60.0,
     idle_duration: str = "PT5M",
 ) -> dict:
     """Create a trip dict with a start time N hours ago."""
@@ -41,6 +42,7 @@ def _make_trip(
         "start": start.isoformat(),
         "stop": (start + timedelta(minutes=30)).isoformat(),
         "maximumSpeed": max_speed,
+        "averageSpeed": avg_speed,
         "idlingDuration": idle_duration,
     }
 
@@ -125,10 +127,10 @@ class TestAverageTripSpeed:
 
     def test_average(self):
         trips = [
-            _make_trip(max_speed=80, hours_ago=1),
-            _make_trip(max_speed=120, hours_ago=24),
+            _make_trip(max_speed=80, avg_speed=55, hours_ago=1),
+            _make_trip(max_speed=120, avg_speed=85, hours_ago=24),
         ]
-        assert average_trip_speed(trips) == 100.0
+        assert average_trip_speed(trips) == 70.0
 
     def test_no_recent_trips(self):
         trips = [_make_trip(max_speed=80, hours_ago=200)]

Original file line number	Diff line number	Diff line change
`@@ -7,5 +7,5 @@`
`7`	`7`	`"iot_class": "cloud_polling",`
`8`	`8`	`"issue_tracker": "https://github.com/Syax89/geotab-hacs-integration/issues",`
`9`	`9`	`"requirements": ["mygeotab>=0.9.1,<1.0.0"],`
`10`		`- "version": "1.5.0"`
	`10`	`+ "version": "1.5.1"`
`11`	`11`	`}`