Partner-API — öffentliche Katalogdaten

Registrierte Dienste können Orte und Events aus mostlyharmless.travel maschinenlesbar abfragen und in eigenen Apps anzeigen — serverseitig, mit API-Key, nicht im Browser.

Was ist das?

Eine versionierte Read-API unter /api/v1/partner. Sie liefert geprüfte, öffentliche Artikel (Places, Events, Objects) inklusive Geo, Lizenzen und einem Änderungs-Feed zum synchronisieren.

Zugang

Die API ist nicht öffentlich anonym nutzbar. Wir stellen registrierten Partnern einen API-Key aus. Schreib uns kurz, was ihr vorhabt — dann richten wir einen Partner-Zugang ein.

Kontakt

Schnellstart (technisch)

API-Key erhalten (einmalig als Klartext; danach nur noch keyId sichtbar).
Jeden Request nur per HTTPS vom eigenen Backend senden.
Authorization-Header setzen und z. B. GET /api/v1/partner/articles aufrufen.

Header-Format:

Authorization: Bearer mh_pk_<keyId>_<secret>

Den Key nicht in Webseiten oder Mobile Apps einbetten. Es gibt bewusst keine CORS-Freigabe für Browser-Clients.

Wichtige Endpunkte

Basis-Pfad auf diesem Server:

GET /api/v1/partner/articles
GET /api/v1/partner/articles/{id}
GET /api/v1/partner/geo/articles?bbox=west,south,east,north
GET /api/v1/partner/changes

Vollständige Spezifikation (OpenAPI 3): openapi/partner-v1.yaml

Datenformat (DTO)

DTO steht für „Data Transfer Object“: ein fest definiertes JSON-Objekt pro Artikel, das nur die Felder enthält, die Partner sehen dürfen — ohne interne Moderation, Autoren oder Statistiken. Beispiel-Felder:

id, permalink, type (Place / Event / Object)
title, description (Klartext, Sprache per ?lang=)
geo, location, Event-Felder bei Bedarf
license, source — Herkunft und Nutzungsrecht pro Datensatz
updatedAt — für Sync; Feed unter /changes mit upsert und delete

Limits & Fair Use

Pro Partner gilt ein Request-Kontingent (konfigurierbar). Antworten können per ETag gecacht werden (304). Bitte Tombstones aus /changes verarbeiten, damit entfernte Inhalte auch bei euch verschwinden.

Self-Service (geplant)

Registriere ein normales Konto. Nach Freischaltung durch uns (Rolle partnerApi + Verknüpfung) verwaltest du API-Keys unter /partner — erzeugen, widerrufen, Nutzung der letzten 30 Tage einsehen.

Zum Partner-Portal (Login erforderlich)