Zum Inhalt springen

API

Der GLOBE-Katalog, als API

Alles, was die Seite über 11.000+ Festivals und 40.000+ Künstler weiß, als schlichtes JSON: Listen, Seiten, Line-ups, tippfehlertolerante Suche. Nur lesend, ein Schlüssel, klare Quotas.

https://theglobalfestivalmap.com/api/catalog/v1Schlüssel anfragen

Erste Schritte

Jede Anfrage geht an die Basisadresse oben und trägt Ihren Schlüssel im Header X-Api-Key. Fragen Sie per E-Mail nach einem Schlüssel: Sagen Sie, wer Sie sind und was Sie bauen wollen.

Antworten haben immer denselben Umschlag: generated_at, catalog_version, count, next_cursor und data. Listen paginieren über einen opaken Cursor: Geben Sie next_cursor als cursor zurück, mit demselben sort, bis er als null zurückkommt.

curl "https://theglobalfestivalmap.com/api/catalog/v1/search?q=hellfest" \
  -H "X-Api-Key: $GLOBE_API_KEY"

Quotas und Header

Zwei Grenzen pro Schlüssel, pro Minute und pro Tag, auf jeder Antwort angegeben: X-RateLimit-Limit-Minute, X-RateLimit-Remaining-Minute, X-Quota-Limit-Day, X-Quota-Remaining-Day. Darüber antwortet die API mit 429, rate_limited oder daily_quota_exceeded und einem Retry-After.

GET-Antworten tragen ein ETag: Senden Sie If-None-Match, um ein 304 zu erhalten und Ihr Quota zu schonen. Aufrufe ohne Schlüssel werden während einer Schonfrist mit einem Header X-Catalog-Warning geduldet, dann mit 401 api_key_required abgelehnt.

Scopes und Quellen

catalog umfasst Festivals, Künstler und Suche. past_events umfasst vergangene Konzerte aus dem setlist.fm-Archiv: Namensnennung ist Pflicht und kommerzielle Nutzung ohne deren schriftliche Zustimmung nicht erlaubt, deshalb gehört dieser Scope zu keinem bezahlten Tarif. Ein Schlüssel ohne den Scope erhält 403 scope_required.

Festivaldaten stammen aus öffentlichen Registern, Wikidata, OpenStreetMap, offiziellen Websites und von Veranstaltern; Künstler aus MusicBrainz, Spotify, Deezer und Ticketmaster.

Fehler

Jeder Fehler hat einen stabilen error.code zum Prüfen, eine lesbare error.message und, wo sinnvoll, error.details mit dem, was abgelehnt wurde. Codes, die Ihnen begegnen: die Familie bad_request (400), api_key_required (401), scope_required (403), not_found (404), rate_limited und daily_quota_exceeded (429).

Ausprobieren

Ausprobieren

Ihr Schlüssel bleibt in diesem Browser-Tab (Session Storage), und der Aufruf geht direkt an die API, nicht über die Seite.

Referenz

Erzeugt aus dem Live-OpenAPI-Dokument. Laden Sie es herunter, um die API in Postman, Insomnia, n8n oder einen Client-Generator einzubinden.

OpenAPI-Dokument (JSON) · GLOBE catalog API 1.0.0

Account

Your key, quotas and usage.

GET/versionAPI and catalog version

kein Schlüssel nötig

Catalog timestamp, available endpoints, data sources and required attributions.

Antworten

  • 200 OK

Beispiel

curl "https://theglobalfestivalmap.com/api/catalog/v1/version"
GET/meYour key, quotas and usage

With an API key: plan, scopes, quotas and usage for today and the current month, per route.

Antworten

  • 200 OK
  • 401 Missing or refused key

Beispiel

curl "https://theglobalfestivalmap.com/api/catalog/v1/me" \
  -H "X-Api-Key: $GLOBE_API_KEY"
GET/openapi.jsonThis specification

kein Schlüssel nötig

Antworten

  • 200 OpenAPI 3.1 document

Beispiel

curl "https://theglobalfestivalmap.com/api/catalog/v1/openapi.json"

Festivals

Festival lists, pages and batch lookups.

GET/festivalsList festivals

Festivals with their next edition, filtered by country, dates, genres, text and distance. Defaults to France: pass country=all for the world. Sorted by next date unless sort says otherwise.

Parameter

countryQuerystring = FRISO 3166-1 alpha-2 country code, or all. Defaults to FR.
fromQuerystring dateISO date (YYYY-MM-DD), inclusive.
toQuerystring dateISO date (YYYY-MM-DD), inclusive.
genresQuerystringComma-separated genre slugs (up to 10), e.g. rock,metal.
qQuerystringTypo-tolerant text filter on the name.
nearQuerystringlat,lng. Enables distance_km in items and sort=distance.
radius_kmQuerynumber (..2000) = 100Radius around near.
sortQuerydate | distance | popularity = date
limitQueryinteger (1..100) = 20Page size (1 to 100).
cursorQuerystringThe next_cursor of the previous page. Must be used with the same sort.

