OpenBookCase Entwickler-API

Baue Apps auf den OpenBookCase-Daten. Das Lesen öffentlicher Daten ist frei — kein Schlüssel nötig. Zum Schreiben (Einträge anlegen/bearbeiten, Fotos, Wunschlisten, …) brauchst du ein OAuth-2.0-Access-Token, das im Namen einer deiner Nutzer:innen handelt. Alle Anfragen sind JSON rein / JSON raus und liegen unter /api/v1.

Basis-URL in der Produktion: https://openbookcase.de

So funktioniert es

  • Freies Lesen: die Kartenausschnitts-Liste, einzelne Einträge sowie deren Fotos und Wunschlisten sind öffentlich — ohne Token abrufbar.
  • Authentifiziertes Schreiben: jede Änderung erfolgt als eine deiner Nutzer:innen. Sie autorisieren deine App einmalig (OAuth), dein Token legt dann Daten in ihrem Namen an/bearbeitet sie.
  • Keine Konto-Endpunkte: bewusst keine API für E-Mail, Passwort, Benachrichtigungen oder Kontolöschung.
  • Offene Daten: der Datenbestand stammt aus OpenStreetMap und steht unter der ODbL — siehe Datenlizenz.

Zugang erhalten

Öffne Profil → API-Zugang und stelle einen Antrag, der deine App und die geplante Datennutzung beschreibt. Ein Admin prüft ihn (mit eingebautem Rückfrage-Dialog bei Fragen). Nach Freigabe erhältst du deine Zugangsdaten:

  • Public Client (Mobil-/Single-Page-Apps): eine client_id, kein Secret. Muss PKCE verwenden.
  • Confidential Client (Apps mit sicherem Backend): eine client_id und ein client_secret, das einmalig angezeigt wird — sicher aufbewahren.

Außerdem hinterlegst du eine oder mehrere Redirect-URIs und wählst die benötigten Scopes.

Authentifizierung (OAuth 2.0 Authorization Code)

Zwei Endpunkte: /oauth/authorize (Nutzer:in genehmigt deine App) und /oauth/token (du tauschst den Code gegen Tokens). Access-Tokens gelten 1 Stunde, Refresh-Tokens 1 Jahr (bei Nutzung rotiert). Tokens bleiben gültig, bis sie widerrufen werden.

1 · Public Clients (Mobil/SPA) — PKCE

Erzeuge zuerst einen PKCE-Verifier + Challenge:

# code_verifier: 43–128 zufällige Zeichen; code_challenge = base64url(sha256(verifier))
CODE_VERIFIER=$(openssl rand -base64 60 | tr -d '\n=+/' | cut -c1-64)
CODE_CHALLENGE=$(printf '%s' "$CODE_VERIFIER" \
  | openssl dgst -binary -sha256 | openssl base64 | tr '+/' '-_' | tr -d '=')

Schicke die Nutzer:in zur Authorize-URL (im Browser / In-App-Browser öffnen):

https://openbookcase.de/oauth/authorize
  ?response_type=code
  &client_id=DEINE_CLIENT_ID
  &redirect_uri=https://deineapp.example/callback
  &scope=bookcases.write%20images.write
  &state=ZUFALLSWERT
  &code_challenge=$CODE_CHALLENGE
  &code_challenge_method=S256

Nach der Zustimmung erfolgt die Weiterleitung zu https://deineapp.example/callback?code=AUTH_CODE&state=ZUFALLSWERT.

Tausche den Code gegen Tokens (Public Clients senden den Verifier, kein Secret):

curl -X POST https://openbookcase.de/oauth/token \
  -d grant_type=authorization_code \
  -d client_id=DEINE_CLIENT_ID \
  -d redirect_uri=https://deineapp.example/callback \
  -d code_verifier=$CODE_VERIFIER \
  -d code=AUTH_CODE

Antwort:

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJ0eXAiOiJKV1Qi...",
  "refresh_token": "def502..."
}

2 · Confidential Clients (mit Backend)

Gleicher Ablauf, aber Authentifizierung per Secret statt PKCE-Verifier:

curl -X POST https://openbookcase.de/oauth/token \
  -d grant_type=authorization_code \
  -d client_id=DEINE_CLIENT_ID \
  -d client_secret=DEIN_CLIENT_SECRET \
  -d redirect_uri=https://deineapp.example/callback \
  -d code=AUTH_CODE

3 · Token erneuern

curl -X POST https://openbookcase.de/oauth/token \
  -d grant_type=refresh_token \
  -d client_id=DEINE_CLIENT_ID \
  -d refresh_token=DEIN_REFRESH_TOKEN
  # Confidential Clients hängen zusätzlich an: -d client_secret=DEIN_CLIENT_SECRET

