# LetsCast.fm API

Mit der LetsCast.fm API rufst Du die Statistik-Daten Deiner Podcasts automatisiert ab, zum Beispiel für eigene Auswertungen, Tabellen oder Dashboards. Die API ist lesend und liefert CSV- oder JSON-Daten.

Deinen persönlichen API-Token und die IDs Deiner Podcasts findest Du nach dem Login unter Einstellungen → API. (https://letscast.fm/user/api)

In den Beispielen stehen `API_TOKEN` und `PODCAST_ID` als Platzhalter für Deinen Token und die ID eines Deiner Podcasts.

## Authentifizierung

Jede Anfrage muss Deinen API-Token im HTTP-Header `x-api-key` enthalten.

```bash
curl -H "x-api-key: API_TOKEN" \
  "https://letscast.fm/api/v1/analytics/downloads"
```

Fehlt der Token oder ist er ungültig, antwortet die API mit HTTP-Status 401 und einer JSON-Fehlermeldung. Wiederhole die Anfrage in dem Fall nicht, sondern prüfe den Token.

Alle Endpunkte liefern die gleichen Zahlen wie die Statistik im Backend. Downloads von Bots und bekannten Rechenzentren werden herausgefiltert.

## Limits

Damit die API für alle zuverlässig bleibt, gelten folgende Grenzen:

- Höchstens 60 Anfragen pro Minute je Token, über alle Endpunkte hinweg.
- Höchstens 30 CSV-Abrufe pro Stunde je Token (Endpunkte downloads, listeners und export).
- Der Zeitraum eines Download-Exports darf höchstens 6 Monate umfassen.

Bei Überschreitung antwortet die API mit HTTP-Status 429 und einer JSON-Fehlermeldung. Der Header Retry-After nennt die Sekunden bis zum nächsten erlaubten Versuch. Warte diese Zeit ab, statt die Anfrage sofort zu wiederholen.

## Endpunkte

### Downloads aller Podcasts pro Tag

`GET /api/v1/analytics/downloads`

Liefert die Downloads aller Deiner Podcasts als CSV-Datei, zusammengefasst pro Tag und Episode.

| Parameter | |
| --- | --- |
| `start_date` | Optional. Startdatum im Format JJJJ-MM-TT. Ohne Angabe werden alle Daten geliefert. |

Beispiel-Anfrage:

```bash
curl -H "x-api-key: API_TOKEN" -o downloads-podcasts.csv \
  "https://letscast.fm/api/v1/analytics/downloads?start_date=2026-09-14"
```

Beispiel-Ausgabe (CSV, tabulatorgetrennt):

```
delivered_at	downloads	podcast	episode_number	episode_title
2025-10-01	42	Mein Podcast	12	Episode 12
```

### Hörer:innen aller Podcasts pro Monat

`GET /api/v1/analytics/listeners`

Liefert die Anzahl der eindeutigen Hörer:innen (eindeutige IP-Adressen) aller Deiner Podcasts als CSV-Datei, zusammengefasst pro Monat und Podcast.

| Parameter | |
| --- | --- |
| `start_date` | Optional. Startdatum im Format JJJJ-MM-TT. Ohne Angabe werden alle Daten geliefert. |

Beispiel-Anfrage:

```bash
curl -H "x-api-key: API_TOKEN" -o listeners-podcasts.csv \
  "https://letscast.fm/api/v1/analytics/listeners?start_date=2026-09-14"
```

Beispiel-Ausgabe (CSV, tabulatorgetrennt):

```
date	listeners	podcast
2025-09	1234	Mein Podcast
```

### Download-Export eines Podcasts

`GET /api/v1/analytics/export`

Liefert alle einzelnen Downloads eines Podcasts im gewählten Zeitraum als CSV-Datei, mit jeweils einer Zeile pro Download, inklusive Episode, App und Land.

| Parameter | |
| --- | --- |
| `id` | Pflichtfeld. Die ID des Podcasts. |
| `start_date` | Optional. Startdatum im Format JJJJ-MM-TT. Standard: vor 30 Tagen. |
| `end_date` | Optional. Enddatum im Format JJJJ-MM-TT. Standard: heute. |

Beispiel-Anfrage:

```bash
curl -H "x-api-key: API_TOKEN" -o downloads.csv \
  "https://letscast.fm/api/v1/analytics/export?id=PODCAST_ID&start_date=2026-09-14&end_date=2026-10-14"
```

Beispiel-Ausgabe (CSV, kommagetrennt):

```
delivered_at,title,publishing_date,request_user_agent,is_bot,app,country_iso_code,country_name,count,delivered_at_YYYYMM
2025-10-01,Episode 12,2025-09-28 06:00:00,AppleCoreMedia/1.0.0 ...,0,Apple Podcasts,DE,Deutschland,1,2025-10
```

Der Zeitraum darf höchstens 6 Monate umfassen, sonst antwortet die API mit HTTP-Status 400. Bei vielen Downloads kann die Datei trotzdem groß werden, begrenze den Zeitraum über start_date und end_date.

### Downloads für LaMetric

`GET /api/v1/analytics/lametric`

Liefert die Downloads der letzten 24 Stunden, 7 Tage und 30 Tage eines Podcasts als JSON im Frame-Format von LaMetric Time.

| Parameter | |
| --- | --- |
| `id` | Pflichtfeld. Die ID des Podcasts. |

Beispiel-Anfrage:

```bash
curl -H "x-api-key: API_TOKEN" \
  "https://letscast.fm/api/v1/analytics/lametric?id=PODCAST_ID"
```

Beispiel-Antwort:

```
{
  "frames": [
    { "index": 0, "text": "1d: 123", "icon": "i22514" },
    { "index": 1, "text": "7d: 1.234", "icon": "i22514" },
    { "index": 2, "text": "30d: 5.678", "icon": "i22514" }
  ]
}
```

Lege in der LaMetric-App eine "Indicator"-App mit dem Modus "Poll" an, trage die URL ein und hinterlege Deinen Token als Header x-api-key.

## Für Entwickler:innen und KI-Tools

- OpenAPI-Spezifikation (YAML): https://letscast.fm/api/v1/openapi.yaml
- llms.txt: https://letscast.fm/llms.txt
- HTML: https://letscast.fm/api/docs