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 anfragenErste 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 versionkein Schlüssel nötig
Catalog timestamp, available endpoints, data sources and required attributions.
Antworten
200OK
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
200OK401Missing or refused key
Beispiel
curl "https://theglobalfestivalmap.com/api/catalog/v1/me" \ -H "X-Api-Key: $GLOBE_API_KEY"
GET/openapi.jsonThis specificationkein Schlüssel nötig
Antworten
200OpenAPI 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
country | Query | string = FR | ISO 3166-1 alpha-2 country code, or all. Defaults to FR. |
from | Query | string date | ISO date (YYYY-MM-DD), inclusive. |
to | Query | string date | ISO date (YYYY-MM-DD), inclusive. |
genres | Query | string | Comma-separated genre slugs (up to 10), e.g. rock,metal. |
q | Query | string | Typo-tolerant text filter on the name. |
near | Query | string | lat,lng. Enables distance_km in items and sort=distance. |
radius_km | Query | number (..2000) = 100 | Radius around near. |
sort | Query | date | distance | popularity = date | |
limit | Query | integer (1..100) = 20 | Page size (1 to 100). |
cursor | Query | string | The next_cursor of the previous page. Must be used with the same sort. |
Antworten
200OK400Invalid 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
slugerforderlich | Pfad | string |
Antworten
200OK404Unknown 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
200OK400Invalid 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
idOrSlugerforderlich | Pfad | string | Artist slug, or art-<slug> id. |
Antworten
200OK404Unknown 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
200OK400Invalid 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.
GET/searchSearch festivals and artists
Tolerates typos and accents ("helfest" finds Hellfest). Results of both types are ranked together: exact > prefix > fuzzy, then popularity.
Parameter
qerforderlich | Query | string | |
types | Query | string = artist,festival | Comma-separated: artist, festival. |
scope | Query | published | site = published | site restricts to the live, geolocated festivals shown on theglobalfestivalmap.com. |
limit | Query | integer (1..50) = 8 | Page size (1 to 50). |
Antworten
200OK400Invalid parameter
Beispiel
curl "https://theglobalfestivalmap.com/api/catalog/v1/search?q=hellfest" \ -H "X-Api-Key: $GLOBE_API_KEY"
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
idOrSlugerforderlich | Pfad | string | |
from | Query | string date | ISO date (YYYY-MM-DD), inclusive. |
to | Query | string date | ISO date (YYYY-MM-DD), inclusive. |
country | Query | string | ISO 3166-1 alpha-2 country code, or all. No filter by default. |
limit | Query | integer (1..100) = 20 | Page size (1 to 100). |
cursor | Query | string | The next_cursor of the previous page. Must be used with the same sort. |
Antworten
200OK403Scope missing on this key404Unknown resource
Beispiel
curl "https://theglobalfestivalmap.com/api/catalog/v1/artists/value/past" \ -H "X-Api-Key: $GLOBE_API_KEY"
GET/past-events/searchFind a past concert
For "I was there" imports. artist is required; year, city, venue and country narrow the result. Requires the past_events scope. Past concerts come from the setlist.fm archive (attribution required, non-commercial use).
Parameter
artisterforderlich | Query | string | |
year | Query | integer (1900..) | |
city | Query | string | |
venue | Query | string | |
country | Query | string | ISO 3166-1 alpha-2 country code, or all. No filter by default. |
limit | Query | integer (1..50) = 20 | Page size (1 to 50). |
Antworten
200OK400Invalid parameter403Scope missing on this key
Beispiel
curl "https://theglobalfestivalmap.com/api/catalog/v1/past-events/search?artist=hellfest" \ -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
200OK400Invalid parameter403Scope 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
venueIderforderlich | Pfad | string | |
from | Query | string date | ISO date (YYYY-MM-DD), inclusive. |
to | Query | string date | ISO date (YYYY-MM-DD), inclusive. |
limit | Query | integer (1..100) = 20 | Page size (1 to 100). |
cursor | Query | string | The next_cursor of the previous page. Must be used with the same sort. |
Antworten
200OK400Invalid parameter403Scope missing on this key404Unknown resource
Beispiel
curl "https://theglobalfestivalmap.com/api/catalog/v1/venues/sfmvenue-3bd6b6b4/past" \ -H "X-Api-Key: $GLOBE_API_KEY"