API
El catálogo de GLOBE, como API
Todo lo que el sitio sabe sobre más de 11.000 festivales y 40.000 artistas, en JSON simple: listas, páginas, carteles, búsqueda tolerante a erratas. Solo lectura, una clave, cuotas claras.
https://theglobalfestivalmap.com/api/catalog/v1Pedir una clavePrimeros pasos
Cada petición va a la dirección base de arriba y lleva tu clave en la cabecera X-Api-Key. Pide una clave por correo: di quién eres y qué quieres construir.
Las respuestas siempre tienen la misma envoltura: generated_at, catalog_version, count, next_cursor y data. Las listas se paginan con un cursor opaco: devuelve next_cursor como cursor, con la misma ordenación, hasta que vuelva null.
curl "https://theglobalfestivalmap.com/api/catalog/v1/search?q=hellfest" \ -H "X-Api-Key: $GLOBE_API_KEY"
Cuotas y cabeceras
Dos límites por clave, por minuto y por día, anunciados en cada respuesta: X-RateLimit-Limit-Minute, X-RateLimit-Remaining-Minute, X-Quota-Limit-Day, X-Quota-Remaining-Day. Superado el límite, la API responde 429 con rate_limited o daily_quota_exceeded y un Retry-After.
Las respuestas GET llevan un ETag: envía If-None-Match para obtener un 304 y ahorrar cuota. Las llamadas sin clave se toleran durante un periodo de gracia con una cabecera X-Catalog-Warning, y después se rechazan con 401 api_key_required.
Ámbitos y fuentes
catalog cubre festivales, artistas y búsqueda. past_events cubre los conciertos pasados, que proceden del archivo de setlist.fm: la atribución es obligatoria y el uso comercial no está permitido sin su acuerdo escrito, por lo que ese ámbito no forma parte de ningún plan de pago. Una clave sin el ámbito recibe 403 scope_required.
Los datos de festivales proceden de registros públicos, Wikidata, OpenStreetMap, sitios oficiales y organizadores; los artistas, de MusicBrainz, Spotify, Deezer y Ticketmaster.
Errores
Cada error tiene un error.code estable que puedes comprobar, un error.message legible y, cuando resulta útil, un error.details con lo que se rechazó. Códigos que encontrarás: familia bad_request (400), api_key_required (401), scope_required (403), not_found (404), rate_limited y daily_quota_exceeded (429).
Pruébala
Pruébala
Tu clave se queda en esta pestaña del navegador (session storage) y la llamada va directamente a la API, no pasa por el sitio.
Referencia
Generada a partir del documento OpenAPI en vivo. Descárgalo para conectar la API a Postman, Insomnia, n8n o un generador de clientes.
Documento OpenAPI (JSON) · GLOBE catalog API 1.0.0
Account
Your key, quotas and usage.
GET/versionAPI and catalog versionsin clave
Catalog timestamp, available endpoints, data sources and required attributions.
Respuestas
200OK
Ejemplo
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.
Respuestas
200OK401Missing or refused key
Ejemplo
curl "https://theglobalfestivalmap.com/api/catalog/v1/me" \ -H "X-Api-Key: $GLOBE_API_KEY"
GET/openapi.jsonThis specificationsin clave
Respuestas
200OpenAPI 3.1 document
Ejemplo
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.
Parámetros
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. |
Respuestas
200OK400Invalid parameter
Ejemplo
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.
Parámetros
slugobligatorio | ruta | string |
Respuestas
200OK404Unknown resource
Ejemplo
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.
Cuerpo
{
"ids": [
"hellfest-open-air",
"rock-en-seine"
]
}Respuestas
200OK400Invalid parameter
Ejemplo
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.
Parámetros
idOrSlugobligatorio | ruta | string | Artist slug, or art-<slug> id. |
Respuestas
200OK404Unknown resource
Ejemplo
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".
Cuerpo
{
"ids": [
"hellfest-open-air",
"rock-en-seine"
]
}Respuestas
200OK400Invalid parameter
Ejemplo
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.
Parámetros
qobligatorio | 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). |
Respuestas
200OK400Invalid parameter
Ejemplo
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).
Parámetros
idOrSlugobligatorio | ruta | 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. |
Respuestas
200OK403Scope missing on this key404Unknown resource
Ejemplo
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).
Parámetros
artistobligatorio | 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). |
Respuestas
200OK400Invalid parameter403Scope missing on this key
Ejemplo
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).
Cuerpo
{
"ids": [
"hellfest-open-air",
"rock-en-seine"
]
}Respuestas
200OK400Invalid parameter403Scope missing on this key
Ejemplo
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).
Parámetros
venueIdobligatorio | ruta | 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. |
Respuestas
200OK400Invalid parameter403Scope missing on this key404Unknown resource
Ejemplo
curl "https://theglobalfestivalmap.com/api/catalog/v1/venues/sfmvenue-3bd6b6b4/past" \ -H "X-Api-Key: $GLOBE_API_KEY"