swagger: "2.0"

info:
  version: 1.0.0
  title: Orchard ows-analytics-sr Specifications

schemes:
  - https
host: qa-ows-analytics-sr.theorchard.io
paths:
  /hello:
    get:
      summary: Check the health of the application.
      responses:
        200:
          description: 200 OK
          examples:
            application/json: { "status": "ok" }
  /top-sound-recordings:
    get:
      summary: Get the top sound recordings for a label/artist
      description: Returns a list of highest streaming sound recordings (by ISRC) for a given label/artist.
      parameters:
        - $ref: '#/parameters/orchardProfileType'
        - $ref: '#/parameters/orchardProfileId'
        - $ref: '#/parameters/orchardIdentityId'
        - $ref: '#/parameters/limit'
        - $ref: '#/parameters/offset'
        - $ref: '#/parameters/countryCodes'
        - $ref: '#/parameters/orderBy'
        - $ref: '#/parameters/distributors'
      responses:
        200:
          description: 'HTTP 200 OK'
          schema:
            $ref: '#/definitions/topSoundRecordings'
        400:
          examples:
            validation_error:
              code: bad_grass_request_error
              message: 'Missing Grass Headers'
          description: Request missing required grass headers
  /sound-recording/{isrc}/metadata:
    get:
      summary: Get sound recording metadata
      description: Returns an object containing product metadata based on a provided ISRC.
      parameters:
        - $ref: '#/parameters/isrc'
        - $ref: '#/parameters/orchardProfileType'
        - $ref: '#/parameters/orchardProfileId'
        - $ref: '#/parameters/orchardIdentityId'
      responses:
        200:
          description: 'HTTP 200 OK'
          schema:
            $ref: '#/definitions/soundRecordingMetadata'
  /sound-recording/{isrc}/streams:
    get:
      summary: Get the stream data for a sound recording
      parameters:
        - $ref: '#/parameters/isrc'
        - $ref: '#/parameters/orchardProfileType'
        - $ref: '#/parameters/orchardProfileId'
        - $ref: '#/parameters/orchardIdentityId'
        - $ref: '#/parameters/storeIds'
        - $ref: '#/parameters/countryCodes'
        - $ref: '#/parameters/startDate'
        - $ref: '#/parameters/endDate'
        - $ref: '#/parameters/days'
      responses:
        200:
          description: 'HTTP 200 OK'
          schema:
            $ref: '#/definitions/soundRecordingStreams'
        400:
          examples:
            validation_error:
              code: bad_grass_request_error
              message: 'Missing Grass Headers'
          description: Request missing required grass headers
  /sound-recording/streams:
    post:
      summary: Get the stream data for a list of sound recording
      parameters:
        - $ref: '#/parameters/isrcs'
        - $ref: '#/parameters/orchardProfileType'
        - $ref: '#/parameters/orchardProfileId'
        - $ref: '#/parameters/orchardIdentityId'
        - $ref: '#/parameters/storeIds'
        - $ref: '#/parameters/countryCodes'
        - $ref: '#/parameters/startDate'
        - $ref: '#/parameters/endDate'
        - $ref: '#/parameters/days'
      responses:
        200:
          description: 'HTTP 200 OK'
          schema:
            $ref: '#/definitions/soundRecordingStreams'
        400:
          examples:
            validation_error:
              code: bad_grass_request_error
              message: 'Missing Grass Headers'
          description: Request missing required grass headers
  /sound-recording/aggregate-streams:
    post:
      summary: Get aggregate streams for a list of ISRCs
      parameters:
        - $ref: '#/parameters/isrcs'
        - $ref: '#/parameters/orchardProfileType'
        - $ref: '#/parameters/orchardProfileId'
        - $ref: '#/parameters/orchardIdentityId'
        - $ref: '#/parameters/storeIds'
        - $ref: '#/parameters/countryCodes'
      responses:
        200:
          description: 'HTTP 200 OK'
          schema:
            $ref: '#/definitions/soundRecordingAggregateStreams'
        400:
          examples:
            validation_error:
              code: bad_grass_request_error
              message: 'Missing Grass Headers'
          description: Request missing required grass headers
  /sound-recording/{isrc}/downloads:
    get:
      summary: Get the downoad data for a sound recording from the past 7 days
      parameters:
        - $ref: '#/parameters/isrc'
        - $ref: '#/parameters/orchardProfileType'
        - $ref: '#/parameters/orchardProfileId'
        - $ref: '#/parameters/orchardIdentityId'
        - $ref: '#/parameters/storeIds'
        - $ref: '#/parameters/countryCodes'
        - $ref: '#/parameters/startDate'
        - $ref: '#/parameters/endDate'
        - $ref: '#/parameters/days'
      responses:
        200:
          description: 'HTTP 200 OK'
          schema:
            $ref: '#/definitions/soundRecordingDownloads'
        400:
          examples:
            validation_error:
              code: bad_grass_request_error
              message: 'Missing Grass Headers'
          description: Request missing required grass headers
  /sound-recording/{isrc}/downloads-all:
    get:
      summary: Get the downoad data for a sound recording from the past 7 days
      parameters:
        - $ref: '#/parameters/isrc'
        - $ref: '#/parameters/orchardProfileType'
        - $ref: '#/parameters/orchardProfileId'
        - $ref: '#/parameters/orchardIdentityId'
        - $ref: '#/parameters/storeIds'
        - $ref: '#/parameters/countryCodes'
        - $ref: '#/parameters/startDate'
        - $ref: '#/parameters/endDate'
        - $ref: '#/parameters/days'
      responses:
        200:
          description: 'HTTP 200 OK'
          schema:
            $ref: '#/definitions/soundRecordingDownloadsAll'
        400:
          examples:
            validation_error:
              code: bad_grass_request_error
              message: 'Missing Grass Headers'
          description: Request missing required grass headers
  /sound-recording/{isrc}/downloads-by-store:
    get:
      summary: Get downloads data by store for sound-recording
      parameters:
        - $ref: '#/parameters/isrc'
        - $ref: '#/parameters/orchardProfileType'
        - $ref: '#/parameters/orchardProfileId'
        - $ref: '#/parameters/orchardIdentityId'
        - $ref: '#/parameters/storeIds'
        - $ref: '#/parameters/countryCodes'
        - $ref: '#/parameters/startDate'
        - $ref: '#/parameters/endDate'
      responses:
        200:
          description: 'HTTP 200 OK'
          schema:
            $ref: '#/definitions/soundRecordingDownloadsByStore'
        400:
          examples:
            validation_error:
              code: bad_grass_request_error
              message: 'Missing Grass Headers'
          description: Request missing required grass headers
  /sound-recording/{isrc}/downloads-by-product:
    get:
      summary: Get downloads timeseries data by product for sound-recording
      parameters:
        - $ref: '#/parameters/isrc'
        - $ref: '#/parameters/orchardProfileType'
        - $ref: '#/parameters/orchardProfileId'
        - $ref: '#/parameters/orchardIdentityId'
        - $ref: '#/parameters/storeIds'
        - $ref: '#/parameters/countryCodes'
        - $ref: '#/parameters/startDate'
        - $ref: '#/parameters/endDate'
      responses:
        200:
          description: 'HTTP 200 OK'
          schema:
            $ref: '#/definitions/soundRecordingDownloadsByProduct'
        400:
          examples:
            validation_error:
              code: bad_grass_request_error
              message: 'Missing Grass Headers'
          description: Request missing required grass headers
  /sound-recording/{isrc}/downloads-by-country:
    get:
      summary: Get downloads data by country for sound-recording
      parameters:
        - $ref: '#/parameters/isrc'
        - $ref: '#/parameters/orchardProfileType'
        - $ref: '#/parameters/orchardProfileId'
        - $ref: '#/parameters/orchardIdentityId'
        - $ref: '#/parameters/storeIds'
        - $ref: '#/parameters/countryCodes'
        - $ref: '#/parameters/startDate'
        - $ref: '#/parameters/endDate'
      responses:
        200:
          description: 'HTTP 200 OK'
          schema:
            $ref: '#/definitions/soundRecordingDownloadsByCountry'
        400:
          examples:
            validation_error:
              code: bad_grass_request_error
              message: 'Missing Grass Headers'
          description: Request missing required grass headers
  /sound-recording/{isrc}/source-of-streams:
    get:
      summary: Get the source breakdown for a sound recording
      parameters:
        - $ref: '#/parameters/isrc'
        - $ref: '#/parameters/orchardProfileType'
        - $ref: '#/parameters/orchardProfileId'
        - $ref: '#/parameters/orchardIdentityId'
        - $ref: '#/parameters/storeIds'
        - $ref: '#/parameters/countryCodes'
        - $ref: '#/parameters/startDate'
        - $ref: '#/parameters/endDate'
        - $ref: '#/parameters/days'
      responses:
        200:
          description: 'HTTP 200 OK'
          schema:
            $ref: '#/definitions/sourceOfStreams'
        400:
          examples:
            validation_error:
              code: bad_grass_request_error
              message: 'Missing Grass Headers'
          description: Request missing required grass headers
  /sound-recording/{isrc}/top-markets:
    get:
      summary: Get top markets information for a sound recording
      parameters:
        - $ref: '#/parameters/isrc'
        - $ref: '#/parameters/orchardProfileType'
        - $ref: '#/parameters/orchardProfileId'
        - $ref: '#/parameters/orchardIdentityId'
        - $ref: '#/parameters/storeIds'
      responses:
        200:
          description: 'HTTP 200 OK'
          schema:
            $ref: '#/definitions/topMarkets'
        400:
          examples:
            validation_error:
              code: bad_grass_request_error
              message: 'Missing Grass Headers'
          description: Request missing required grass headers
  /sound-recording/{isrc}/placements:
    get:
      summary: Get playlist placements information for a sound recording
      parameters:
        - $ref: '#/parameters/isrc'
        - $ref: '#/parameters/orchardProfileType'
        - $ref: '#/parameters/orchardProfileId'
        - $ref: '#/parameters/orchardIdentityId'
        - $ref: '#/parameters/ownerCategories'
        - $ref: '#/parameters/storeIds'
      responses:
        200:
          description: 'HTTP 200 OK'
          schema:
            $ref: '#/definitions/placements'
  /sound-recording/{isrc}/placement/{playlistId}:
    get:
      summary: Get a playlist placement
      parameters:
        - $ref: '#/parameters/isrc'
        - $ref: '#/parameters/playlistId'
        - $ref: '#/parameters/orchardProfileType'
        - $ref: '#/parameters/orchardProfileId'
        - $ref: '#/parameters/orchardIdentityId'
      responses:
        200:
          description: 'HTTP 200 OK'
          schema:
            $ref: '#/definitions/playlistPlacement'
  /sound-recording/{isrc}/playlists:
    get:
      summary: Get playlist streaming data for a sound recording
      parameters:
        - $ref: '#/parameters/isrc'
        - $ref: '#/parameters/orchardProfileType'
        - $ref: '#/parameters/orchardProfileId'
        - $ref: '#/parameters/orchardIdentityId'
        - $ref: '#/parameters/ownerCategories'
        - $ref: '#/parameters/storeIds'
        - $ref: '#/parameters/countryCodes'
        - $ref: '#/parameters/startDate'
        - $ref: '#/parameters/endDate'
        - $ref: '#/parameters/days'
      responses:
        200:
          description: 'HTTP 200 OK'
          schema:
            $ref: '#/definitions/playlists'
  /sound-recording/{isrc}/demographics:
    get:
      summary: Get demographics summary for a sound recording
      parameters:
        - $ref: '#/parameters/isrc'
        - $ref: '#/parameters/orchardProfileType'
        - $ref: '#/parameters/orchardProfileId'
        - $ref: '#/parameters/orchardIdentityId'
        - $ref: '#/parameters/ownerCategories'
        - $ref: '#/parameters/storeIds'
        - $ref: '#/parameters/countryCodes'
        - $ref: '#/parameters/startDate'
        - $ref: '#/parameters/endDate'
        - $ref: '#/parameters/days'
      responses:
        200:
          description: 'HTTP 200 OK'
          schema:
            $ref: '#/definitions/demographics'
  /sound-recording/{isrc}/top-countries-streams:
    get:
      summary: Get top streaming countries for a sound recording
      parameters:
        - $ref: '#/parameters/isrc'
        - $ref: '#/parameters/orchardProfileType'
        - $ref: '#/parameters/orchardProfileId'
        - $ref: '#/parameters/orchardIdentityId'
        - $ref: '#/parameters/ownerCategories'
        - $ref: '#/parameters/storeIds'
        - $ref: '#/parameters/startDate'
        - $ref: '#/parameters/endDate'
        - $ref: '#/parameters/days'
      responses:
        200:
          description: 'HTTP 200 OK'
          schema:
            $ref: '#/definitions/topCountriesStreams'
  /sound-recording/{isrc}/top-countries-downloads:
    get:
      summary: Get top download countries for a sound recording
      parameters:
        - $ref: '#/parameters/isrc'
        - $ref: '#/parameters/orchardProfileType'
        - $ref: '#/parameters/orchardProfileId'
        - $ref: '#/parameters/orchardIdentityId'
        - $ref: '#/parameters/ownerCategories'
        - $ref: '#/parameters/storeIds'
        - $ref: '#/parameters/startDate'
        - $ref: '#/parameters/endDate'
        - $ref: '#/parameters/days'
      responses:
        200:
          description: 'HTTP 200 OK'
          schema:
            $ref: '#/definitions/topCountriesDownloads'
  /sound-recording/{isrc}/streams-breakdown:
    get:
      summary: Get subscription data for a sound recording
      description: Returns an object containing subscription information based on a provided ISRC.
      parameters:
        - $ref: '#/parameters/isrc'
        - $ref: '#/parameters/orchardProfileType'
        - $ref: '#/parameters/orchardProfileId'
        - $ref: '#/parameters/orchardIdentityId'
        - $ref: '#/parameters/storeIds'
        - $ref: '#/parameters/countryCodes'
        - $ref: '#/parameters/startDate'
        - $ref: '#/parameters/endDate'
        - $ref: '#/parameters/days'
      responses:
        200:
          description: 'HTTP 200 OK'
          schema:
            $ref: '#/definitions/streamsBreakdown'
        400:
          examples:
            validation_error:
              code: bad_grass_request_error
              message: 'Missing Grass Headers'
          description: Request missing required grass headers
  /sound-recording/{isrc}/streams-by-country:
    get:
      summary: Get timeseries data by country for sound-recording
      parameters:
        - $ref: '#/parameters/isrc'
        - $ref: '#/parameters/orchardProfileType'
        - $ref: '#/parameters/orchardProfileId'
        - $ref: '#/parameters/orchardIdentityId'
        - $ref: '#/parameters/storeIds'
        - $ref: '#/parameters/countryCodes'
        - $ref: '#/parameters/startDate'
        - $ref: '#/parameters/endDate'
      responses:
        200:
          description: 'HTTP 200 OK'
          schema:
            $ref: '#/definitions/streamsByCountry'
        400:
          examples:
            validation_error:
              code: bad_grass_request_error
              message: 'Missing Grass Headers'
          description: Request missing required grass headers
  /sound-recording/{isrc}/streams-by-store:
    get:
      summary: Get timeseries data by store for sound-recording
      parameters:
        - $ref: '#/parameters/isrc'
        - $ref: '#/parameters/orchardProfileType'
        - $ref: '#/parameters/orchardProfileId'
        - $ref: '#/parameters/orchardIdentityId'
        - $ref: '#/parameters/storeIds'
        - $ref: '#/parameters/countryCodes'
        - $ref: '#/parameters/startDate'
        - $ref: '#/parameters/endDate'
      responses:
        200:
          description: 'HTTP 200 OK'
          schema:
            $ref: '#/definitions/streamsByStore'
        400:
          examples:
            validation_error:
              code: bad_grass_request_error
              message: 'Missing Grass Headers'
          description: Request missing required grass headers
  /sound-recording/{isrc}/streams-by-sos:
    get:
      summary: Get timeseries data by source of streams for sound-recording
      parameters:
        - $ref: '#/parameters/isrc'
        - $ref: '#/parameters/orchardProfileType'
        - $ref: '#/parameters/orchardProfileId'
        - $ref: '#/parameters/orchardIdentityId'
        - $ref: '#/parameters/storeIds'
        - $ref: '#/parameters/countryCodes'
        - $ref: '#/parameters/startDate'
        - $ref: '#/parameters/endDate'
      responses:
        200:
          description: 'HTTP 200 OK'
          schema:
            $ref: '#/definitions/streamsBySos'
        400:
          examples:
            validation_error:
              code: bad_grass_request_error
              message: 'Missing Grass Headers'
          description: Request missing required grass headers
  /sound-recording/{isrc}/streams-all:
    get:
      summary: Get timeseries streams data for sound-recording
      parameters:
        - $ref: '#/parameters/isrc'
        - $ref: '#/parameters/orchardProfileType'
        - $ref: '#/parameters/orchardProfileId'
        - $ref: '#/parameters/orchardIdentityId'
        - $ref: '#/parameters/storeIds'
        - $ref: '#/parameters/countryCodes'
        - $ref: '#/parameters/startDate'
        - $ref: '#/parameters/endDate'
      responses:
        200:
          description: 'HTTP 200 OK'
          schema:
            $ref: '#/definitions/streamsAll'
        400:
          examples:
            validation_error:
              code: bad_grass_request_error
              message: 'Missing Grass Headers'
          description: Request missing required grass headers
