TVmaze
TVmaze Search API

Free-text search and lookup endpoints for shows and people.
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.0.0
info:
  title: TVmaze Premium User auth Search API
  description: 'Premium-only user API for TVmaze. Access is restricted to users with a paid

    [Premium subscription](https://www.tvmaze.com/premium). A user can only access

    their own data.


    Authentication uses HTTP Basic: the TVmaze username is the basic-auth username and

    the API key (visible on the user dashboard) is the basic-auth password. There is

    also a device-style auth-pairing flow exposed at `/auth/start` and `/auth/poll`.

    '
  version: '1.0'
  contact:
    name: TVmaze
    url: https://www.tvmaze.com
  license:
    name: CC BY-SA 4.0
    url: https://creativecommons.org/licenses/by-sa/4.0/
servers:
- url: https://api.tvmaze.com/v1
- url: http://api.tvmaze.com/v1
security:
- usertoken: []
tags:
- name: Search
  description: Free-text search and lookup endpoints for shows and people.
paths:
  /search/shows:
    get:
      tags:
      - Search
      operationId: searchShows
      summary: Search Shows
      description: Search for shows using a fuzzy text query.
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
        description: Search query string.
      responses:
        '200':
          description: List of show search hits scored by match.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    score:
                      type: number
                    show:
                      $ref: '#/components/schemas/Show'
              examples:
                default:
                  summary: Example response for /search/shows
                  value:
                  - score: 0.902979
                    show:
                      id: 139
                      url: https://www.tvmaze.com/shows/139/girls
                      name: Girls
                      type: Scripted
                      language: English
                      genres:
                      - Drama
                      - Romance
                      status: Ended
                      runtime: 30
                      averageRuntime: 30
                      premiered: '2012-04-15'
                      ended: '2017-04-16'
                      officialSite: http://www.hbo.com/girls
                      schedule:
                        time: 1320
                        days:
                        - Sunday
                      rating:
                        average: 6.5
                      weight: 98
                      network:
                        id: 8
                        name: HBO
                        country:
                          name: United States
                          code: US
                          timezone: America/New_York
                        officialSite: https://www.hbo.com/
                      webChannel: null
                      dvdCountry: null
                      externals:
                        tvrage: 30124
                        thetvdb: 220411
                        imdb: tt1723816
                      image:
                        medium: https://static.tvmaze.com/uploads/images/medium_portrait/31/78286.jpg
                        original: https://static.tvmaze.com/uploads/images/original_untouched/31/78286.jpg
                      summary: <p>This Emmy winning series is a comic look at the assorted humiliations and rare triumphs of a group of girls in their 20s.</p>
                      updated: 1704794122
                      _links:
                        self:
                          href: https://api.tvmaze.com/shows/139
                        previousepisode:
                          href: https://api.tvmaze.com/episodes/1079686
                          name: Latching
                  - score: 0.8784869
                    show:
                      id: 41734
                      url: https://www.tvmaze.com/shows/41734/girls
                      name: GIRLS
                      type: Scripted
                      language: Mongolian
                      genres:
                      - Comedy
                      status: Ended
                      runtime: 41
                      averageRuntime: 41
                      premiered: '2018-06-15'
                      ended: '2019-10-14'
                      officialSite: https://www.ubstv.mn/tech-blog/index1.html
                      schedule:
                        time: ''
                        days:
                        - Thursday
                      rating:
                        average: null
                      weight: 59
                      network:
                        id: 1672
                        name: UBS
                        country:
                          name: Mongolia
                          code: MN
                          timezone: Asia/Ulaanbaatar
                        officialSite: null
                      webChannel: null
                      dvdCountry: null
                      externals:
                        tvrage: null
                        thetvdb: null
                        imdb: tt8709752
                      image:
                        medium: https://static.tvmaze.com/uploads/images/medium_portrait/191/478539.jpg
                        original: https://static.tvmaze.com/uploads/images/original_untouched/191/478539.jpg
                      summary: null
                      updated: 1743150150
                      _links:
                        self:
                          href: https://api.tvmaze.com/shows/41734
                        previousepisode:
                          href: https://api.tvmaze.com/episodes/3187423
                          name: Episode 1
      x-microcks-operation:
        defaultExample: default
      x-microcks-default: default
  /singlesearch/shows:
    get:
      tags:
      - Search
      operationId: singleSearchShows
      summary: Single Search Shows
      description: Return the single best matching show for a query, optionally embedding related data.
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
      - name: embed
        in: query
        required: false
        schema:
          type: string
          enum:
          - episodes
          - cast
      responses:
        '200':
          description: A single show record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Show'
        '404':
          description: Not Found
  /lookup/shows:
    get:
      tags:
      - Search
      operationId: lookupShows
      summary: Lookup Shows By External ID
      description: Look up a show using a TVRage, TheTVDB, or IMDb identifier.
      parameters:
      - name: tvrage
        in: query
        required: false
        schema:
          type: integer
      - name: thetvdb
        in: query
        required: false
        schema:
          type: integer
      - name: imdb
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Matching show.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Show'
        '404':
          description: Not Found
  /search/people:
    get:
      tags:
      - Search
      operationId: searchPeople
      summary: Search People
      description: Search for people (actors, crew) using a fuzzy text query.
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: List of person search hits.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    score:
                      type: number
                    person:
                      $ref: '#/components/schemas/Person'
components:
  schemas:
    Show:
      type: object
      properties:
        id:
          type: integer
        url:
          type: string
          format: uri
        name:
          type: string
        type:
          type: string
          description: e.g. Scripted, Reality, Documentary
        language:
          type: string
          nullable: true
        genres:
          type: array
          items:
            type: string
        status:
          type: string
          description: e.g. Running, Ended, To Be Determined
        runtime:
          type: integer
          nullable: true
        averageRuntime:
          type: integer
          nullable: true
        premiered:
          type: string
          format: date
          nullable: true
        ended:
          type: string
          format: date
          nullable: true
        officialSite:
          type: string
          nullable: true
        schedule:
          $ref: '#/components/schemas/Schedule'
        rating:
          $ref: '#/components/schemas/Rating'
        weight:
          type: integer
        network:
          allOf:
          - $ref: '#/components/schemas/Network'
          nullable: true
        webChannel:
          allOf:
          - $ref: '#/components/schemas/WebChannel'
          nullable: true
        dvdCountry:
          allOf:
          - $ref: '#/components/schemas/Country'
          nullable: true
        externals:
          $ref: '#/components/schemas/Externals'
        image:
          allOf:
          - $ref: '#/components/schemas/Image'
          nullable: true
        summary:
          type: string
          nullable: true
          description: HTML summary
        updated:
          type: integer
          format: int64
        _links:
          $ref: '#/components/schemas/Links'
    Country:
      type: object
      properties:
        name:
          type: string
        code:
          type: string
        timezone:
          type: string
    WebChannel:
      allOf:
      - $ref: '#/components/schemas/Network'
    Links:
      type: object
      additionalProperties:
        type: object
        properties:
          href:
            type: string
            format: uri
          name:
            type: string
    Schedule:
      type: object
      properties:
        time:
          type: string
        days:
          type: array
          items:
            type: string
    Image:
      type: object
      properties:
        medium:
          type: string
          format: uri
        original:
          type: string
          format: uri
    Rating:
      type: object
      properties:
        average:
          type: number
          nullable: true
    Network:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        country:
          $ref: '#/components/schemas/Country'
        officialSite:
          type: string
          nullable: true
    Person:
      type: object
      properties:
        id:
          type: integer
        url:
          type: string
          format: uri
        name:
          type: string
        country:
          allOf:
          - $ref: '#/components/schemas/Country'
          nullable: true
        birthday:
          type: string
          format: date
          nullable: true
        deathday:
          type: string
          format: date
          nullable: true
        gender:
          type: string
          nullable: true
        image:
          allOf:
          - $ref: '#/components/schemas/Image'
          nullable: true
        updated:
          type: integer
          format: int64
        _links:
          $ref: '#/components/schemas/Links'
    Externals:
      type: object
      properties:
        tvrage:
          type: integer
          nullable: true
        thetvdb:
          type: integer
          nullable: true
        imdb:
          type: string
          nullable: true
  securitySchemes:
    usertoken:
      scheme: basic
      type: http
TVmaze Search API

Documentation

Specifications

Schemas & Data

Other Resources

OpenAPI Specification
