Tickets.dev Capture API

openapi: 3.2.0
info:
  title: Tickets.dev Capture API
  version: '1'
  description: 'Live ticket listings, all-in prices and seat maps from Ticketmaster, StubHub, SeatGeek, Vivid Seats, TickPick, Gametime, Viagogo and more, in one schema. Use the API key tk_test_sandbox to try it: it returns fixed sample data and is never billed.'
  contact:
    url: https://tickets.dev/docs
  termsOfService: https://tickets.dev/terms-of-service
servers:
- url: https://api.tickets.dev
tags:
- name: Capture
paths:
  /v1/capture:
    get:
      operationId: capture
      summary: 'Capture one event: every listing on it, in one response'
      description: 'Capture one event: every listing on it, in one response. A live key spends one credit; tk_test_sandbox returns a fixture and is never billed.'
      x-billable: true
      security:
      - apiKey: []
      parameters:
      - name: url
        in: query
        required: true
        schema:
          type: string
        description: A marketplace event page URL.
      - name: source
        in: query
        required: false
        schema:
          type: string
        description: Marketplace key, only needed when the URL's host doesn't say (see /v1/capture/sources).
      - name: includeVenueMaps
        in: query
        required: false
        schema:
          type: boolean
        description: true to also return the seat map SVGs.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Snapshot'
        4XX:
          description: Request error, e.g. invalid_key (401), marketplace_required (400), rate_limited (429, with Retry-After).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Error. Retry only when error.retryable is true; 429 sends Retry-After.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Capture
  /v1/capture/{source}:
    get:
      operationId: captureFromSource
      summary: The same capture with the marketplace in the path, e.g
      description: The same capture with the marketplace in the path, e.g. /v1/capture/ticketmaster.
      x-billable: true
      security:
      - apiKey: []
      parameters:
      - name: source
        in: path
        required: true
        schema:
          type: string
        description: Marketplace key, e.g. ticketmaster.
      - name: url
        in: query
        required: true
        schema:
          type: string
        description: A marketplace event page URL.
      - name: includeVenueMaps
        in: query
        required: false
        schema:
          type: boolean
        description: true to also return the seat map SVGs.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Snapshot'
        4XX:
          description: Request error, e.g. invalid_key (401), marketplace_required (400), rate_limited (429, with Retry-After).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Error. Retry only when error.retryable is true; 429 sends Retry-After.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Capture
  /v1/capture/sources:
    get:
      operationId: listSources
      summary: The marketplaces you can capture, and the hosts that route to each
      description: The marketplaces you can capture, and the hosts that route to each. Never billable.
      x-billable: false
      security:
      - apiKey: []
      parameters: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sources'
        4XX:
          description: Request error, e.g. invalid_key (401), marketplace_required (400), rate_limited (429, with Retry-After).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Error. Retry only when error.retryable is true; 429 sends Retry-After.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Capture
components:
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          - retryable
          properties:
            code:
              type: string
              description: Machine-readable error code, e.g. invalid_key, marketplace_required, rate_limited.
            message:
              type: string
              description: What went wrong, for people.
            outcome:
              type: string
              description: How the request ended, e.g. rejected.
            retryable:
              type: boolean
              description: Whether retrying the same request can succeed. 429 responses also send Retry-After.
            request_id:
              type: string
              description: Quote this when contacting support.
    Sources:
      type: object
      properties:
        sources:
          type: array
          items:
            type: object
            properties:
              source:
                type: string
                description: Marketplace key.
              hosts:
                type: array
                items:
                  type: string
                description: Hosts that route to it.
              searchable:
                type: boolean
                description: Whether /v1/events covers it.
    Snapshot:
      type: object
      description: 'One capture: every listing on one event page on one marketplace, at capturedAt.'
      properties:
        source:
          type: string
          description: The marketplace, e.g. stubhub.
        eventId:
          type: string
          description: The marketplace's own id for the event.
        eventName:
          type: string
          description: Event title.
        performers:
          type: array
          items:
            type: object
          description: Performers, as the marketplace lists them.
        venueId:
          type: string
          description: The marketplace's own venue id.
        venueName:
          type: string
          description: Venue name.
        venueAddress:
          type: string
          description: Street address of the venue.
        venueCity:
          type: string
          description: Venue city.
        venueState:
          type: string
          description: Venue state or province.
        venueTimezone:
          type: string
          description: Venue time zone, where the marketplace gives one.
        eventDateLocal:
          type: string
          description: Event date and time, venue-local ISO 8601 with offset.
        eventDateUtc:
          type: string
          description: The same moment in ISO 8601 UTC.
        sourceUrl:
          type: string
          description: The event page the capture read.
        capturedAt:
          type: string
          description: When the capture ran, ISO 8601 UTC.
        currency:
          type: string
          description: ISO 4217 currency of every price in the snapshot.
        note:
          type: string
          description: The marketplace's notice, e.g. sold out or canceled. An empty capture with no note may be a partial page.
        sectionLevelUrl:
          type: string
          description: 'With includeVenueMaps: section map SVG; shapes carry the listings'' section names.'
        seatLevelUrl:
          type: string
          description: 'With includeVenueMaps: seat or row level map SVG.'
        stats:
          $ref: '#/components/schemas/Stats'
        listings:
          type: array
          items:
            $ref: '#/components/schemas/Listing'
        venueLayout:
          type: object
          description: Sections, rows and seats of the venue map, where available.
    Listing:
      type: object
      properties:
        listingId:
          type: string
          description: 'The marketplace''s own id for the listing: compare it within one marketplace only.'
        inventoryType:
          type: string
          description: primary or resale.
        section:
          type: string
          description: Section, as the marketplace names it. Matches data-section in the seat map SVG.
        row:
          type: string
          description: Row label.
        seats:
          type: string
          description: Comma-separated seat numbers, when the marketplace shows them.
        quantity:
          type: number
          description: Seats available in this listing.
        sellableQuantities:
          type: string
          description: Quantities a buyer can buy, e.g. "2,4". A listing of 3 selling as "1,3" cannot sell 2.
        ticketPrice:
          type: number
          description: Face price per ticket, before fees.
        fee:
          type: number
          description: Per-ticket fees. 0 where the marketplace shows only an all-in price.
        totalPrice:
          type: number
          description: All-in price per ticket, excluding sales tax, with the same meaning on every marketplace.
        ticketType:
          type: string
          description: Delivery or ticket type, as the marketplace shows it.
        group:
          type: string
          description: The marketplace's zone or price level, e.g. 100 Level.
        listingNotes:
          type: string
          description: Listing features, e.g. Clear view or Obstructed view.
        dealScore:
          type: string
          description: The marketplace's own value score, as it shows it. Empty where it shows none.
    Stats:
      type: object
      properties:
        listingCount:
          type: number
          description: Listings on the page.
        ticketCount:
          type: number
          description: Tickets across all listings.
        getInPrice:
          type: number
          description: Lowest all-in price per ticket. 0 when there are no listings.
        medianPrice:
          type: number
          description: Median all-in price per ticket.
        avgPrice:
          type: number
          description: Mean all-in price per ticket.
        maxPrice:
          type: number
          description: Highest all-in price per ticket.
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
externalDocs:
  url: https://tickets.dev/docs