Spectacular Atlas

Find spectacles worldwide (festivals, parades, light and drone shows, eccentric traditions) by trip dates, place, type and size. Returns up to `limit` events, soonest first (or nearest first when near_lat/near_lng are given), each with dates, status, place, type, size, description, official website and the event's page on spectacularatlas.com.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Words in the name, place or description, e.g. 'Harbin', 'Kyoto', 'lantern'."
    },
    "from": {
      "type": "string",
      "description": "Trip start, YYYY-MM-DD: events running on or after this day."
    },
    "to": {
      "type": "string",
      "description": "Trip end, YYYY-MM-DD: events that have started by this day."
    },
    "country": {
      "type": "string",
      "description": "ISO 3166 country code (e.g. JP) or country name."
    },
    "region": {
      "type": "string",
      "description": "One of: East Asia, Southeast Asia, South Asia, Middle East and Central Asia, Europe, North America, Latin America and the Caribbean, Africa, Oceania."
    },
    "types": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "light",
          "lantern",
          "drone",
          "projection",
          "immersive",
          "parade",
          "fireworks",
          "ice",
          "balloon",
          "sand",
          "animals",
          "battles",
          "contests",
          "cultural"
        ]
      },
      "description": "Types of spectacle: light (Light festivals and light art), lantern (Lanterns), drone (Drone shows), projection (Projection mapping), immersive (Immersive venues), parade (Parades and carnivals), fireworks (Fireworks), ice (Ice and snow), balloon (Balloons and kites), sand (Sand sculpture), animals (Animal spectacles), battles (Food fights and mass battles), contests (Odd contests and races), cultural (Cultural festivals)."
    },
    "sizes": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "Mega",
          "Major",
          "Notable"
        ]
      },
      "description": "Mega: about a million visitors or more or a national flagship; Major: about 200,000 to a million; Notable: smaller."
    },
    "confirmed_only": {
      "type": "boolean",
      "description": "Only events whose dates the organizer has published."
    },
    "year_round": {
      "type": "string",
      "enum": [
        "include",
        "exclude",
        "only"
      ],
      "default": "include",
      "description": "Venues open all year and regular shows without a season: include them (default), exclude them, or return only them."
    },
    "near_lat": {
      "type": "number",
      "description": "Latitude of a place to search around."
    },
    "near_lng": {
      "type": "number",
      "description": "Longitude of a place to search around."
    },
    "radius_km": {
      "type": "number",
      "description": "Search radius around near_lat/near_lng in km (default 250)."
    },
    "sort": {
      "type": "string",
      "enum": [
        "soonest",
        "size",
        "distance"
      ],
      "description": "Order of results."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "description": "How many events to return (default 10)."
    }
  }
}

Full details of one spectacle by its id (from search_events): dates, status, place and coordinates, official website, the quoted source of its dates and when it was last checked.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The event id, e.g. 'sapporo-snow-festival'."
    }
  },
  "required": [
    "id"
  ]
}

The types, sizes, regions and countries in the guide, with how many spectacles each has, and how many are venues and shows open all year (the year_round option of search_events).

{
  "type": "object",
  "properties": {}
}