{
 "openapi": "3.1.0",
 "info": {
  "title": "Spectacular Atlas API",
  "version": "1.0.0",
  "description": "Read-only search over Spectacular Atlas, a travel guide to visual art spectacles worldwide (light festivals, lantern festivals, drone shows, projection mapping, immersive venues, ice and snow festivals, giant parades). Dates come from quotes on organizers' websites and are re-checked automatically. Data licence CC BY 4.0: credit Spectacular Atlas and link to each event's page_url. Confirm dates on official_url before travelling.",
  "license": {
   "name": "CC BY 4.0 (data)",
   "url": "https://creativecommons.org/licenses/by/4.0/"
  }
 },
 "servers": [
  {
   "url": "https://spectacularatlas.com"
  }
 ],
 "paths": {
  "/api/events": {
   "get": {
    "operationId": "searchEvents",
    "summary": "Search spectacles by trip dates, place, type and size",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "description": "Words in the name, place or description, e.g. Harbin, Kyoto, lantern"
     },
     {
      "name": "from",
      "in": "query",
      "schema": {
       "type": "string",
       "format": "date"
      },
      "description": "Trip start (YYYY-MM-DD)"
     },
     {
      "name": "to",
      "in": "query",
      "schema": {
       "type": "string",
       "format": "date"
      },
      "description": "Trip end (YYYY-MM-DD)"
     },
     {
      "name": "country",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "description": "ISO 3166 code (JP) or country name"
     },
     {
      "name": "region",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "description": "East Asia, Southeast Asia, South Asia, Middle East and Central Asia, Europe, North America, Latin America and the Caribbean, Africa, Oceania"
     },
     {
      "name": "type",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "description": "Comma-separated: light, lantern, drone, projection, immersive, parade, fireworks, ice, balloon, cultural"
     },
     {
      "name": "size",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "description": "Comma-separated: Mega, Major, Notable"
     },
     {
      "name": "top",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "0",
        "1"
       ]
      },
      "description": "1 for top picks only"
     },
     {
      "name": "confirmed",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "0",
        "1"
       ]
      },
      "description": "1 for events with dates published by the organizer only"
     },
     {
      "name": "near",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "description": "lat,lng of a place to search around, e.g. 45.76,4.84"
     },
     {
      "name": "radius_km",
      "in": "query",
      "schema": {
       "type": "number",
       "default": 250
      },
      "description": "Radius around `near`, km"
     },
     {
      "name": "sort",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "soonest",
        "size",
        "distance"
       ]
      },
      "description": "soonest (default), size, or distance (default when near is given)"
     },
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 100,
       "default": 20
      }
     },
     {
      "name": "offset",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 0,
       "default": 0
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Matching spectacles (total, offset, limit, events[], license, attribution)",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SearchResult"
        }
       }
      }
     }
    }
   }
  },
  "/api/events/{id}": {
   "get": {
    "operationId": "getEvent",
    "summary": "One spectacle by id",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "The spectacle"
     },
     "404": {
      "description": "No such id"
     }
    }
   }
  },
  "/api/meta": {
   "get": {
    "operationId": "listFilters",
    "summary": "Types, sizes, regions and countries, with counts",
    "responses": {
     "200": {
      "description": "Facets"
     }
    }
   }
  }
 },
 "components": {
  "schemas": {
   "Event": {
    "type": "object",
    "properties": {
     "id": {
      "type": [
       "string",
       "null"
      ]
     },
     "name": {
      "type": [
       "string",
       "null"
      ]
     },
     "also_known_as": {
      "type": [
       "string",
       "null"
      ]
     },
     "local_name": {
      "type": [
       "string",
       "null"
      ]
     },
     "size": {
      "type": [
       "string",
       "null"
      ]
     },
     "status": {
      "type": [
       "string",
       "null"
      ]
     },
     "status_label": {
      "type": [
       "string",
       "null"
      ]
     },
     "start": {
      "type": [
       "string",
       "null"
      ]
     },
     "end": {
      "type": [
       "string",
       "null"
      ]
     },
     "schedule": {
      "type": [
       "string",
       "null"
      ]
     },
     "city": {
      "type": [
       "string",
       "null"
      ]
     },
     "place": {
      "type": [
       "string",
       "null"
      ]
     },
     "country": {
      "type": [
       "string",
       "null"
      ]
     },
     "country_name": {
      "type": [
       "string",
       "null"
      ]
     },
     "region": {
      "type": [
       "string",
       "null"
      ]
     },
     "description": {
      "type": [
       "string",
       "null"
      ]
     },
     "official_url": {
      "type": [
       "string",
       "null"
      ]
     },
     "last_checked": {
      "type": [
       "string",
       "null"
      ]
     },
     "page_url": {
      "type": [
       "string",
       "null"
      ]
     },
     "types": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "top_pick": {
      "type": "boolean"
     },
     "end_unknown": {
      "type": "boolean"
     },
     "lat": {
      "type": [
       "number",
       "null"
      ]
     },
     "lng": {
      "type": [
       "number",
       "null"
      ]
     },
     "free": {
      "type": [
       "boolean",
       "null"
      ]
     },
     "distance_km": {
      "type": "number"
     },
     "date_source": {
      "type": [
       "object",
       "null"
      ],
      "properties": {
       "url": {
        "type": "string"
       },
       "quote": {
        "type": "string"
       }
      }
     }
    }
   },
   "SearchResult": {
    "type": "object",
    "properties": {
     "total": {
      "type": "integer"
     },
     "offset": {
      "type": "integer"
     },
     "limit": {
      "type": "integer"
     },
     "events": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Event"
      }
     },
     "license": {
      "type": "string"
     },
     "attribution": {
      "type": "string"
     },
     "data_updated": {
      "type": "string"
     },
     "note": {
      "type": "string"
     }
    }
   }
  }
 }
}