MyGeotab exposes detailed measurements for vehicles and assets, but a correct request is more than a method name and an entity type. The integration must bound high-volume reads, use the right diagnostic filter, interpret values with their units, and preserve synchronization progress. This guide assembles those reference details into a production-safe telemetry workflow.
Decide whether the application is answering a bounded question or maintaining a synchronized copy. Repeatedly scanning history withGet is not a substitute for a feed cursor.
| Need | Use | Reason |
|---|---|---|
| Measurements for known devices during a short time window | Get with a bounded StatusDataSearch | The device, diagnostic, and UTC time range make the question explicit. |
| New and corrected telemetry processed continuously | GetFeed | A durable version cursor avoids rescanning the same history and preserves later corrections. StatusData search filters are ignored by GetFeed, so the API user's data scope determines the feed. |
| Large historical reporting or analytics | Data Connector | Analytical workloads do not compete with operational API traffic. |
A common architecture uses Get for a small interactive window and GetFeedto maintain a local store. Save a feed's toVersion only after its records are durably processed, and make processing safe to repeat. See the Data Feed guide for checkpoint and invalidation behavior.
StatusData GetFeed ignores search criteria and returns the feed visible to the API user. Do not rely on a device or diagnostic search to reduce it. Use a dedicated API user with an intentional data scope, filter each batch locally, and use boundedGet when the integration must retrieve only a restricted device subset.
StatusData is a measurement, not the definition of that measurement. Its data property is the numeric value, dateTime is when it was logged, and its device anddiagnostic properties identify what produced the value and what the value means.
unitOfMeasure.data as raw data until the diagnostic supplies its meaning and unit. For example, do not label or convert a value based only on its magnitude.Tire-pressure diagnostics return raw StatusData.data in pascals (Pa), identified byUnitOfMeasurePascalsId. Convert only after checking that unit ID: kPa = Pa / 1000,psi = Pa / 6894.757293, and bar = Pa / 100000. For example, a raw value of 6895 is about6.9 kPa, 1.0 psi, or 0.069 bar.
When a StatusData search includes both a device and a diagnostic, the service can create values at the requested time boundaries by interpolation. These generated rows have no id. Do not discard them or deduplicate solely by ID; use the device, diagnostic, timestamp, and the application's purpose to decide how boundary values should be handled.
Always provide an explicit device and UTC fromDate and toDate when retrieving historical StatusData. A request without those constraints can scan far more telemetry than the application intended.
resultsLimit explicitly. If the response reaches that limit, treat the window as possibly incomplete and split it into smaller time ranges or implement the supported Date/Version pagination; do not silently use a truncated result.Short, bounded windows also make recovery predictable. A retry repeats a known unit of work instead of launching another open-ended scan.
DiagnosticSearch supports an ids collection when retrieving Diagnostic entities. Its use inside StatusDataSearch.diagnosticSearch is narrower: only id is a documented option, so it represents one diagnostic.
| Requested diagnostics | Reliable StatusData pattern | Why |
|---|---|---|
| One | Try the bounded server-side diagnosticSearch.id filter. If it returns no rows, make one bounded request for the same device and time range without that filter, then filter locally. | In practice, some KnownId diagnostics can be present in the bounded device window even when the equivalent filtered request is empty. The bounded fallback preserves correctness without creating an unbounded query. Apply the result-limit guard to the filtered response before testing whether it is empty: if the response reaches the limit, split the UTC range instead of falling back or widening the window. |
| More than one | Make one bounded device-and-time request and filter the returned rows against an ID set in the client. | This is a bounded workaround used by maintained tooling, not a documented efficient search combination. Keep the window small; it avoids an API loop that repeats the same window once per diagnostic. |
Keep the unfiltered fallback conditional and bounded. It is a narrow recovery path for one known diagnostic, not permission to retrieve all StatusData in a database. An empty result can also mean the API user cannot see the device or data, so test with production-equivalent clearances.
This JavaScript example searches for exactly one device, reads one or several diagnostics safely, rejects a possibly truncated response, and loads the Diagnostic definitions needed to interpret each value. Replace the example KnownId values with the diagnostics required by the application.
The equivalent .NET example uses the Geotab.Checkmate.ObjectModel types, including strongly typed KnownId values. The same safety invariants apply: one exact device, an explicit UTC range, no per-diagnostic API loop, a bounded single-ID fallback, and a hard response limit check.
Compile the example against the Geotab.Checkmate.ObjectModel package version the application deploys. See the .NET client guide for package setup and authentication behavior.