API Connect

Mit der REST-API von GPS-WATCH Connect können Sie Daten aus Ihrem Benutzerkonto in eigene Anwendungen übernehmen. Typische Anwendungen sind eine Fahrzeugübersicht, die Anzeige letzter Standorte oder die Weiterverarbeitung von Fahrten und bereits erzeugten Berichten.

Diese Anleitung führt durch die ersten lesenden Anfragen. Die vollständige API-Referenz beschreibt außerdem weitere Funktionen, beispielsweise Aufgaben, Ereignisse, Geozäune und Befehle. Prüfen Sie vor der Integration die benötigten Endpunkte und deren Berechtigungen.

Zugang und Berechtigungen

Für den Zugriff benötigen Sie ein aktives Connect-Benutzerkonto mit freigeschaltetem API-Zugang und einen zugehörigen API-Schlüssel. Im Handbuchabschnitt Benutzerkonto wird der API-Schlüssel beschrieben; die Freischaltung erfolgt durch den Administrator in der Verwaltung. Falls Ihnen der Zugang fehlt, wenden Sie sich an Ihren Administrator oder an support@gps-watch.de.

Der API-Schlüssel wird im HTTP-Header X-API-Key übertragen. Die Basisadresse für die Anfragen lautet:

https://connect.gps-watch.de/api/rest

Die API berücksichtigt die Zugriffsrechte des Benutzers. Bei Unterkonten müssen Objekte sowohl zum Hauptkonto gehören als auch durch die wirksamen IMEI-Berechtigungen des Unterkontos freigegeben sein. Die Rolle „Fleet Manager“ gewährt Zugriff auf die gesamte Flotte des Hauptkontos. Wählen Sie für eine Integration ein Konto mit den tatsächlich benötigten Rechten.

Behandeln Sie den Schlüssel wie ein Passwort. Hinterlegen Sie ihn in der geschützten Konfiguration Ihrer Anwendung und halten Sie ihn aus öffentlich ausgeliefertem Browsercode, Quellcode-Repositories und Protokollen heraus.

Optional stellt die API POST /auth/api-key bereit, um den eigenen Schlüssel mit den Anmeldedaten abzurufen. Auch dafür müssen das Konto aktiv und der API-Zugang freigeschaltet sein. Details stehen in der API-Referenz im Abschnitt Auth. Für die folgenden Beispiele genügt ein bereits vorliegender Schlüssel.

Schnellstart mit cURL

Die Beispiele sind für eine Shell mit cURL vorgesehen. Ersetzen Sie den Platzhalter durch Ihren API-Schlüssel. In einer produktiven Anwendung laden Sie den Wert aus Ihrer geschützten Konfiguration.

GPS_WATCH_API_KEY='IHR_API_SCHLUESSEL'

curl --silent --show-error --include \
  --header "X-API-Key: ${GPS_WATCH_API_KEY}" \
  'https://connect.gps-watch.de/api/rest/objects'

Die Anfrage verwendet GET und liefert die für das Konto verfügbaren Objekte. --include zeigt zusätzlich zum Antwortinhalt die HTTP-Header, damit Sie den Status der Anfrage prüfen können. Die Objektliste steht im Feld data; für Objekte sind unter anderem die Felder imei und name dokumentiert. Die IMEI dient bei objektbezogenen Anfragen als Kennung.

Ermitteln Sie zuerst eine zugängliche IMEI aus dieser Liste. Übernehmen Sie Gerätekennungen als Zeichenfolgen in Ihre Anwendung.

Letzte Standorte abrufen

Für die letzten Standorte aller zugänglichen Objekte verwenden Sie:

curl --silent --show-error --include \
  --header "X-API-Key: ${GPS_WATCH_API_KEY}" \
  'https://connect.gps-watch.de/api/rest/objects/locations'

