PeekUniverselle PaketverfolgungDein Paket verfolgen
Ratgeber

Open-Source-Sendungsverfolgung: Peeks Code und Engine

7 Min. Lesezeit

Peek ist eine kostenlose Open-Source-Sendungsverfolgung: Web-App, API sowie iPhone- und Android-App liegen unter der Apache License 2.0 auf GitHub, und die Abfrage der Paketdienste übernimmt eine eigenständige Open-Source-Engine, Universal Parcel Scraper. Eine öffentliche API mit Keys hat Peek nicht. Um Pakete aus deinem eigenen Code zu verfolgen, nimm deshalb den Scraper, als Befehl, als Node-Bibliothek oder als HTTP-Server, ohne Konto und ohne API-Key. Du kannst Peek auch selbst hosten oder es mit erfundenen Paketen auf deinem Rechner starten.

So probierst du den Scraper im Terminal aus:

  1. Installiere ihnDu brauchst ein aktuelles Node.js (die Mindestversion steht im README). Führe npm install -g universal-parcel-scraper aus, oder schreib npx universal-parcel-scraper überall dort, wo unten parcel-scraper steht.
  2. Bestimme den Paketdienstparcel-scraper detect 1Z999AA10123456784 sagt dir offline, zu welchem Paketdienst eine Nummer gehört.
  3. Hol den Verlaufparcel-scraper track mit deiner Nummer dahinter fragt beim Paketdienst nach und gibt den Verlauf des Pakets als JSON aus. Passt die Nummer zu mehreren Paketdiensten, häng zum Beispiel --carrier dhl an. Manche Paketdienste wollen außerdem --postcode, --phone-digits oder --tracking-url.

Ist Peek Open Source, und unter welcher Lizenz?

Ja. Peeks Code ist öffentlich auf github.com/plhery/peek-delivery-tracker und steht unter der Apache License 2.0: die Web-App und die API (Next.js, React, TypeScript), die native SwiftUI-App für iPhone, iPad und Mac und die Android-App. Universal Parcel Scraper, den Peek über npm installiert, steht ebenfalls unter Apache 2.0; nur sein optionales TRAWL-Browser-Image steht unter AGPL-3.0.

Peek ist ein nicht kommerzielles Projekt ohne Werbung; Paketverfolgung aller Anbieter vergleicht es mit anderen Trackern.

Fehler und Ideen gehören in Peeks GitHub-Issues, und die sind öffentlich: Lass echte Sendungsnummern, Postleitzahlen und Anmeldecodes weg. Sicherheitsprobleme meldest du über GitHubs private Meldung von Sicherheitslücken. In CONTRIBUTING.md stehen die Prüfungen, die vor einem Pull Request laufen sollen.

Hat Peek eine API, die ich nutzen kann?

Keine öffentliche: Peek vergibt keine API-Keys. Seine API ist die der App selbst, die die Website und die iPhone- und Android-Apps aufrufen, angemeldet mit der Sitzung des Nutzers. Beschrieben ist sie in einer OpenAPI-Datei, die im Repository als contracts/openapi.json liegt; peektracker.com/api selbst antwortet mit 404.

Der Katalog der Paketdienste, GET /api/carriers, braucht keine Anmeldung. Das Verfolgen eines Pakets ohne Konto auch nicht, aber eine neue Abfrage muss dort zuerst eine Prüfung im Browser oder in der App bestehen. Persönliche Tokens für Skripte sind aus, solange der Server sie nicht einschaltet, und in den „Einstellungen“ gibt es keinen Bildschirm, der eins erstellt.

Von außen führt nur ein Weg hinein: die Anmeldung eines Assistenten. Claude, ChatGPT, Gemini oder ein anderer Assistent meldet sich mit Standard-OAuth bei deinem Konto an und nutzt Peeks MCP-Server, https://peektracker.com/mcp, im Rahmen dessen, was du erlaubt hast. Mit demselben Token lassen sich deine Pakete als JSON unter GET /api/parcels lesen, und Peeks Integration für Home Assistant meldet sich auf dieselbe Weise an. Siehe den Ratgeber zu Assistenten, Peeks Seite für Assistenten und den Ratgeber zu Home Assistant.

Wie verfolge ich Pakete aus meinem eigenen Code ohne API-Key?

Mit Universal Parcel Scraper, der Engine, die für Peek die Paketdienste abfragt. Er findet den Paketdienst, liest dessen eigene Website, weicht nur wo nötig auf universelle Tracker aus und liefert für jeden Paketdienst dasselbe JSON, in dem jeder Scan einem gemeinsamen Zustellschritt zugeordnet ist.

Sein README zählt mehr als 3.500 Paketdienste, angebunden über mehr als 800 eigene Adapter und universelle Fallbacks. In seinem Benchmark mit 100 Paketdiensten, ausgewählt für Kunden in Europa, liefern die Adapter für 91 einen Verlauf, mit allen Fallbacks für 95, gegenüber 73 beim besten einzelnen Aggregator.

Neben der Kommandozeile läuft er auf drei Arten:

WoWie
NodeImportiere createTracker aus universal-parcel-scraper/node; tracker.track({ number }) liefert den Paketdienst, wer geantwortet hat, die Scans, den aktuellen Zustellschritt und was der Paketdienst anzeigt, etwa die erwartete Zustellung
Ein BrowserNur die Erkennung des Paketdiensts, mit parseTrackingInput: keine Node-Importe, keine Anfragen
HTTPparcel-scraper serve --port 8080 oder das Docker-Image ghcr.io/plhery/universal-parcel-scraper, das nur mit Release-Versionen getaggt wird; dann per POST an /v1/track. Der Server hält Antworten im Arbeitsspeicher vor und begrenzt die Anfragen pro Aufrufer; er hat keine Datenbank und fragt nie von sich aus nach

