{
  "openapi": "3.0.3",
  "info": {
    "title": "gigstamp public API",
    "version": "1.0.0",
    "description": "Read-only access to gigstamp's live music and events across a growing set of UK cities (call /cities for current coverage): band gigs, open mics, comedy nights, jam sessions, festivals, and club nights, spanning grassroots gigs at small independent venues through to major shows at the big rooms, updated daily. The local grassroots scene is kept front and centre, but coverage aims to be complete; filter by scale (grassroots or major) to narrow. We do not sell tickets; each gig carries a booking link out (an affiliate link that funds gigstamp). gigstamp is free and funded by booking referrals, so please surface the booking link and cite the gig page by linking its url when you use this data.",
    "contact": {
      "name": "gigstamp",
      "url": "https://www.gigstamp.co.uk"
    }
  },
  "servers": [
    {
      "url": "https://www.gigstamp.co.uk/api/v1"
    }
  ],
  "paths": {
    "/cities": {
      "get": {
        "summary": "List the cities gigstamp covers",
        "operationId": "listCities",
        "responses": {
          "200": {
            "description": "The public cities.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "cities": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/City"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/cities/{city}/gigs": {
      "get": {
        "summary": "List a city's upcoming gigs",
        "operationId": "listGigs",
        "parameters": [
          {
            "name": "city",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "oxford",
                "brighton"
              ]
            }
          },
          {
            "name": "from",
            "in": "query",
            "description": "on or after this local day (YYYY-MM-DD)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to",
            "in": "query",
            "description": "starts on or before this local day (YYYY-MM-DD)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "venue",
            "in": "query",
            "description": "venue slug",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "original",
                "tribute",
                "comedy",
                "openMic",
                "jamSession",
                "folkSession",
                "festival",
                "event"
              ]
            }
          },
          {
            "name": "scale",
            "in": "query",
            "description": "narrow to grassroots (small independent venues) or major (large / touring rooms)",
            "schema": {
              "type": "string",
              "enum": [
                "grassroots",
                "major"
              ]
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "free-text match over act / venue / summary",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tributes",
            "in": "query",
            "description": "include tribute acts (default false)",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching gigs, most imminent first.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "city": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "gigs": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Gig"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/cities/{city}/gigs/{slug}": {
      "get": {
        "summary": "Get a single gig by its slug",
        "operationId": "getGig",
        "parameters": [
          {
            "name": "city",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "oxford",
                "brighton"
              ]
            }
          },
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The gig.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "gig": {
                      "$ref": "#/components/schemas/Gig"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/cities/{city}/venues": {
      "get": {
        "summary": "List a city's venues",
        "operationId": "listVenues",
        "parameters": [
          {
            "name": "city",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "oxford",
                "brighton"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The city's venues.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "city": {
                      "type": "string"
                    },
                    "venues": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Venue"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "NotFound": {
        "description": "No such city or gig.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "City": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "region": {
            "type": "string",
            "nullable": true
          },
          "country": {
            "type": "string",
            "nullable": true
          },
          "url": {
            "type": "string"
          },
          "feeds": {
            "type": "object",
            "properties": {
              "ical": {
                "type": "string"
              },
              "rss": {
                "type": "string"
              }
            }
          }
        }
      },
      "Venue": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "scale": {
            "type": "string",
            "enum": [
              "grassroots",
              "major"
            ],
            "description": "grassroots (small independent) or major (large / touring)"
          },
          "locality": {
            "type": "string",
            "nullable": true
          },
          "postcode": {
            "type": "string",
            "nullable": true
          },
          "lat": {
            "type": "number",
            "nullable": true
          },
          "lng": {
            "type": "number",
            "nullable": true
          },
          "website": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "Gig": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "slug": {
            "type": "string",
            "nullable": true
          },
          "url": {
            "type": "string"
          },
          "act": {
            "type": "string"
          },
          "support": {
            "type": "string",
            "nullable": true
          },
          "category": {
            "type": "string",
            "enum": [
              "original",
              "tribute",
              "comedy",
              "openMic",
              "jamSession",
              "folkSession",
              "festival",
              "event"
            ]
          },
          "scale": {
            "type": "string",
            "enum": [
              "grassroots",
              "major"
            ],
            "description": "grassroots (small independent venue) or major (large / touring room)"
          },
          "citySlug": {
            "type": "string"
          },
          "venue": {
            "type": "object",
            "properties": {
              "slug": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "locality": {
                "type": "string",
                "nullable": true
              },
              "lat": {
                "type": "number",
                "nullable": true
              },
              "lng": {
                "type": "number",
                "nullable": true
              }
            }
          },
          "date": {
            "type": "string",
            "format": "date"
          },
          "endDate": {
            "type": "string",
            "format": "date",
            "nullable": true
          },
          "startTime": {
            "type": "string",
            "nullable": true
          },
          "start": {
            "type": "string"
          },
          "price": {
            "type": "string",
            "nullable": true,
            "description": "raw price label, verbatim"
          },
          "booking": {
            "type": "object",
            "nullable": true,
            "properties": {
              "url": {
                "type": "string"
              },
              "source": {
                "type": "string"
              }
            }
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "source": {
                  "type": "string"
                },
                "url": {
                  "type": "string",
                  "nullable": true
                }
              }
            }
          },
          "summary": {
            "type": "string",
            "nullable": true
          },
          "image": {
            "type": "string",
            "nullable": true
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}