Die Antwort enthält unter data die nach IMEI zugeordneten Standorte. Dokumentiert sind beispielsweise die Felder lat, lng, speed, dt_server und dt_tracker. Mehrere dieser Werte sind im Schema als Zeichenfolgen definiert; berücksichtigen Sie das bei der Verarbeitung.

Mit dem optionalen Parameter imeis lässt sich die Auswahl einschränken: * steht für alle zugänglichen Objekte, mehrere IMEIs werden durch Semikolons getrennt. Für genau ein Objekt gibt es außerdem GET /objects/{imei}/location. Ein letzter Standort kann älter sein; berücksichtigen Sie die gelieferten Zeitangaben bei der Anzeige.

Fahrten und Verlauf auswerten

GET /objects/{imei}/route liefert den Verlauf eines Objekts. Pflichtparameter sind from, to und min_stop_duration. Wählen Sie die IMEI aus der Objektliste und einen Zeitraum mit vorhandenen Daten. Zeitangaben und Einheiten folgen den Kontoeinstellungen. Das dokumentierte Datumsformat und die weiteren Parameter finden Sie in der API-Referenz.

Die Stoppschwelle ist in Minuten angegeben. Ein Stopp trennt Fahrten erst, wenn seine Dauer die Schwelle überschreitet; die vorhandenen Einstellungen zur Stopperkennung gelten weiterhin.

summary=true liefert Stopps, Fahrten und verfügbare Summen ohne die vollständigen Streckenpunkte und Ereignisse. Optional ergänzt include_zones=true passende, aktuell freigegebene Geozonen. Diese Zuordnung verwendet die heutigen Zonendefinitionen.

Besonderheit der Antwort: Der Routenendpunkt liefert das bestehende Routen-JSON direkt an der Wurzel, ohne die sonst übliche Hülle aus success und data. Verfügbare Felder können mit den Daten variieren. Weitere Verlaufsdaten bieten GET /objects/{imei}/messages und GET /objects/{imei}/events, jeweils mit from und to.

Vorhandene Berichte übernehmen

Über GET /reports/generated listen Sie bereits erzeugte Berichte auf. Mit der jeweiligen Berichtskennung rufen Sie anschließend GET /reports/{report_id}/content für den Inhalt oder GET /reports/{report_id}/download für die Berichtsdatei auf. Der Download ist als Dateiantwort dokumentiert.

Diese Endpunkte greifen auf erzeugte Berichte zu. Wie Sie Berichte in Connect einrichten und erstellen, beschreibt das Kapitel Berichte.

Antworten und Fehler prüfen

Prüfen Sie HTTP-Status und Antwortinhalt gemeinsam. Die Referenz beschreibt für die üblichen JSON-Antworten success und data, für Fehler success: false sowie error.code und error.message. Beachten Sie die abweichende Routen- und Dateiantwort.

• HTTP 401: Bei den oben genannten Listenabfragen dokumentiert. Prüfen Sie zunächst den Header X-API-Key und den verwendeten Schlüssel.
• HTTP 403 oder 404: Beim Einzelstandort dokumentiert. Prüfen Sie Kennung und Zugriffsrechte; beim Berichtsdownload ist ebenfalls 404 dokumentiert.
• HTTP 422 beim Verlauf: Für ungültige Werte von summary oder include_zones dokumentiert. Zulässig sind true, false, 1 und 0; fehlende oder leere Werte bedeuten false.

Beim Routenabruf mit Zonen kann ein Fehler beim Laden der Zonen trotz HTTP 200 als Text ERROR: route zones could not be loaded. zurückkommen. Verlassen Sie sich dort deshalb nicht allein auf den HTTP-Status.

Vollständige Referenz

Die interaktive API-Dokumentation enthält die Endpunkte, Parameter und verfügbaren Antwortschemas. Die zugrunde liegende Swagger-Spezifikation kann auch für die technische Integration genutzt werden. Die Beispiele und Hinweise dieser Seite wurden am 8. November 2026 mit dieser Spezifikation abgeglichen.

Zur Kapitelübersicht: Handbuch Connect