Antworten

  • 200 OK
  • 400 Invalid parameter

Beispiel

curl "https://theglobalfestivalmap.com/api/catalog/v1/festivals" \
  -H "X-Api-Key: $GLOBE_API_KEY"
GET/festivals/{slug}Festival page

Everything the site shows on a festival page: description (fr/en), place, links, editions, next edition, lineup with artist references, amenities.

Parameter

slugerforderlichPfadstring

Antworten

  • 200 OK
  • 404 Unknown resource

Beispiel

curl "https://theglobalfestivalmap.com/api/catalog/v1/festivals/hellfest-open-air" \
  -H "X-Api-Key: $GLOBE_API_KEY"
POST/festivals/batchResolve festival slugs in bulk

Up to 200 slugs per call. Unknown slugs come back with status: "gone" instead of failing the whole batch.

Body

{
  "ids": [
    "hellfest-open-air",
    "rock-en-seine"
  ]
}

Antworten

  • 200 OK
  • 400 Invalid parameter

Beispiel

curl -X POST "https://theglobalfestivalmap.com/api/catalog/v1/festivals/batch" \
  -H "X-Api-Key: $GLOBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids":["hellfest-open-air","rock-en-seine"]}'

Artists

Artist pages and batch lookups.

GET/artists/{idOrSlug}Artist page

Identity, bio, links, genres, popularity, upcoming festival appearances and past ones.

Parameter

idOrSlugerforderlichPfadstringArtist slug, or art-<slug> id.

Antworten

  • 200 OK
  • 404 Unknown resource

Beispiel

curl "https://theglobalfestivalmap.com/api/catalog/v1/artists/gojira" \
  -H "X-Api-Key: $GLOBE_API_KEY"
POST/artists/batchResolve artist ids in bulk

Up to 200 ids per call. Unknown ids come back with status: "gone".

Body

{
  "ids": [
    "hellfest-open-air",
    "rock-en-seine"
  ]
}

Antworten

  • 200 OK
  • 400 Invalid parameter

Beispiel

curl -X POST "https://theglobalfestivalmap.com/api/catalog/v1/artists/batch" \
  -H "X-Api-Key: $GLOBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids":["hellfest-open-air","rock-en-seine"]}'

Search

Typo-tolerant search across festivals and artists.

Past events

Past concerts from the setlist.fm archive. Requires the past_events scope. Past concerts come from the setlist.fm archive (attribution required, non-commercial use).

GET/artists/{idOrSlug}/pastPast concerts of an artist

Newest first, cursor-paginated. An artist unknown to the archive gets an empty page with past_count: 0, never a 404. Requires the past_events scope. Past concerts come from the setlist.fm archive (attribution required, non-commercial use).

Parameter

idOrSlugerforderlichPfadstring
fromQuerystring dateISO date (YYYY-MM-DD), inclusive.
toQuerystring dateISO date (YYYY-MM-DD), inclusive.
countryQuerystringISO 3166-1 alpha-2 country code, or all. No filter by default.
limitQueryinteger (1..100) = 20Page size (1 to 100).
cursorQuerystringThe next_cursor of the previous page. Must be used with the same sort.

Antworten

  • 200 OK
  • 403 Scope missing on this key
  • 404 Unknown resource

Beispiel

curl "https://theglobalfestivalmap.com/api/catalog/v1/artists/value/past" \
  -H "X-Api-Key: $GLOBE_API_KEY"
POST/events/batchResolve concert ids in bulk

sfm-<id> ids are resolved against the archive (ok or gone); other schemes come back unsupported. Requires the past_events scope. Past concerts come from the setlist.fm archive (attribution required, non-commercial use).

Body

{
  "ids": [
    "hellfest-open-air",
    "rock-en-seine"
  ]
}

Antworten

  • 200 OK
  • 400 Invalid parameter
  • 403 Scope missing on this key

Beispiel

curl -X POST "https://theglobalfestivalmap.com/api/catalog/v1/events/batch" \
  -H "X-Api-Key: $GLOBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids":["hellfest-open-air","rock-en-seine"]}'
GET/venues/{venueId}/pastPast concerts of an archive venue

Only archive venues (sfmvenue-<id>). Requires the past_events scope. Past concerts come from the setlist.fm archive (attribution required, non-commercial use).

Parameter

venueIderforderlichPfadstring
fromQuerystring dateISO date (YYYY-MM-DD), inclusive.
toQuerystring dateISO date (YYYY-MM-DD), inclusive.
limitQueryinteger (1..100) = 20Page size (1 to 100).
cursorQuerystringThe next_cursor of the previous page. Must be used with the same sort.

Antworten

  • 200 OK
  • 400 Invalid parameter
  • 403 Scope missing on this key
  • 404 Unknown resource

Beispiel

curl "https://theglobalfestivalmap.com/api/catalog/v1/venues/sfmvenue-3bd6b6b4/past" \
  -H "X-Api-Key: $GLOBE_API_KEY"