openapi: 3.0.3
info:
  title: Spreaker Advertising Statistics API
  description: The Spreaker API (v2) is a REST API for the Spreaker podcast hosting, distribution, and monetization platform, owned by iHeartMedia. It lets developers manage users and their social graph, podcast shows, episodes (including uploads, playback, messages, chapters, and ad cuepoints), analytics and statistics, search and discovery, and the advertising campaign stack. All access is over HTTPS at api.spreaker.com. GET requests are public unless otherwise noted; all PUT, POST, and DELETE requests must be authenticated with an OAuth2 Bearer token. Responses are paginated with a default of 50 items per page (up to 100 via the limit parameter) and a next_url property for the following page.
  version: '2.0'
  contact:
    name: Spreaker for Developers
    url: https://developers.spreaker.com
  license:
    name: Proprietary
    url: https://www.spreaker.com/terms-of-service
servers:
- url: https://api.spreaker.com/v2
  description: Spreaker API v2
security:
- oauth2: []
tags:
- name: Statistics
  description: Playback and engagement analytics at user, show, and episode level.
paths:
  /users/{user_id}/statistics:
    parameters:
    - $ref: '#/components/parameters/UserId'
    get:
      operationId: getUserStatistics
      tags:
      - Statistics
      summary: Retrieve overall user statistics
      responses:
        '200':
          description: Aggregated statistics for the user.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /users/{user_id}/statistics/plays:
    parameters:
    - $ref: '#/components/parameters/UserId'
    get:
      operationId: getUserPlayStatistics
      tags:
      - Statistics
      summary: Retrieve user play statistics
      responses:
        '200':
          description: Play statistics for the user.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /users/{user_id}/statistics/geographics:
    parameters:
    - $ref: '#/components/parameters/UserId'
    get:
      operationId: getUserGeographicStatistics
      tags:
      - Statistics
      summary: Retrieve user geographic statistics
      responses:
        '200':
          description: Geographic distribution of plays.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /shows/{show_id}/statistics/plays:
    parameters:
    - $ref: '#/components/parameters/ShowId'
    get:
      operationId: getShowPlayStatistics
      tags:
      - Statistics
      summary: Retrieve show play statistics
      responses:
        '200':
          description: Play statistics for the show.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /episodes/{episode_id}/statistics/plays:
    parameters:
    - $ref: '#/components/parameters/EpisodeId'
    get:
      operationId: getEpisodePlayStatistics
      tags:
      - Statistics
      summary: Retrieve episode play statistics
      responses:
        '200':
          description: Play statistics for the episode.
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    Unauthorized:
      description: The request was not authenticated with a valid OAuth2 token.
  parameters:
    ShowId:
      name: show_id
      in: path
      required: true
      schema:
        type: integer
      description: The show ID.
    UserId:
      name: user_id
      in: path
      required: true
      schema:
        type: integer
      description: The user ID.
    EpisodeId:
      name: episode_id
      in: path
      required: true
      schema:
        type: integer
      description: The episode ID.
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth2. Authorize at https://www.spreaker.com/oauth2/authorize and exchange or refresh tokens at https://api.spreaker.com/oauth2/token. Access tokens are sent as a Bearer token in the Authorization header.
      flows:
        authorizationCode:
          authorizationUrl: https://www.spreaker.com/oauth2/authorize
          tokenUrl: https://api.spreaker.com/oauth2/token
          refreshUrl: https://api.spreaker.com/oauth2/token
          scopes:
            basic: Basic access to the Spreaker API on behalf of the user.