Scopes

Fordere nur an, was du brauchst (im scope-Parameter durch Leerzeichen getrennt). Lesen braucht keinen Scope.

ScopeErlaubt
bookcases.writeEinträge anlegen & bearbeiten, Position verschieben
bookcases.deleteEintrag löschen (Grund erforderlich; ein Snapshot wird archiviert)
images.writeFotos zu einem Eintrag hochladen
wishlist.writeWunschlisten-Einträge hinzufügen
watchlist.writeEintrag für die Nutzer:in beobachten / nicht mehr beobachten
ratings.writeEinen Eintrag für die Nutzer:in bewerten (1–5) und ihre Bewertung entfernen
home.writeHeimat-Kartenposition der Nutzer:in setzen

Endpunkt-Referenz

MethodePfadAuthZweck
GET/api/v1/bookcasesfreiListe nach Bounding-Box (latMin,latMax,lonMin,lonMax, limit≤1000, offset)
GET/api/v1/bookcases/{id}freiEinzelner Eintrag mit Details
GET/api/v1/bookcases/{id}/imagesfreiFotos eines Eintrags auflisten
GET/api/v1/bookcases/{id}/wishlistfreiWunschliste eines Eintrags auflisten
GET/api/v1/bookcases/{id}/caretakersfreiBetreuer:innen eines Eintrags auflisten
GET/api/v1/bookcases/{id}/opening-timesfreiÖffnungszeiten eines Eintrags auflisten
GET/api/v1/bookcases/{id}/ratingfreiBewertungsübersicht (Anzahl + Durchschnitt)
POST/api/v1/bookcasesbookcases.writeEintrag anlegen
PATCH/api/v1/bookcases/{id}bookcases.writeFelder aktualisieren (partiell)
POST/api/v1/bookcases/{id}/positionbookcases.writeVerschieben (latitude/longitude)
DELETE/api/v1/bookcases/{id}bookcases.deleteLöschen (JSON reason erforderlich)
POST/api/v1/bookcases/{id}/imagesimages.writeFoto hochladen (multipart)
POST/api/v1/bookcases/{id}/wishlistwishlist.writeWunschlisten-Eintrag hinzufügen
POST/api/v1/bookcases/{id}/watchwatchlist.writeEintrag beobachten
DELETE/api/v1/bookcases/{id}/watchwatchlist.writeBeobachtung beenden
POST/api/v1/profile/homehome.writeHeimatposition der Nutzer:in setzen
POST/api/v1/bookcases/{id}/caretakersbookcases.writeBetreuer:in zu einem Eintrag hinzufügen
PATCH/api/v1/bookcases/{id}/caretakers/{caretakerId}bookcases.writeBetreuer:in aktualisieren (partiell)
DELETE/api/v1/bookcases/{id}/caretakers/{caretakerId}bookcases.writeBetreuer:in entfernen
POST/api/v1/bookcases/{id}/opening-timesbookcases.writeÖffnungszeit hinzufügen
PATCH/api/v1/bookcases/{id}/opening-times/{openingTimeId}bookcases.writeÖffnungszeit aktualisieren (partiell)
DELETE/api/v1/bookcases/{id}/opening-times/{openingTimeId}bookcases.writeÖffnungszeit entfernen
PUT/api/v1/bookcases/{id}/ratingratings.writeBewertung der Nutzer:in hinzufügen oder aktualisieren (1–5)
DELETE/api/v1/bookcases/{id}/ratingratings.writeBewertung der Nutzer:in entfernen

Das Bearer-Token gehört in den Authorization-Header. Ein Schreibzugriff ohne Token liefert 401, mit falschem Scope 403.

API verwenden

Kartenausschnitt lesen (frei)

curl "https://openbookcase.de/api/v1/bookcases?latMin=52.4&latMax=52.6&lonMin=13.3&lonMax=13.5&limit=200"

Einen Eintrag lesen (frei)

curl https://openbookcase.de/api/v1/bookcases/01JZ8M4P3Q0000000000000000

Eintrag anlegen

curl -X POST https://openbookcase.de/api/v1/bookcases \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "title": "Gemeinschaftsregal im Park",
        "entryType": "bookcase",
        "latitude": 52.5200,
        "longitude": 13.4050
      }'
# → 201 Created, liefert den neuen Eintrag (inkl. id). Titel dürfen keine URLs enthalten.

Felder aktualisieren (partiell)

curl -X PATCH https://openbookcase.de/api/v1/bookcases/01JZ8M4P3Q... \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"comment": "Wöchentlich aufgefüllt", "isMobile": false, "accessibilityLevel": 3}'

