swagger: "2.0"
schemes:
  - https
host: rest.bandsintown.com
info:
  contact:
    name: Bandsintown
    url: https://bandsintown.com/
    x-twitter: Bandsintown
  description: |
    # What is the Bandsintown API?
    The Bandsintown API is designed for artists and enterprises representing artists.

    It offers read-only access to artist info and artist events:
    - artist info: returns the link to the Bandsintown artist page, the link to the artist photo, the current number of trackers and more
    - artist events: returns the list of events including their date and time, venue name and location, ticket links, lineup, description and the link to the Bandsintown event page

    Note you can specify if you only want to return upcoming events, past events, all events, or events within a given date range.

    # Getting Started
    - In order to use the Bandsintown API, you must read and accept our Terms and Conditions below and you must have written consent from Bandsintown Inc. Any other use of the Bandsintown API is prohibited. [Contact Bandsintown](http://help.bandsintown.com/) to tell us what you plan to do and request your personal application ID.
    - Find out about the API methods available and the format of the API responses below. Select the method you wish to use and try it out online with the app ID provided to you.
    - Call our Bandsintown API with the app ID provided straight from your website or back-end platform and choose which element of the API response you wish to display. Scroll to the bottom of this page to find out about the Models used.
  license:
    name: Terms and Conditions
    url: https://corp.bandsintown.com/data-applications-terms
  title: Bandsintown API
  version: 3.0.0
  x-apisguru-categories:
    - social
  x-logo:
    url: https://twitter.com/Bandsintown/profile_image?size=original
  x-origin:
    - format: swagger
      url: https://api.swaggerhub.com/apis/Bandsintown/PublicAPI/3.0.0/swagger.yaml
      version: "2.0"
  x-providerName: bandsintown.com
paths:
  "/artists/{artistname}":
    get:
      description: |
        Get artist information
      operationId: artist
      parameters:
        - description: 'The name of the artist. If it contains one of the special characters below, please be sure to replace it by the corresponding code: for / use %252F, for ? use %253F, for * use %252A, and for " use %27C'
          in: path
          name: artistname
          required: true
          type: string
        - description: The application ID assigned to you by Bandsintown
          in: query
          name: app_id
          required: true
          type: string
      produces:
        - application/json
      responses:
        "200":
          description: 200 response
          schema:
            $ref: "#/definitions/ArtistData"
      summary: Get artist information
      tags:
        - artist information
  "/artists/{artistname}/events":
    get:
      description: |
        artist events
      operationId: artistEvents
      parameters:
        - description: 'The name of the artist. If it contains one of the special characters below, please be sure to replace it by the corresponding code: for / use %252F, for ? use %253F, for * use %252A, and for " use %27C'
          in: path
          name: artistname
          required: true
          type: string
        - description: The application ID assigned to you by Bandsintown
          in: query
          name: app_id
          required: true
          type: string
        - description: 'Can be one of the following values: "upcoming", "past", "all", or a date range e.g. "2015-05-05,2017-05-05". If not specified, only upcoming shows are returned'
          in: query
          name: date
          required: false
          type: string
      produces:
        - application/json
      responses:
        "200":
          description: Shows within a date range for the selected artist
          schema:
            items:
              $ref: "#/definitions/EventData"
            type: array
      summary: Get upcoming, past, or all artist events, or events within a date range
      tags:
        - artist events
definitions:
  ArtistData:
    properties:
      facebook_page_url:
        example: https://www.facebook.com/maroon5
        format: url
        type: string
      id:
        example: 510
        type: integer
      image_url:
        example: https://s3.amazonaws.com/bit-photos/large/7481529.jpeg
        format: url
        type: string
      mbid:
        example: 0ab49580-c84f-44d4-875f-d83760ea2cfe
        type: string
      name:
        example: Maroon 5
        type: string
      thumb_url:
        example: https://s3.amazonaws.com/bit-photos/thumb/7481529.jpeg
        format: url
        type: string
      tracker_count:
        type: integer
      upcoming_event_count:
        type: integer
      url:
        example: http://www.bandsintown.com/Maroon5?came_from=67
        format: url
        type: string
    required:
      - name
      - url
      - image_url
      - thumb_url
      - facebook_page_url
      - mbid
      - tracker_count
      - upcoming_event_count
    type: object
  EventData:
    properties:
      artist_id:
        example: "438314"
        format: integer
        type: string
      datetime:
        example: 2017-03-19T11:00:00
        format: datetime
        type: string
      description:
        example: This is a description
        type: string
      id:
        example: "13722599"
        format: integer
        type: string
      lineup:
        items:
          type: string
        type: array
      offers:
        items:
          $ref: "#/definitions/OfferData"
        type: array
      on_sale_datetime:
        example: 2017-03-01T18:00:00
        format: datetime
        type: string
      url:
        example: http://www.bandsintown.com/event/13722599?app_id=foo&artist=Skrillex&came_from=67
        format: url
        type: string
      venue:
        $ref: "#/definitions/VenueData"
    required:
      - id
      - artist_id
      - url
      - on_sale_datetime
      - datetime
      - venue
      - offers
      - lineup
    type: object
  OfferData:
    properties:
      status:
        example: available
        type: string
      type:
        example: Tickets
        type: string
      url:
        example: http://www.bandsintown.com/event/13722599/buy_tickets?app_id=foo&artist=Skrillex&came_from=67
        format: url
        type: string
    required:
      - type
      - url
      - status
    type: object
  VenueData:
    properties:
      city:
        example: Las Vegas
        type: string
      country:
        example: United States
        type: string
      latitude:
        example: "36.12714"
        format: double
        type: string
      longitude:
        example: "-115.1629562"
        format: double
        type: string
      name:
        example: Encore Beach Club
        type: string
      region:
        example: NV
        type: string
    required:
      - name
      - latitude
      - longitude
      - city
      - region
      - country
    type: object