definitions:
  productId:
    type: string
    example: '1486533'
    description: Unique identifier for a product, release_id in releases table
  labelId:
    type: number
    example: 1486533
    description: Unique identifier for a label
  subaccountId:
    type: number
    example: 32312
    description: Unique identifier for a subaccount
  upc:
    type: string
    example: '886443663534'
    description: Universal Product Code, display_upc in releases table
  isrc:
    type: string
    example: 'US53Q1200099'
    description: International Standard Recording Code
  isrcs:
    type: array
    description: International Standard Recording Code
    items:
      type: string
  releaseDate:
    type: string
    description: Release date for the product in YYYY-MM-DD format.
    example: '2018-09-11T00:00:00Z'
  streams:
    type: integer
    example: 2430
    description: Total number of streams for this sound recording
  downloads:
    type: integer
    example: 243
    description: Total number of downloads for this sound recording
  views:
    type: integer
    example: 1000
    description: Views for this channel
  growthPercentage:
    type: number
    example: 12.4
    description: (current streams - past streams) / past streams
  skipRate:
    type: number
    example: 0.5
    description: (skips / (skips + streams_with_skips))
  saves:
    type: integer
    example: 0.5
    description: Number of saves for this sound-recording
  allTime:
    type: integer
    example: 12345
    description: number of streams all the way back
  totalPlaylistStreams:
    type: integer
    example: 12345
    description: number of streams of all playlists
  imageLocation:
    type: string
    example: 'https://images.theorchard.io/product/large_cover/49c461c020422c4ab37860bd29e27c64.jpg'
    description: Url for serving image via orchard images server
  soundRecordingName:
    type: string
    example: 'Frozen Pines'
    description: Title of the track
  artistName:
    type: string
    example: 'Lord Huron'
    description: Primary artist for most recent product relating to the track
  dailyStreams:
    type: array
    description: An array containing daily streams for a period of time
    items:
      type: object
      description: An object describing the number of streams for a given day
      properties:
        date:
          type: string
          example: '2018-06-22T00:00:00Z'
        streams:
          type: integer
          example: 232
  dailyDownloads:
    type: array
    description: An array containing daily streams for a period of time
    items:
      type: object
      description: An object describing the number of streams for a given day
      properties:
        date:
          type: string
          example: '2018-06-22T00:00:00Z'
        downloads:
          type: integer
          example: 23
  sourceError:
    type: object
    description: An object representing an error with a source's data
    properties:
      code:
        type: string
        description: A known code to describe the type of error that occurred (this can be i18n'd on the frontend)
        enum: [unreliable]
      types:
        type: array
        items:
          type: string
          enum:
            - streams
            - skips_saves
        description: The types of outage that occurred
      message:
        type: string
        example: Data for this source is unavailable due to GDPR compliance complications.
        description: A server-specified error message to be shown on the frontend if an enumerated code is not applicable (this cannot be i18n'd on the frontend)
  streamsTimeseries:
    type: array
    description: An array of objects containing stream, saves & skips timeseries data.
    items:
      type: object
      properties:
        date:
          type: string
          example: '2020-01-20T00:00:00Z'
        streams:
          $ref: '#/definitions/streams'
        skip_rate:
          $ref: '#/definitions/skipRate'
        saves:
          $ref: '#/definitions/saves'
  source:
    type: object
    description: Store ID, name, and potentially an error
    properties:
      id:
        type: integer
        example: 1
        description: Unique identifier for a store
      name:
        type: string
        example: 'Spotify'
        description: The name of a store
  sourceWithError:
    type: object
    properties:
      id:
        type: integer
        example: 1
        description: Unique identifier for a store
      name:
        type: string
        example: 'Spotify'
        description: The name of a store
      error:
        $ref: '#/definitions/sourceError'
  sources:
    type: array
    description: Array of sources providing related data
    items:
      $ref: '#/definitions/sourceWithError'
  sourceBreakdown:
    type: object
    description: Breakdown of stream source by streams, percentage, and percent growth
    properties:
      total:
        type: integer
        description: Number of streams from source
        example: 60000
      value:
        type: number
        description: Percent of overall streams due to source
        example: 0.3333
      growth_percentage:
        type: number
        description: Growth of percent compared to last week
        example: 0.052
  topSoundRecordings:
    type: object
    properties:
      items:
        type: object
        properties:
          isrc:
            $ref: '#/definitions/isrc'
          streams:
            $ref: '#/definitions/streams'
          growth_percentage:
            $ref: '#/definitions/growthPercentage'
      sources:
        $ref: '#/definitions/sources'
  soundRecordingProductMetadata:
    type: object
    properties:
      product_id:
        type: string
        example: '192562490839'
      upc:
        type: string
        example: '192562490837'
      product_name:
        type: string
        example: 'Landscape'
      format:
        type: string
        enum: ['lp']
      version:
        type: string
        description: Text which differentiates this product from other, similar products.
        example: 'Deluxe'
      image_location:
        $ref: '#/definitions/imageLocation'
      release_date:
        $ref: '#/definitions/releaseDate'
      sale_start_date:
        type: string
        description: Sales date for the product in YYYY-MM-DD format.
        example: '2018-09-11T00:00:00Z'
      subaccount_name:
        type: string
        description: The name of the subaccount associated with the product.
        example: 'Frenchkiss Records'
      subaccount_id:
        type: string
        description: The ID of the subaccount associated with the product.
        example: '192562'
      primary_artists:
        type: array
        items:
          $ref: '#/definitions/artistMetadata'
  soundRecordingMetadata:
    type: object
    properties:
      label_id:
        $ref: '#/definitions/labelId'
      subaccount_id:
        $ref: '#/definitions/subaccountId'
      image_location:
        $ref: '#/definitions/imageLocation'
      isrc:
        $ref: '#/definitions/isrc'
      name:
        $ref: '#/definitions/soundRecordingName'
      artist_name:
        $ref: '#/definitions/artistName'
      products:
        type: array
        items:
          $ref: '#/definitions/soundRecordingProductMetadata'
      primary_artists:
        type: array
        items:
          $ref: '#/definitions/artistMetadata'
      version:
        type: string
        example: 'Album Version'
        description: Version of the track
  artistMetadata:
    type: object
    properties:
      artist_name:
        $ref: '#/definitions/artistName'
      type:
        type: string
        example: 'performer'
        description: Artist type 'performer' or 'featuring'
  playlistTracks:
    type: object
    description: An object containing information about tracks related to a playlist.
    properties:
      length:
        type: number
        description: The number of tracks in the playlist
        example: 200
  playlist:
    type: object
    properties:
      source:
        $ref: '#/definitions/source'
      id:
        type: string
        example: 1sPA314hOnCqtZswABdD2z
      uri:
        type: string
        description: The URI of the playlist
        example: 'spotify:playlist:1sPA314hOnCqtZswABdD2z'
      name:
        type: string
        example: Urban Outfitters | Women in Music
      image_location:
        $ref: '#/definitions/imageLocation'
      country:
        type: string
        description: Country associated with the playlist
        example: 'us'
      storefront:
        type: string
        description: The storefront identifier for the playlist
        example: 'us'
      tracks:
        $ref: '#/definitions/playlistTracks'
      followers:
        type: number
        description: The number of followers of the playlist
        example: 234001
      user_display_name:
        type: string
        description: The display user name (full name) of that playlist's author
        example: 'Daniel Ek'
  playlistPlacement:
    type: object
    properties:
      isrc:
        $ref: '#/definitions/isrc'
      position:
        type: number
        description: The position of the provided ISRC on the playlist
        example: 200
      previous_position:
        type: number
        description: The previous position of the provided ISRC on the playlist
        example: 201
      streams:
        type: number
        description: The number of streams for the ISRC on the playlist
        example: 12324
      added:
        type: string
        description: The date on which the ISRC was added to the playlist
        example: '2018-06-22T00:00:00Z'
      playlist:
        $ref: '#/definitions/playlist'
  sourceOfStreams:
    type: object
    properties:
      isrc:
        $ref: '#/definitions/isrc'
      active:
        description: Statistics for active streams
        $ref: '#/definitions/sourceBreakdown'
      passive:
        description: Statistics for passive streams
        $ref: '#/definitions/sourceBreakdown'
      collection:
        description: Statistics for collection streams
        $ref: '#/definitions/sourceBreakdown'
      sources:
        $ref: '#/definitions/sources'
  soundRecordingStreams:
    type: object
    properties:
      isrc:
        $ref: '#/definitions/isrc'
      aggregate:
        type: object
        description: An object representing the aggregate of streaming information for the
        properties:
          growth_percentage:
            $ref: '#/definitions/growthPercentage'
          all_time:
            $ref: '#/definitions/allTime'
          items:
            $ref: '#/definitions/dailyStreams'
      stores:
        type: array
        description: Array of stores with daily store information
        items:
          type: object
          description: Description of a store with its daily streams
          properties:
            id:
              type: integer
              example: 1
              description: Unique identifier for a store
            name:
              type: string
              example: 'Spotify'
              description: The name of a store
            growth_percentage:
              $ref: '#/definitions/growthPercentage'
            all_time:
              $ref: '#/definitions/allTime'
            items:
              $ref: '#/definitions/dailyStreams'
      sources:
        $ref: '#/definitions/sources'
  soundRecordingAggregateStreams:
    type: object
    properties:
      isrc:
        type: object
        description: An object representing aggregate streams info for the ISRC
        properties:
            growth_percentage_7_days:
              $ref: '#/definitions/growthPercentage'
            streams_all_time:
              $ref: '#/definitions/allTime'
  soundRecordingDownloads:
    type: object
    properties:
      isrc:
        $ref: '#/definitions/isrc'
      aggregate:
        type: object
        description: An object representing the aggregate of streaming information for the
        properties:
          items:
            $ref: '#/definitions/dailyDownloads'
      stores:
        type: array
        description: Array of stores with daily stream information
        items:
          type: object
          description: Description of a store with its daily streams
          properties:
            id:
              type: integer
              example: 1
              description: Unique identifier for a store
            name:
              type: string
              example: 'Apple Music'
              description: The name of a store
            items:
              $ref: '#/definitions/dailyDownloads'
      sources:
        $ref: '#/definitions/sources'
  soundRecordingDownloadsAll:
    type: object
    properties:
      isrc:
        $ref: '#/definitions/isrc'
      items:
        $ref: '#/definitions/dailyDownloads'
  soundRecordingDownloadsByStore:
    type: object
    properties:
      isrc:
        $ref: '#/definitions/isrc'
      stores:
        type: array
        description: Array of stores with daily stream information
        items:
          type: object
          description: Description of a store with its daily streams
          properties:
            id:
              type: integer
              example: 1
              description: Unique identifier for a store
            name:
              type: string
              example: 'Apple Music'
              description: The name of a store
            items:
              $ref: '#/definitions/dailyDownloads'
  soundRecordingDownloadsByProduct:
    type: object
    properties:
      isrc:
        $ref: '#/definitions/isrc'
      products:
        type: array
        description: Array of stores with daily stream information
        items:
          type: object
          description: Description of a product with its daily streams
          properties:
            product_id:
              $ref: '#/definitions/productId'
            items:
              $ref: '#/definitions/dailyDownloads'
  soundRecordingDownloadsByCountry:
    type: object
    properties:
      isrc:
        $ref: '#/definitions/isrc'
      countries:
        type: array
        description: Array of countries with daily stream information
        items:
          type: object
          description: Description of a country with its daily streams
          properties:
            code:
              type: string
              example: 'GB'
              description: Unique identifier for a country
            items:
              $ref: '#/definitions/dailyDownloads'
  topMarkets:
    type: object
    properties:
      isrc:
        $ref: '#/definitions/isrc'
      items:
        type: array
        description: Array of top markets containing streaming performance by region
        items:
          type: object
          description: Top market streaming performance
          properties:
            country_code:
              type: string
              example: 'US'
              description: The ISO country code in which the top market is located
            region:
              type: string
              example: 'Brooklyn'
              description: The region for the top market
            streams:
              $ref: '#/definitions/streams'
            growth_percentage:
              $ref: '#/definitions/growthPercentage'
      sources:
        $ref: '#/definitions/sources'
  placements:
    type: object
    properties:
      isrc:
        $ref: '#/definitions/isrc'
      items:
        type: array
        items:
          $ref: '#/definitions/playlistPlacement'
      sources:
        $ref: '#/definitions/sources'
  playlists:
    type: object
    properties:
      isrc:
        $ref: '#/definitions/isrc'
      total_playlist_streams:
        $ref: '#/definitions/totalPlaylistStreams'
      items:
        type: array
        items:
          type: object
          properties:
            playlist_id:
              type: string
              example: 2591869068
            playlist_url:
              type: string
              description: The URI of the playlist
              example: 'spotify:playlist:1sPA314hOnCqtZswABdD2z'
            playlist_name:
              type: string
              example: Urban Outfitters | Women in Music
            playlist_image:
              $ref: '#/definitions/imageLocation'
            streams:
              $ref: '#/definitions/streams'
            store_id:
              type: integer
              example: 286
      sources:
        $ref: '#/definitions/sources'
  demographics:
    type: object
    properties:
      isrc:
        $ref: '#/definitions/isrc'
      demographics:
        type: array
        items:
          type: object
          properties:
            gender:
              type: object
              properties:
                F:
                  type: integer
                  example: 43
                M:
                  type: integer
                  example: 42
                UG:
                  type: integer
                  example: 5
            age:
              type: object
              properties:
                _17:
                  type: integer
                  example: 32
                _18_22:
                  type: integer
                  example: 51
                _23_27:
                  type: integer
                  example: 76
                _28_34:
                  type: integer
                  example: 50
                _35_44:
                  type: integer
                  example: 30
                _45_59:
                  type: integer
                  example: 15
                _60_:
                  type: integer
                  example: 10
                UA:
                  type: integer
                  example: 4
            store_id:
              type: integer
              example: 286
      sources:
        $ref: '#/definitions/sources'
  topCountriesStreams:
    type: object
    properties:
      isrc:
        $ref: '#/definitions/isrc'
      top_countries:
        type: array
        items:
          type: object
          properties:
            streams:
              type: integer
              example: 43
            country_code:
              type: string
              example: 'US'
      sources:
        $ref: '#/definitions/sources'
  topCountriesDownloads:
    type: object
    properties:
      isrc:
        $ref: '#/definitions/isrc'
      top_countries:
        type: array
        items:
          type: object
          properties:
            gender:
              type: object
              properties:
                downloads:
                  type: integer
                  example: 43
                country_code:
                  type: string
                  example: 'US'
      sources:
        $ref: '#/definitions/sources'
  streamsBreakdown:
    type: object
    properties:
      isrc:
        $ref: '#/definitions/isrc'
      source_of_streams:
        type: array
        items:
          type: object
          description: Breakdown of source of streams
          properties:
            active:
              description: Statistics for active streams
              $ref: '#/definitions/sourceBreakdown'
            passive:
              description: Statistics for passive streams
              $ref: '#/definitions/sourceBreakdown'
            collection:
              description: Statistics for collection streams
              $ref: '#/definitions/sourceBreakdown'
            unknown:
              description: Statistics for unknown streams
              $ref: '#/definitions/sourceBreakdown'
            sources:
              $ref: '#/definitions/sources'
      streams_by_subscription:
        type: array
        items:
          type: object
          description: Breakdown of subscription type
          properties:
            subscription:
              description: Statistics for subscriptions
              $ref: '#/definitions/sourceBreakdown'
            ad_supported:
              description: Statistics for ad supported subscriptions
              $ref: '#/definitions/sourceBreakdown'
            mid_tier:
              description: Statistics for mid-tier subscriptions
              $ref: '#/definitions/sourceBreakdown'
            sources:
              $ref: '#/definitions/sources'
  streamsByCountry:
    type: object
    properties:
      isrc:
        $ref: '#/definitions/isrc'
      countries:
        type: array
        items:
          type: object
          properties:
            country_code:
              type: string
              example: 'US'
            items:
              $ref: '#/definitions/streamsTimeseries'
  streamsByStore:
    type: object
    properties:
      isrc:
        $ref: '#/definitions/isrc'
      stores:
        type: array
        items:
          type: object
          properties:
            id:
              type: integer
              example: 1
            name:
              type: string
              example: 'Apple Music'
            items:
              $ref: '#/definitions/streamsTimeseries'
  streamsBySos:
    type: object
    properties:
      isrc:
        $ref: '#/definitions/isrc'
      source_of_streams:
        type: array
        items:
          type: object
          properties:
            source:
              type: string
              example: 'active'
            items:
              type: array
              items:
                type: object
                properties:
                  date:
                    type: string
                    example: '2020-01-20T00:00:00Z'
                  streams:
                    $ref: '#/definitions/streams'
  streamsAll:
    type: object
    properties:
      isrc:
        $ref: '#/definitions/isrc'
      items:
        type: array
        items:
          $ref: '#/definitions/streamsTimeseries'
  streams_1_day:
    type: number
    description: The number of streams over the past 24 hours
    example: 33
  growth_percentage_1_day:
    type: number
    example: 12.4
    description: (current 1 day streams - past 1 day streams) / past 1 day streams
  streams_7_days:
    type: number
    description: The number of streams over the past 7 days
    example: 50
  growth_percentage_7_days:
    type: number
    example: 12.4
    description: (current 7 day streams - past 7 day streams) / past 7 day streams
  streams_28_days:
    type: number
    description: The number of streams over the past 28 days
    example: 200
  growth_percentage_28_days:
    type: number
    example: 12.4
    description: (current 28 day streams - past 28 day streams) / past 28 day streams
  streams_all_time:
      type: number
      description: The number of all time streams
      example: 1000
parameters:
  grassAccountId:
    name: Grass-Account-Id
    description: Grass account id. Provided by ows-grass proxy in QA/Prod.
    in: header
    pattern: ^\d+$
    type: string
    required: true
  grassAccountType:
    name: Grass-Account-Type
    description: Grass account type. Provided by ows-grass proxy in QA/Prod.
    enum:
      - vendor
      - subaccount
    in: header
    type: string
    required: true
  orchardProfileType:
    name: Orchard-Profile-Type
    description: Orchard profile type. Provided by ows-grass proxy in QA/Prod.
    in: header
    type: string
    required: true
    enum:
      - ArtistProfile
      - LabelProfile
  orchardProfileId:
    name: Orchard-Profile-Id
    description: Orchard profile id. Provided by ows-grass proxy in QA/Prod.
    in: header
    type: integer
    required: true
  orchardIdentityId:
    name: Orchard-Identity-Id
    description: Orchard identity id. Provided by ows-grass proxy in QA/Prod.
    in: header
    type: string
    required: true
  productId:
    name: productId
    description: Uniquely identifies a product
    type: string
    required: true
    in: path
  isrc:
    in: path
    name: isrc
    description: Industry Standard Recording Code
    type: string
    required: true
  isrcs:
    in: body
    name: isrcs
    description: List of Industry Standard Recording Code
    required: true
    schema:
      $ref: '#/definitions/isrcs'
  playlistId:
    name: playlistId
    description: Uniquely identifies a playlist
    type: string
    required: true
    in: path
  searchTerm:
    in: query
    name: term
    description: String to be used in search
    type: string
    required: true
  storeIds:
    in: query
    name: store_id
    description: Store id values used for global filters
    type: integer
    enum: [1, 286]
  labelIds:
    in: query
    name: label_ids
    description: Label ids to filter by
    type: integer
    enum: [1, 286]
  subaccountIds:
    in: query
    name: subaccount_ids
    description: Sub-account ids to filter by
    type: integer
    enum: [1, 286]
  countryCodes:
    in: query
    name: country_code
    description: Country code values used for global filters
    type: string
    enum: ['US', 'NO', 'DE']
  startDate:
    in: query
    name: start_date
    description: Start date used for global filters
    type: string
    format: '%Y-%m-%d/HIGHWATERMARK_DATE'
  endDate:
    in: query
    name: end_date
    description: Start date used for global filters
    type: string
    format: '%Y-%m-%d'
  days:
    in: query
    name: days
    description: Days back used for global filters
    type: integer
  orderBy:
    in: query
    name: order_by
    description: order by column provided
    type: string
  orderDir:
    in: query
    name: order_dir
    description: order direction provided
    type: string
  ownerCategories:
    in: query
    name: owner_category
    description: Owner category values used for filtering placements
    type: string
    enum: ['CURATOR', 'EDITORIAL', 'USER_GENERATED']
  offset:
    in: query
    name: offset
    type: integer
    description: The number of items to skip before starting to collect the result set
  limit:
    in: query
    name: limit
    type: integer
    description: The numbers of items to return
  distributors:
    in: query
    name: distributors
    type: string
    description: The distributor of a track
  artistIds:
    in: query
    name: artist_ids
    type: string
    description: The global participant ID to do artist filtering
    enum: ['f67b0892-f0bc-4575-b23e-59566ccb44bc']
  globalParticipantIds:
    in: query
    name: global_participant_ids
    type: string
    description: The global participant ID for artist filtering
    enum: ['f67b0892-f0bc-4575-b23e-59566ccb44bc']
  globalParticipantId:
    in: path
    name: global_participant_id
    type: string
    description: The global participant ID for artist filtering
    required: true
  upc:
    in: path
    name: upc
    type: string
    description: If UPC to do product filtering
    required: true
  type:
    name: type
    description: Type for which to get the highwatermark date (videos, downloads, streams)
    type: string
    required: true
    in: query