Raus Heute Ausflüge finden Jetzt suchen

Entwicklerdokumentation

Raus Heute Karten-API

Eine kompakte Referenz für externe Webseiten: SDK-Einbindung, Kartenkonfiguration, POI-Suche, Authentifizierung, Limits und Attribution.

Markdown herunterladen Demo ansehen API-Index

Raus Heute Karten-API

Stand: 25. Mai 2026

Diese Dokumentation beschreibt die öffentliche Raus-Heute-Karten-API für Entwickler, die Raus-Heute-Karten, Ausflugsziele oder eigene Marker in externe Webseiten einbinden möchten.

Schnellstart

Ein API-Key ist für normale anonyme Einbettungen nicht erforderlich. Für produktive Integrationen mit höheren Limits kann ein Key eingerichtet werden. Der Key wird als Header X-RausHeute-Key gesendet.

Einbindung per HTML

<div
  data-rausheute-map
  data-query="Wasser"
  data-lat="49.4521"
  data-lng="11.0767"
  data-radius-km="80"
  data-limit="20"
  style="height: 520px">
</div>
<script src="https://www.rausheute.de/maps/v1/rausheute-map.js" defer></script>

Das SDK sucht beim Laden automatisch nach Elementen mit data-rausheute-map und initialisiert die Karte. Sinnvolle Attribute sind:

Einbindung per JavaScript

<div id="karte" style="height: 520px"></div>
<script src="https://www.rausheute.de/maps/v1/rausheute-map.js" defer></script>
<script>
  window.addEventListener('rausheute-map-sdk-ready', function () {
    RausHeuteMap.create('#karte', {
      pois: {
        q: 'Aussicht',
        lat: 49.4521,
        lng: 11.0767,
        radius_km: 80,
        limit: 20
      },
      center: [11.0767, 49.4521],
      zoom: 10,
      controls: ['zoom', 'scale', 'fullscreen'],
      markers: [
        {
          id: 'eigener-ort',
          title: 'Eigener Ortspunkt',
          label: '1',
          lat: 49.4521,
          lng: 11.0767,
          color: '#2454a6'
        }
      ]
    });
  });
</script>

Authentifizierung und Limits

Die API liefert CORS-Header für Browser-Integrationen. Bei registrierten API-Keys können Origins freigeschaltet und serverseitig geprüft werden.

Endpunkte

GET /api/v1/

Liefert den API-Index mit Version, Basis-URL, SDK-URL, Endpunkten, Client-Status, Nutzungsbedingungen, Datenschutz und Dokumentationslinks.

Beispiel:

curl "https://www.rausheute.de/api/v1/"

GET /api/v1/map/config

Liefert die Kartenkonfiguration, Bibliotheks-URLs, Bounds, Fähigkeiten und Nutzungsinformationen. Dieser Endpunkt ist der empfohlene Einstieg für eigene Clients.

Beispiel:

curl "https://www.rausheute.de/api/v1/map/config"

Wichtige Felder:

GET /api/v1/map/style

Liefert den MapLibre-Stil mit absoluten URLs für externe Einbettungen. Browser-Clients sollten normalerweise styleUrl aus /api/v1/map/config verwenden, statt diese URL fest zu verdrahten.

GET /api/v1/pois

Sucht Raus-Heute-Ausflugsziele und liefert JSON oder GeoJSON.

Beispiel:

curl "https://www.rausheute.de/api/v1/pois?q=Wasser&lat=49.4521&lng=11.0767&radius_km=80&limit=6"
curl "https://www.rausheute.de/api/v1/pois?bbox=10.90,49.35,11.20,49.60&format=geojson"

Parameter:

JSON-Antwort:

{
  "ok": true,
  "apiVersion": "1.0",
  "count": 2,
  "items": [
    {
      "slug": "beispielziel",
      "name": "Beispielziel",
      "latitude": 49.4521,
      "longitude": 11.0767,
      "category": "Wasser"
    }
  ],
  "attribution": "Raus Heute, © OpenStreetMap contributors, Protomaps"
}

GET /api/v1/pois/{slug}

Liefert ein einzelnes Ausflugsziel per Slug.

Beispiel:

curl "https://www.rausheute.de/api/v1/pois/beispielziel"

GET /api/v1/categories

Liefert die verfügbaren POI-Kategorien mit Trefferanzahl.

Beispiel:

curl "https://www.rausheute.de/api/v1/categories"

Fehlerformat

Fehler werden als JSON mit ok: false geliefert.

{
  "ok": false,
  "error": "Das API-Limit für diese Minute ist erreicht.",
  "retryAfterSeconds": 24
}

Typische HTTP-Statuscodes:

Attribution und Nutzung

Die Kartendaten basieren auf OpenStreetMap und Protomaps. Die sichtbare Attribution darf nicht entfernt, verdeckt oder unlesbar gemacht werden. Nicht erlaubt sind Massendownloads, systematisches Spiegeln der PMTiles-Dateien, automatisiertes Vorladen großer Gebiete und die Umgehung von Limits.

Kontakt

Für API-Keys, höhere Limits oder technische Rückfragen: info@adrastea.com