Bevor du darauf aufbaust:

  • Er beantwortet jeweils eine Abfrage. Pakete speichern und erneut abfragen musst du selbst: Das ist der Teil, den Peek hinzufügt.
  • Manche Websites von Paketdiensten antworten nur einem Browser. Für sie braucht er ein Chromium, das er über optionale Zusatzpakete steuert, oder seinen TRAWL-Browserdienst. Das Docker-Image bringt Chromium mit.
  • Fallbacks musst du selbst einschalten. Nur UPU ist standardmäßig an; ParcelsApp, Ship24, 17TRACK, Postal Ninja und Track718 warten, bis du sie aktivierst, und jeder, den du aktivierst, bekommt die Sendungsnummer.
  • Eine Abfrage schickt die Nummer an den Paketdienst, mit Postleitzahl, Link oder Ziffern der Telefonnummer, wenn der Paketdienst danach fragt. Telemetrie gibt es keine.

Kann ich Peek selbst hosten?

Ja. Ein selbst gehostetes Peek ist ein einziger, dauerhaft laufender Container mit der Web-App, der API und dem Worker, der immer wieder bei den Paketdiensten nachfragt, daneben Supabase für die Anmeldung und Postgres, hinter HTTPS. Du brauchst:

  • einen Supabase-Stack (Auth, PostgREST und Postgres) mit getestetem Backup und Restore;
  • SMTP, wenn die Anmeldung per E-Mail oder die Zustell-E-Mail eingeschaltet ist;
  • einen Host, der das Dockerfile bauen und den Container am Laufen halten kann. Serverless-Hosting funktioniert nicht: Der Worker muss am Leben bleiben.

Web-Push, Mitteilungen auf dem iPhone (ein Apple-Team und ein APNs-Key) und auf Android (Firebase) sind optional. Assistenten auch: Ohne ASSISTANT_ACCOUNTS gibt es /mcp und /oauth nicht. Die Einstellung listet die Konten, die sich verbinden dürfen, oder * für alle, und braucht CANONICAL_ORIGIN. Ist sie gesetzt, schaltet PERSONAL_TOKENS=on persönliche Tokens für deine Skripte ein, die du über die API erstellst. docs/DEPLOYMENT.md enthält die Schritte, von der Datenbank und der Anmeldung bis zu Upgrades, Backups und dem Umzug auf einen anderen Host.

Erst auf deinem Rechner ausprobieren

Kein Konto, keine Datenbank und keine .env-Datei nötig:

  1. Hol den CodeKlone https://github.com/plhery/peek-delivery-tracker.git. Du brauchst nvm und die Node.js-Version, die im README steht.
  2. InstalliereFühre in seinem Ordner nvm use aus, dann npm ci.
  3. StarteFühre npm run dev aus und öffne localhost:3000: Peek antwortet im Browser mit erfundenen Paketen. Unter localhost:3000/demo steht eine Liste von Beispiellieferungen, die bei jedem Neuladen ein Stück weiterkommen.

Für echte Konten und echte Sendungsverfolgung kopierst du .env.example nach .env.local, trägst ein Supabase-Projekt ein und setzt NEXT_PUBLIC_USE_API=true; in docs/AUTHENTICATION.md stehen die Schritte für die Anmeldung. Die iPhone-App lässt sich in Xcode für einen iPhone-Simulator bauen und startet mit Beispielpaketen, ohne Konto, Server oder Apple-Team.

Ein Paketdienst fehlt: Wie melde oder ergänze ich ihn?

Melde ihn beim Scraper, denn dort leben die Paketdienste. Auf seiner Seite für ein neues Issue, die Peeks README als „Tell the scraper“ verlinkt, wählst du „Add a carrier“ (Name, Heimatland und öffentliche Tracking-Website des Paketdiensts) oder „A carrier stopped working“. Neue Paketdienste und Korrekturen gehen als Pull Requests an den Scraper: Jeder Paketdienst hat einen eigenen Ordner mit synthetischen Fixtures und Offline-Tests, und npm run carrier:new legt das Grundgerüst für einen neuen an.

Peek übernimmt neue Releases des Scrapers von selbst, ein Paketdienst braucht also keinen Pull Request an Peek. Und die iPhone-App holt sich ihre Liste der Paketdienste neu vom Server, also braucht es auch kein neues App-Release.

Kein GitHub-Konto? Sag es Peek auf der Seite des Pakets, im Web, auf dem iPhone oder auf Android, mit oder ohne Peek-Konto:

  1. Beantworte die FrageFindet Peek für ein Paket keinen Paketdienst, fragt seine Seite „Zeigt die Website des Paketdiensts das Paket?“ Wähle „Ja“.
  2. Nenne den PaketdienstGib ihn unter „Wer liefert es?“ bei „Paketdienst oder Shop“ an, oder füge seinen Tracking-Link bei „Seine Tracking-Seite, falls du den Link hast“ ein. Eins von beiden reicht.
  3. Schick es abWähle „Senden“. Mitgeschickt wird die Nummer des Pakets, nichts über dich.

Ein Mensch liest diese Antworten, aber niemand kann dir zurückschreiben: Wenn du eine Antwort möchtest, schreib an hello@peektracker.com, die Adresse auf Peeks Hilfeseite. Wie Peek aus dem, was du einfügst, den Paketdienst bestimmt, steht in Paket verfolgen, ohne den Paketdienst zu kennen.

Quellen