API-Dokumentation
Kostenlose, öffentliche API für Genre- und Band-Daten aus MetalDB. Read-only, JSON, keine versteckten Kosten. Einen Key bekommst du in wenigen Sekunden im Entwickler-Bereich.
Quickstart
Jeder Request braucht einen API-Key im Header X-API-Key. Key erstellen dauert eine Minute im Entwickler-Bereich, dann direkt loslegen:
curl -H "X-API-Key: mdb_dein_key_hier" \
https://metaldb.org/api/v1/genresAntwort (gekürzt):
{
"data": [
{ "slug": "black-metal", "name": "Black Metal", "tag": "black metal" },
{ "slug": "death-metal", "name": "Death Metal", "tag": "death metal" }
// ...
],
"meta": { "count": 314 }
}Authentifizierung
Jeder Endpoint (außer der Root-Route) verlangt den Header X-API-Key mit einem gültigen, aktiven Key. Fehlt er oder ist er ungültig/widerrufen, kommt ein 401 mit Fehlercode missing_api_key bzw. invalid_api_key.
Keys werden bei uns nur als Hash gespeichert und sind nach der Erstellung nur einmal im Klartext sichtbar. Verliert sich ein Key, einfach im Entwickler-Bereich widerrufen und einen neuen erstellen.
Antwortformat
Alle erfolgreichen Antworten haben die Form {"data": ...}, teils ergänzt um "meta" mit zusätzlichen Infos (z.B. Anzahl der Ergebnisse). Fehler sehen immer so aus:
{
"error": {
"code": "artist_not_found",
"message": "Keine Band mit dieser MusicBrainz-ID gefunden."
}
}Es werden nie Stacktraces, Datenbankfehler oder interne Pfade zurückgegeben – nur dieser feste Fehler-Umschlag.
Endpoints
Liste aller 300+ Metal-Subgenres, die MetalDB kennt.
Antwort
{ "data": [{ "slug", "name", "tag" }], "meta": { "count" } }Details zu einem einzelnen Genre inkl. verwandter Genres (aus dem Genre-Graphen berechnet). slug z.B. black-metal.
Antwort
{ "data": { "slug", "name", "band_count", "related_genres": [{ "slug", "name" }] } }Der komplette Genre-Beziehungsgraph als Knoten/Kanten-Struktur. Niedrigeres Limit, da teuerster Endpoint – am besten lokal cachen statt oft neu abzufragen.
Antwort
{ "data": { "nodes": [{ "id", "count" }], "edges": [{ "source", "target", "weight" }] } }Basis-Metadaten einer Band anhand ihrer MusicBrainz-ID. Nur öffentliche Musik-Metadaten – keine Kommentare, Ratings oder sonstige Nutzerdaten.
Antwort
{ "data": { "musicbrainz_id", "name", "country", "genres": [{ "slug", "name" }] } }Aggregierte Statistiken über die gesamte Datenbank: häufigste Genres, überraschende Genre-Kombinationen, produktivste Bands, Alben pro Jahrzehnt.
Antwort
{ "data": {
"total_bands", "total_genres_tracked",
"top_genres": [{ "genre", "count" }],
"top_genre_pairs": [{ "genre_a", "genre_b", "weight" }],
"surprising_genre_pairs": [{ "genre_a", "genre_b", "weight" }],
"most_prolific_bands": [{ "artist_id", "name", "count" }],
"albums_by_decade": [{ "decade", "count" }]
} }Fehlercodes
| Status | Code | Bedeutung |
|---|---|---|
| 401 | missing_api_key | Header X-API-Key fehlt komplett. |
| 401 | invalid_api_key | Key existiert nicht oder wurde widerrufen. |
| 404 | genre_not_found | Unbekannter Genre-Slug. |
| 404 | artist_not_found | Keine Band mit dieser MusicBrainz-ID. |
| 404 | not_found | Endpoint existiert nicht. |
| 429 | rate_limited | Rate-Limit für diesen Key/diese IP erreicht. |
| 500 | internal_error | Serverfehler bei uns – wurde geloggt, kein Verschulden deinerseits. |
Rate-Limits
Jeder Endpoint hat sein eigenes Limit pro API-Key (siehe Tabelle oben bei den Endpoints). Zusätzlich gilt ein globales IP-Limit als zweite Sicherheitsschicht. Wird ein Limit überschritten, kommt 429 – einfach kurz warten und erneut versuchen, kein Grund zur Sorge bei normaler Nutzung.
Falls dein Projekt regelmäßig mehr braucht als die Standard-Limits hergeben, meld dich einfach – wir schauen uns das gerne individuell an.
Nutzungsbedingungen
- Kostenlos für alle Zwecke – privat, akademisch, kommerziell. Kein Zahlungsmodell, keine versteckten Stufen.
- Attribution erwünscht – wenn du MetalDB-Daten in einem öffentlichen Projekt nutzt, freuen wir uns über einen Hinweis/Link zu metaldb.org. Verpflichtend ist es nicht, aber es hilft uns, dass die Daten aktuell gehalten und die API weiter ausgebaut wird.
- Kein Massen-Weiterverkauf der Rohdaten – die API ist zum Bauen eigener Anwendungen gedacht, nicht dazu, unseren gesamten Datenbestand zu kopieren und als eigenes Produkt weiterzuverkaufen. Bei Unsicherheit: einfach kurz nachfragen.
- Keys sind persönlich – nicht öffentlich teilen (z.B. in Client-seitigem JS oder GitHub-Repos committen). Ein kompromittierter Key lässt sich jederzeit im Entwickler-Bereich widerrufen.
- Keine Garantie auf Verfügbarkeit – MetalDB ist ein Community-Projekt, kein SLA-gestützter Enterprise-Dienst. Wir bemühen uns um Stabilität, können sie aber nicht vertraglich zusichern.
- Missbrauch führt zum Widerruf – exzessive Nutzung außerhalb der Rate-Limits, Versuche die Limits zu umgehen, oder Nutzung für Spam/Scraping-Zwecke führen zur Sperrung des Keys ohne Vorwarnung.