API

The GLOBE catalog, as an API

Everything the site knows about 11,000+ festivals and 40,000+ artists, as plain JSON: lists, pages, lineups, typo-tolerant search. Read-only, one key, clear quotas.

Ask for a key

Getting started

Every request goes to the base address above and carries your key in the X-Api-Key header. Ask for a key by email: say who you are and what you want to build.

Responses always have the same envelope: generated_at, catalog_version, count, next_cursor and data. Lists paginate with an opaque cursor: pass next_cursor back as cursor, with the same sort, until it comes back null.

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

Quotas and headers

Two limits per key, per minute and per day, announced on every response: X-RateLimit-Limit-Minute, X-RateLimit-Remaining-Minute, X-Quota-Limit-Day, X-Quota-Remaining-Day. Past the limit the API answers 429 with rate_limited or daily_quota_exceeded and a Retry-After.

GET responses carry an ETag: send If-None-Match to get a 304 and save your quota. Calls without a key are tolerated for a grace period with an X-Catalog-Warning header, then refused with 401 api_key_required.

Scopes and sources

catalog covers festivals, artists and search. past_events covers past concerts, which come from the setlist.fm archive: attribution is required and commercial use is not allowed without their written agreement, so that scope is not part of any paid plan. A key without the scope gets 403 scope_required.

Festival data comes from public registers, Wikidata, OpenStreetMap, official websites and organisers; artists from MusicBrainz, Spotify, Deezer and Ticketmaster. The full list and licences are on the credits page.

Errors

Every error has a stable error.code you can test, a readable error.message and, when useful, error.details with what was refused. Codes you will meet: bad_request family (400), api_key_required (401), scope_required (403), not_found (404), rate_limited and daily_quota_exceeded (429).

Try it

Your key stays in this browser tab (session storage) and the call goes straight to the API, not through the site.

Reference

Generated from the live OpenAPI document. Download it to plug the API into Postman, Insomnia, n8n or a client generator.

OpenAPI document (JSON) · GLOBE catalog API 1.0.0

Account

Your key, quotas and usage.

GET/versionAPI and catalog version

no key needed

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

Responses

200 OK

Example

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.

Responses

200 OK
401 Missing or refused key

Example

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

GET/openapi.jsonThis specification

no key needed

Responses

200 OpenAPI 3.1 document

Example

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.

Parameters

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

Responses

200 OK
400 Invalid parameter

Example

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.

Parameters

slugrequired path string

Responses

200 OK
404 Unknown resource

Example

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"
  ]
}

Responses

200 OK
400 Invalid parameter

Example

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.

Parameters

idOrSlugrequired path string Artist slug, or art-<slug> id.

Responses

200 OK
404 Unknown resource

Example

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"
  ]
}

Responses

200 OK
400 Invalid parameter

Example

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.

Parameters

`q`required	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).

Responses

200 OK
400 Invalid parameter

Example

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

Parameters

`idOrSlug`required	path	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.

Responses

200 OK
403 Scope missing on this key
404 Unknown resource

Example

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

Parameters

`artist`required	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).

Responses

200 OK
400 Invalid parameter
403 Scope missing on this key

Example

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"
  ]
}

Responses

200 OK
400 Invalid parameter
403 Scope missing on this key

Example

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

Parameters

`venueId`required	path	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.

Responses

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

Example

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