Ir al contenido

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 clave

Primeros 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 version

sin clave

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

Respuestas

  • 200 OK

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

  • 200 OK
  • 401 Missing or refused key

Ejemplo

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

sin clave

Respuestas

  • 200 OpenAPI 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

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.

Respuestas

  • 200 OK
  • 400 Invalid 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

slugobligatoriorutastring

Respuestas

  • 200 OK
  • 404 Unknown 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

  • 200 OK
  • 400 Invalid 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

idOrSlugobligatoriorutastringArtist slug, or art-<slug> id.

Respuestas

  • 200 OK
  • 404 Unknown 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

  • 200 OK
  • 400 Invalid 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.

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

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

Respuestas

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

Ejemplo

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

Cuerpo

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

Respuestas

  • 200 OK
  • 400 Invalid parameter
  • 403 Scope 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

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

Respuestas

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

Ejemplo

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