Eintrag verschieben

curl -X POST https://openbookcase.de/api/v1/bookcases/01JZ8M4P3Q.../position \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"latitude": 52.5198, "longitude": 13.4042}'

Foto hochladen (multipart)

curl -X POST https://openbookcase.de/api/v1/bookcases/01JZ8M4P3Q.../images \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -F imageFile=@regal.jpg \
  -F author="Jane Doe" \
  -F altText="Vorderansicht des Regals"
# imageFile + author sind Pflicht; altText ist optional. Max. 5 Fotos pro Eintrag.

Eintrag löschen (Grund erforderlich)

curl -X DELETE https://openbookcase.de/api/v1/bookcases/01JZ8M4P3Q... \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Bücherschrank wurde vom Eigentümer entfernt"}'

Beobachten · Wunschliste · Heimat

# Eintrag beobachten (bei Änderungen benachrichtigt werden)
curl -X POST https://openbookcase.de/api/v1/bookcases/01JZ.../watch \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Wunschlisten-Eintrag hinzufügen (title Pflicht; author/isbn/misc optional)
curl -X POST https://openbookcase.de/api/v1/bookcases/01JZ.../wishlist \
  -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \
  -d '{"title": "Die linke Hand der Dunkelheit", "author": "Ursula K. Le Guin"}'

# Heimat-Kartenposition der Nutzer:in setzen
curl -X POST https://openbookcase.de/api/v1/profile/home \
  -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \
  -d '{"latitude": 52.52, "longitude": 13.405, "zoom": 14}'

Betreuer:innen, Öffnungszeiten & Bewertungen

Betreuer:innen und Öffnungszeiten gehören zum Eintrag, sie nutzen daher bookcases.write. Eine Bewertung gehört zur Nutzer:in, sie nutzt daher ratings.write.

# Betreuer:in hinzufügen (Name und/oder Kontakt erforderlich; Adresse optional)
curl -X POST https://openbookcase.de/api/v1/bookcases/01JZ.../caretakers \
  -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \
  -d '{"name": "Local library", "contact": "hello@example.org",
       "address": {"street": "Main St", "houseNumber": "5", "city": "Berlin"}}'
# → 201 Created, liefert die Betreuer:in (inkl. id). PATCH .../caretakers/{id} bearbeitet sie,
#   DELETE .../caretakers/{id} löst sie (und entfernt sie, wenn kein Eintrag sie mehr nutzt).

# Öffnungszeit hinzufügen (Freitext text ODER das 24/7-Flag — eines ist erforderlich)
curl -X POST https://openbookcase.de/api/v1/bookcases/01JZ.../opening-times \
  -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \
  -d '{"openTime": "Mo-Fr 08:00-20:00"}'        # oder: {"twentyFourSeven": true}
# PATCH/DELETE .../opening-times/{id} bearbeiten oder entfernen sie.

# Eintrag für die Nutzer:in bewerten (1–5; legt ihre einzige Bewertung an oder aktualisiert sie)
curl -X PUT https://openbookcase.de/api/v1/bookcases/01JZ.../rating \
  -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \
  -d '{"value": 5}'
# → liefert {userValue, count, average, rounded}. DELETE .../rating entfernt ihre Bewertung.

Limits & Fehler

  • Lesen: 600 Anfragen / Minute, pro IP.
  • Schreiben: 60 Anfragen / 10 Minuten, pro Access-Token.

Bei Überschreitung kommt 429 Too Many Requests mit Retry-After-Header (Sekunden) und X-RateLimit-Limit. Andere Fehler sind JSON mit einer error-Meldung: 400 ungültige Anfrage, 401 fehlendes/ungültiges Token, 403 falscher Scope, 404 nicht gefunden, 422 Validierung fehlgeschlagen (mit violations-Liste).

Datenlizenz & Namensnennung

  • Alle Daten auf dieser Seite stehen unter der Open Database License (ODbL).
  • Wenn du diese Daten in einem anderen Projekt verwendest, muss auch dieses Projekt unter der ODbL veröffentlicht werden und einen Link zum Lizenztext enthalten.
  • OpenBookCase enthält aus OpenStreetMap importierte Daten. Jedes Projekt, das diese Daten nutzt, muss daher OpenStreetMap und seine Mitwirkenden nennen — ein Link zur OpenStreetMap-Urheberrechtsseite ist verpflichtend.
  • Diese Daten dürfen nicht zurück nach OpenStreetMap importiert werden. Einträge werden mitunter aus dem Gedächtnis statt an exakten, geprüften Koordinaten erfasst, wodurch sie für OpenStreetMap unbrauchbar sind.