API

Le catalogue GLOBE, en API

Tout ce que le site sait de plus de 11 000 festivals et 40 000 artistes, en JSON : listes, fiches, programmations, recherche tolérante aux fautes. Lecture seule, une clé, des quotas clairs.

Demander une clé

Pour commencer

Chaque requête part vers l’adresse de base ci-dessus et porte votre clé dans l’en-tête X-Api-Key. Demandez une clé par email : dites qui vous êtes et ce que vous voulez construire.

Les réponses ont toujours la même enveloppe : generated_at, catalog_version, count, next_cursor et data. Les listes se paginent par curseur opaque : renvoyez next_cursor en cursor, avec le même sort, jusqu’à ce qu’il revienne null.

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

Quotas et en-têtes

Deux plafonds par clé, par minute et par jour, annoncés sur chaque réponse : X-RateLimit-Limit-Minute, X-RateLimit-Remaining-Minute, X-Quota-Limit-Day, X-Quota-Remaining-Day. Au-delà, l’API répond 429 avec rate_limited ou daily_quota_exceeded et un Retry-After.

Les réponses GET portent un ETag : envoyez If-None-Match pour obtenir un 304 et économiser votre quota. Les appels sans clé sont tolérés pendant une période de grâce avec un en-tête X-Catalog-Warning, puis refusés en 401 api_key_required.

Scopes et sources

catalog couvre les festivals, les artistes et la recherche. past_events couvre les concerts passés, qui viennent de l’archive setlist.fm : l’attribution est obligatoire et l’usage commercial interdit sans leur accord écrit, ce scope ne fait donc partie d’aucune offre payante. Une clé sans ce scope reçoit 403 scope_required.

Les données festivals viennent de registres publics, de Wikidata, d’OpenStreetMap, des sites officiels et des organisateurs ; les artistes de MusicBrainz, Spotify, Deezer et Ticketmaster. La liste complète et les licences sont sur la page crédits.

Erreurs

Chaque erreur porte un error.code stable à tester, un error.message lisible et, quand c’est utile, error.details avec ce qui a été refusé. Codes rencontrés : la famille bad_request (400), api_key_required (401), scope_required (403), not_found (404), rate_limited et daily_quota_exceeded (429).

Essayer

Votre clé reste dans cet onglet (stockage de session) et l’appel part directement vers l’API, pas par le site.

Référence

Générée depuis le document OpenAPI en ligne. Téléchargez-le pour brancher l’API dans Postman, Insomnia, n8n ou un générateur de client.

Document OpenAPI (JSON) · GLOBE catalog API 1.0.0

Account

Your key, quotas and usage.

GET/versionAPI and catalog version

sans clé

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

Réponses

200 OK

Exemple

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.

Réponses

200 OK
401 Missing or refused key

Exemple

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

GET/openapi.jsonThis specification

sans clé

Réponses

200 OpenAPI 3.1 document

Exemple

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.

Paramètres

`country`	requête	string = FR	ISO 3166-1 alpha-2 country code, or all. Defaults to FR.
`from`	requête	string date	ISO date (YYYY-MM-DD), inclusive.
`to`	requête	string date	ISO date (YYYY-MM-DD), inclusive.
`genres`	requête	string	Comma-separated genre slugs (up to 10), e.g. rock,metal.
`q`	requête	string	Typo-tolerant text filter on the name.
`near`	requête	string	lat,lng. Enables distance_km in items and sort=distance.
`radius_km`	requête	number (..2000) = 100	Radius around near.
`sort`	requête	date \| distance \| popularity = date
`limit`	requête	integer (1..100) = 20	Page size (1 to 100).
`cursor`	requête	string	The next_cursor of the previous page. Must be used with the same sort.

Réponses

200 OK
400 Invalid parameter

Exemple

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.

Paramètres

slugrequis chemin string

Réponses

200 OK
404 Unknown resource

Exemple

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.

Corps

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

Réponses

200 OK
400 Invalid parameter

Exemple

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.

Paramètres

idOrSlugrequis chemin string Artist slug, or art-<slug> id.

Réponses

200 OK
404 Unknown resource

Exemple

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".

Corps

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

Réponses

200 OK
400 Invalid parameter

Exemple

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 > similar, then popularity.

Paramètres

`q`requis	requête	string
`types`	requête	string = artist,festival	Comma-separated: artist, festival.
`scope`	requête	published \| site = published	site restricts to the live, geolocated festivals shown on theglobalfestivalmap.com.
`limit`	requête	integer (1..50) = 8	Page size (1 to 50).

Réponses

200 OK
400 Invalid parameter

Exemple

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).

Paramètres

`idOrSlug`requis	chemin	string
`from`	requête	string date	ISO date (YYYY-MM-DD), inclusive.
`to`	requête	string date	ISO date (YYYY-MM-DD), inclusive.
`country`	requête	string	ISO 3166-1 alpha-2 country code, or all. No filter by default.
`limit`	requête	integer (1..100) = 20	Page size (1 to 100).
`cursor`	requête	string	The next_cursor of the previous page. Must be used with the same sort.

Réponses

200 OK
403 Scope missing on this key
404 Unknown resource

Exemple

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).

Paramètres

`artist`requis	requête	string
`year`	requête	integer (1900..)
`city`	requête	string
`venue`	requête	string
`country`	requête	string	ISO 3166-1 alpha-2 country code, or all. No filter by default.
`limit`	requête	integer (1..50) = 20	Page size (1 to 50).

Réponses

200 OK
400 Invalid parameter
403 Scope missing on this key

Exemple

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).

Corps

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

Réponses

200 OK
400 Invalid parameter
403 Scope missing on this key

Exemple

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).

Paramètres

`venueId`requis	chemin	string
`from`	requête	string date	ISO date (YYYY-MM-DD), inclusive.
`to`	requête	string date	ISO date (YYYY-MM-DD), inclusive.
`limit`	requête	integer (1..100) = 20	Page size (1 to 100).
`cursor`	requête	string	The next_cursor of the previous page. Must be used with the same sort.

Réponses

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

Exemple

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