# 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

- HTML-Dokumentation: https://www.rausheute.de/api-docs
- Markdown-Download: https://www.rausheute.de/api-docs.md
- API-Basis-URL: https://www.rausheute.de/api/v1/
- Karten-SDK: https://www.rausheute.de/maps/v1/rausheute-map.js
- API-Version: 1.0
- Nutzungsbedingungen: https://www.rausheute.de/api-demo/nutzungsbedingungen.php
- Datenschutz: https://www.rausheute.de/datenschutz/

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

```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:

- `data-query`: Suchbegriff für Raus-Heute-POIs
- `data-lat` und `data-lng`: Mittelpunkt in Dezimalgrad
- `data-radius-km`: Suchradius in Kilometern
- `data-limit`: maximale Anzahl der geladenen POIs
- `data-category`: Kategorie-Filter
- `data-controls`: kommagetrennte Liste, zum Beispiel `zoom,scale,fullscreen`

## Einbindung per JavaScript

```html
<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

- Anonyme Zugriffe: 180 Requests pro Minute und IP, sofern der Endpunkt kein engeres Limit setzt.
- API-Key-Zugriffe: standardmäßig 600 Requests pro Minute; individuelle Werte sind möglich.
- Header: `X-RausHeute-Key: <key>`
- Alternativ für einfache Tests: Query-Parameter `key` oder `api_key`
- Rate-Limit-Header: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`

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:

```bash
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:

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

Wichtige Felder:

- `styleUrl`: URL des MapLibre-Stils
- `defaultCenter`: Mittelpunkt als `[lng, lat]`
- `defaultZoom`, `minZoom`, `maxZoom`
- `bounds`: DACH-Grenzen
- `libraries`: MapLibre- und PMTiles-Bibliotheken
- `capabilities`: aktivierte API-Funktionen
- `usage`: Limits, Attribution und Rechtliches

### 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:

```bash
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:

- `q`: Suchbegriff
- `lat` und `lng`: Mittelpunkt in Dezimalgrad
- `radius_km`: Umkreis in Kilometern, Standard `80`
- `bbox`: Bounding Box als `west,south,east,north`
- `category`: Kategorie
- `kids=1`: nur kinderfreundliche Ziele
- `seating=1`: nur Ziele mit Sitz-/Pausenqualität
- `free=1`: nur kostenlose Ziele
- `min_mobility`: Mindestwert für Mobilität
- `limit`: maximale Trefferzahl, Standard `80`
- `format=geojson`: Ausgabe als GeoJSON FeatureCollection

JSON-Antwort:

```json
{
  "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:

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

### GET /api/v1/categories

Liefert die verfügbaren POI-Kategorien mit Trefferanzahl.

Beispiel:

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

## Fehlerformat

Fehler werden als JSON mit `ok: false` geliefert.

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

Typische HTTP-Statuscodes:

- `400`: ungültige oder fehlende Parameter
- `401`: unbekannter API-Key
- `403`: API-Key für Herkunft nicht freigeschaltet
- `404`: Ressource nicht gefunden
- `405`: Methode nicht erlaubt
- `429`: Rate-Limit erreicht
- `500`: temporärer Serverfehler

## 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