swagger: "2.0"
info:
  description: "https://github.com/filtr/dsp-api"
  version: "1.0.0"
  title: "DSP API"
host: "127.0.0.1:8000"
basePath: "/api"
schemes:
- "http"
securityDefinitions:
  apiKey:
    type: apiKey
    in: "header"
    name: "Authorization"
    description: "Service API key"
security:
  - apiKey: []
parameters:
  amazon_playlist_id:
    description: Amazon playlist ID
    in: query
    name: playlist_id
    required: true
    type: string
  amazon_playlist_id_array:
    description: Amazon playlist ID (array)
    in: query
    name: playlist_id
    required: true
    type: array
    items:
      type: string
  country_code:
    description: Typically a lower-case two letter code for the country
    in: query
    name: country_code
    required: false
    type: string
  end_date:
    description: The latest date to consider in the query
    in: query
    name: end_date
    required: true
    format: date
    pattern: '^\d{4}-\d{2}-\d{2}$'
    type: string
  group_by:
    description: Specific term to group the data by. Currently only `date` (day) is supported.
    in: query
    name: group_by
    required: false
    type: string
  isrc_array:
    description: International Standard Recording Code (ISRC) number (array)
    in: query
    name: isrc
    required: true
    items:
      type: string
    type: array
  limit:
    description: The maximum number of `items` to return in a single request.
    in: query
    name: limit
    format: int32
    maximum: 1000
    minimum: 0
    type: integer
  offset:
    description: The number of `items` to offset for pagination.
    in: query
    name: offset
    format: int32
    minimum: 0
    type: integer
  start_date:
    description: The earliest date to consider in the query
    in: query
    name: start_date
    required: true
    format: date
    pattern: '^\d{4}-\d{2}-\d{2}$'
    type: string
paths:
  /apple/tracks/{track_id}:
    get:
      summary: "Get track details"
      produces:
        - "application/json"
      parameters:
        - in: "path"
          name: "track_id"
          description: "Track ID"
          required: true
          type: "integer"
          format: "int64"
        - in: "query"
          name: "market"
          description: "Market code"
          type: "string"
        - in: "query"
          name: "include"
          description: "Include references"
          type: "array"
          items:
            type: "string"
      responses:
        200:
          description: "Track details."
  /apple/tracks:
    get:
      summary: "Returns info about tracks."
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: "ids"
          type: "integer"
          description: "List of ID"
        - in: "query"
          name: "isrc"
          type: "string"
          description: "List of ISRC"
        - in: "query"
          name: "market"
          type: "string"
          default: "us"
          description: "Market"
        - in: "query"
          name: "include"
          description: "Include references"
          type: "array"
          items:
            type: "string"
      responses:
        200:
          description: "List of tracks with details."
  /apple/tracks-images:
    post:
      summary: "Returns track images urls."
      parameters:
      - in: "body"
        name: "body"
        required: true
        schema:
          type: object
          properties:
            ids:
              type: array
              items:
                type: string
            isrc:
              type: array
              items:
                type: string
            market:
              type: string
            image_size:
              type: integer
      responses:
        200:
          description: "List of tracks images id and url data."
  /apple/playlists/{playlist_id}:
    get:
      summary: "Get track details"
      produces:
        - "application/json"
      parameters:
        - in: "path"
          name: "playlist_id"
          description: "Playlist ID"
          required: true
          type: "integer"
          format: "int64"
        - in: "query"
          name: "market"
          description: "Market code"
          type: "string"
        - in: "query"
          name: "include"
          description: "Include references"
          type: "array"
          items:
            type: "string"
      responses:
        200:
          description: "Playlist details."
  /apple/playlists:
    get:
      summary: "Returns info about playlists."
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: "ids"
          type: "integer"
          required: true
          description: "List of ID"
        - in: "query"
          name: "market"
          type: "string"
          default: "us"
          description: "Market"
        - in: "query"
          name: "include"
          description: "Include references"
          type: "array"
          items:
            type: "string"
      responses:
        200:
          description: "List of tracks with details."
  /apple/playlists-images:
    post:
      summary: "Returns playlist images urls."
      parameters:
      - in: "body"
        name: "body"
        required: true
        schema:
          type: object
          properties:
            ids:
              type: array
              items:
                type: string
            market:
              type: string
            image_size:
              type: integer
      responses:
        200:
          description: "List of playlist images id and url data."
  /apple/albums/{album_id}:
    get:
      summary: "Get album details."
      produces:
        - "application/json"
      parameters:
        - in: "path"
          name: "album_id"
          description: "Album ID"
          required: true
          type: "string"
        - in: "query"
          name: "market"
          type: "string"
          default: "us"
          description: "Market"
        - in: "query"
          name: "include"
          description: "Include references"
          type: "array"
          items:
            type: "string"
      responses:
        200:
          description: "Album details."
  /apple/albums:
    get:
      summary: "Returns info about albums."
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: "ids"
          type: "integer"
          required: true
          description: "List of ID"
        - in: "query"
          name: "market"
          type: "string"
          default: "us"
          description: "Market"
        - in: "query"
          name: "include"
          description: "Include references"
          type: "array"
          items:
            type: "string"
      responses:
        200:
          description: "List of albums with details."
  /apple/search:
    get:
      summary: "Search some objects in apple API."
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: "query"
          type: "string"
          required: true
          description: "Search term"
        - in: "query"
          name: "market"
          type: "string"
          default: "us"
          description: "Market"
        - in: "query"
          name: "item_type"
          description: "List of requested types"
          type: "array"
          collectionFormat: multi
          default: ["songs"]
          items:
            type: "string"
            enum: ["songs", "albums", "artists", "playlists"]
        - in: "query"
          name: "offset"
          type: "integer"
          description: "Page offset"
        - in: "query"
          name: "limit"
          type: "integer"
          maximum: 25
          description: "Page limit"
      responses:
        200:
          description: "List of objects data."

  /auth/check-session:
    get:
      summary: "Returns info about user's authorization."
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: "t"
          type: "integer"
          description: "Optional timestamp of datetime to check"
      responses:
        200:
          description: "User's authorization data."
          schema:
            type: "object"
            required: [ "need_authorize", "updated_at" ]
            properties:
              need_authorize:
                type: "boolean"
              updated_at:
                type: "integer"
              details:
                type: "string"

  /spotify/tracks/{track_id}:
    get:
      summary: "Get track details"
      produces:
        - "application/json"
      parameters:
        - in: "path"
          name: "track_id"
          description: "Track ID"
          required: true
          type: "string"
        - in: "query"
          name: "market"
          type: "string"
          default: "global"
          description: "Market"
      responses:
        200:
          description: "Track details."
  /spotify/tracks:
    get:
      summary: "Returns info about tracks by list of ID/URI/ISRC."
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: "ids"
          description: "List of ID"
          type: "array"
          items:
            type: "string"
        - in: "query"
          name: "isrc"
          description: "List of ISRC"
          type: "array"
          items:
            type: "string"
        - in: "query"
          name: "market"
          type: "string"
          default: "global"
          description: "Market"
      responses:
        200:
          description: "List of tracks with details."
  /spotify/artists/{artist_id}:
    get:
      summary: "Get artist details"
      produces:
        - "application/json"
      parameters:
        - in: "path"
          name: "artist_id"
          description: "Artist ID"
          required: true
          type: "string"
      responses:
        200:
          description: "Artist details."
  /spotify/artists:
    get:
      summary: "Returns info about artists."
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: "ids"
          type: "string"
          description: "List of ID"
          required: true
      responses:
        200:
          description: "List of artists data."
  /spotify/playlists/{playlist_id}:
    get:
      summary: "Get playlist details"
      produces:
        - "application/json"
      parameters:
        - in: "path"
          name: "playlist_id"
          description: "Playlist ID"
          required: true
          type: "string"
        - in: "query"
          name: "market"
          type: "string"
          default: "global"
          description: "Market"
        - in: "query"
          name: "fields"
          type: "array"
          items:
            type: "string"
          description: "List of additional fields."
      responses:
        200:
          description: "Playlist details."
  /spotify/playlists:
    get:
      summary: "Returns info about playlists."
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: "ids"
          type: "string"
          required: true
          description: "List of ID"
        - in: "query"
          name: "market"
          type: "string"
          default: "global"
          description: "Market"
        - in: "query"
          name: "fields"
          type: "array"
          items:
            type: "string"
          description: "List of additional fields."
      responses:
        200:
          description: "List of playlists with details."
  /spotify/users/{user_id}:
    get:
      summary: "Get user details"
      produces:
        - "application/json"
      parameters:
        - in: "path"
          name: "user_id"
          description: "User ID"
          required: true
          type: "string"
      responses:
        200:
          description: "User details."
  /spotify/tracks-images:
    post:
      summary: "Returns track images urls."
      parameters:
      - in: "body"
        name: "body"
        required: true
        schema:
          type: object
          properties:
            ids:
              type: array
              items:
                type: string
            market:
              type: string
            image_size:
              type: integer
      responses:
        200:
          description: "List of tracks images id and url data."
  /spotify/playlists-images:
    post:
      summary: "Returns playlist images urls."
      parameters:
      - in: "body"
        name: "body"
        required: true
        schema:
          type: object
          properties:
            ids:
              type: array
              items:
                type: string
            market:
              type: string
      responses:
        200:
          description: "List of playlist images id and url data."
  /spotify/albums/{album_id}:
    get:
      summary: "Get album details."
      produces:
        - "application/json"
      parameters:
        - in: "path"
          name: "album_id"
          description: "Album ID"
          required: true
          type: "string"
        - in: "query"
          name: "market"
          type: "string"
          default: "global"
          description: "Market"
        - in: "query"
          name: "fields"
          type: "array"
          items:
            type: "string"
            enum: ["tracks", "tracks_full"]
          description: "List of additional fields: album tracks compact or full tracks info"
        - in: "query"
          name: "offset"
          description: "Album tracks page offset"
          type: "integer"
        - in: "query"
          name: "limit"
          description: "Album tracks page limit, return all if not set"
          type: "integer"
          maximum: 50
      responses:
        200:
          description: "Album details."
  /spotify/albums:
    get:
      summary: "Returns info about albums."
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: "ids"
          type: "integer"
          required: true
          description: "List of ID"
        - in: "query"
          name: "market"
          type: "string"
          default: "us"
          description: "Market"
      responses:
        200:
          description: "List of albums with details."
  /spotify/search:
    get:
      summary: "Returns info about found tracks."
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: "query"
          type: "string"
          required: true
          description: "Query string"
        - in: "query"
          name: "item_type"
          description: "List of requested types"
          type: "array"
          collectionFormat: multi
          default: ["track"]
          items:
            type: "string"
            enum: ["track", "album", "artist", "playlist"]
        - in: "query"
          name: "market"
          type: "string"
          description: "Market"
        - in: "query"
          name: "limit"
          description: "Limit for pagination"
          type: "integer"
          format: "int64"
        - in: "query"
          name: "offset"
          description: "Offset for pagination"
          type: "integer"
          format: "int64"
      responses:
        200:
          description: "List of tracks with details."

  /consumer_analytics/is_sony_tracks:
    get:
      summary: "Returns dict of pairs ISRC and flag is sony track or not."
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: "isrc"
          type: "string"
          required: true
          description: "List of ISRC"
      responses:
        200:
          description: "Dict {ISRC: boolean}."

  /consumer_analytics/streams_monitoring_data:
    get:
      summary: "Returns Apple and Spotify streams monitoring data in compact format."
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: "isrc"
          type: "string"
          required: true
          description: "Track ISRC value"
        - in: "query"
          name: "start_date"
          required: true
          type: "string"
          description: "Date range start date (ISO8601-formatted)"
        - in: "query"
          name: "end_date"
          required: true
          type: "string"
          description: "Date range end date (ISO8601-formatted)"
      responses:
        200:
          description: "Dict with Apple and Spotify streaming data."
          schema:
            type: "object"
            properties:
              spotify:
                type: "object"
                properties:
                  total_streams_num:
                    type: "integer"
                  active_streams_num:
                    type: "integer"
                  playlist_streams_num:
                    type: "integer"
                  non_playlist_streams_num:
                    type: "integer"
              apple:
                type: "object"
                properties:
                  total_streams_num:
                    type: "integer"

  /consumer_analytics/date_range_streams:
    get:
      summary: "Returns count of streams for given market between two dates."
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: "isrc"
          type: "string"
          required: true
          description: "Track ISRC value."
        - in: "query"
          name: "start_date"
          type: "string"
          required: true
          description: "Date range start date (ISO8601-formatted)"
        - in: "query"
          name: "end_date"
          type: "string"
          required: true
          description: "Date range end date (ISO8601-formatted)"
        - in: "query"
          name: "market"
          type: "string"
          required: true
          description: "Market code."
      responses:
        200:
          description: "Streams count."
          schema:
            type: "object"
            properties:
              results:
                type: "integer"

  /consumer_analytics/total_streams_count:
    get:
      summary: "Returns total count of streams."
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: "isrc"
          type: "string"
          required: true
          description: "Track ISRC value."
        - in: "query"
          name: "market"
          type: "string"
          description: "Market name."
        - in: "query"
          name: "end_date"
          type: "string"
          required: false
          description: "Optional end date parameter for CA requests."
      responses:
        200:
          description: "Total streams count."
          schema:
            type: "object"
            required: [ "global" ]
            properties:
              global:
                type: "integer"
              market:
                type: "integer"

  /consumer_analytics/streams-latest-date:
    get:
      summary: "Returns latest date for spotify streams. Cached for 15 minutes"
      produces:
        - "application/json"
      responses:
        200:
          description: "Latest date for spotify streams."
          schema:
            type: "object"
            properties:
              date:
                type: "string"
                description: "Date (ISO8601-formatted)"

  /consumer_analytics/stream_graph:
    get:
      summary: "Returns data for Stream Graph."
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: "isrc"
          type: "string"
          required: true
          description: "Track ISRC value."
        - in: "query"
          name: "market"
          type: "string"
          description: "Market name."
        - in: "query"
          name: "start_date"
          type: "string"
          required: true
          description: "Date range start date (ISO8601-formatted)"
        - in: "query"
          name: "end_date"
          type: "string"
          required: true
          description: "Date range end date (ISO8601-formatted)"
      responses:
        200:
          description: "Data with coordinates for Stream Graph."
          schema:
            type: "object"
            properties:
              spotify:
                $ref: '#/definitions/Coordinates'
              apple:
                $ref: '#/definitions/Coordinates'
  /consumer_analytics/daily-and-weekly-streams-count:
    get:
      summary: "Count daily and weekly based streams."
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: "isrc"
          type: "string"
          required: true
          description: "Track ISRC value."
        - in: "query"
          name: "market"
          type: "string"
          description: "Market name."
        - in: "query"
          name: "last_date"
          type: "string"
          required: false
          description: "Optional last date parameter."
      responses:
        200:
          description: "Streams counters data."
          schema:
            $ref: '#/definitions/StreamsCounters'
  /consumer_analytics/playlists-summary:
    get:
      summary: "Count track streams in playlists."
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: "isrc"
          type: "string"
          required: true
          description: "Track ISRC value."
        - in: "query"
          name: "market"
          type: "string"
          description: "Market name."
        - in: "query"
          name: "last_date"
          type: "string"
          required: false
          description: "Optional last date parameter."
        - in: "query"
          name: "vendor"
          required: true
          description: "Spotify or Apple"
          type: string
      responses:
        200:
          description: "Playlists streams num data."
          schema:
            $ref: '#/definitions/PlaylistTrackStreams'
  /consumer_analytics/tracks-streams:
    get:
      summary: "Count tracks streams in specific date range."
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: "isrc"
          type: "array"
          items:
            type: string
          required: true
          description: "Tracks ISRCs list."
        - in: "query"
          name: "market"
          type: "string"
          description: "optional market name. Global if missing"
        - in: "query"
          name: "start_date"
          type: "string"
          required: True
          description: "Start date parameter."
        - in: "query"
          name: "end_date"
          type: "string"
          required: True
          description: "End date parameter."
        - in: "query"
          name: "vendor"
          required: true
          description: "Spotify or Apple"
          type: string
      responses:
        200:
          description: "Tracks streams data."
          schema:
            $ref: '#/definitions/TracksISRCStreams'
  /consumer_analytics/detailed-streams-data:
    get:
      summary: "Coordinates data for detailed track streaming data chart."
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: "isrc"
          type: string
          required: true
          description: "Track ISRC value."
        - in: "query"
          name: "market"
          type: "string"
          description: "Optional market name. To get  data for global one - leave this field empty"
        - in: "query"
          name: "start_date"
          type: "string"
          required: True
          description: "Start date parameter."
        - in: "query"
          name: "end_date"
          type: "string"
          required: True
          description: "End date parameter."
        - in: "query"
          name: "vendor"
          type: "string"
          required: false
          description: "Spotify or Apple"
      responses:
        200:
          description: "Streams monitoring detailed view coordinates data."
          schema:
            type: "object"
  /consumer_analytics/track-per-country:
    get:
      summary: "Coordinates data for detailed track streaming data chart."
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: "isrc"
          type: string
          required: true
          description: "Track ISRC value."
        - in: "query"
          name: "start_date"
          type: "string"
          format: "date"
          required: True
          description: "Start date parameter."
        - in: "query"
          name: "end_date"
          type: "string"
          format: "date"
          required: True
          description: "End date parameter."
        - in: "query"
          name: "vendor"
          type: "string"
          required: true
          description: "Spotify or Apple"
        - in: "query"
          name: "streams_only"
          type: "boolean"
          default: "True"
          description: "Return streams count only (with country codes and dates)"
      responses:
        200:
          description: "Streams countr per date and country code."
          schema:
            type: "array"
            items:
              type: "object"
              properties:
                countryCode:
                  type: "string"
                data:
                  type: "object"
                  description: "Set of streams stats per date"
  /consumer_analytics/tracks-first-stream-dates:
    get:
      summary: "Coordinates data for detailed track streaming data chart."
      produces:
      - "application/json"
      parameters:
      - in: "query"
        name: "isrc"
        type: array
        items:
          type: "string"
        required: true
        description: "Track ISRC list."
      - in: "query"
        name: "vendor"
        type: "string"
        required: true
        description: "Spotify or Apple"
      responses:
        200:
          description: "ISRC to first stream date mapping."
          schema:
            type: "object"

  /vendors/search-by-isrc:
    get:
      summary: "Search track in Spotify and Apple with ISRC value."
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: "isrc"
          type: "string"
          required: true
          description: "Track ISRC value."
        - in: "query"
          name: "market"
          type: "string"
          description: "Optional market name. Global if missing"
      responses:
        200:
          description: "Vendor track data."
          schema:
            type: "object"
            properties:
              vendor:
                type: "string"
              track:
                type: "object"

  /delphi/amazon/playlist/tracks/streams:
    get:
      summary: "Query for aggregate counts of Amazon Playlist Track Streams"
      produces:
        - "application/json"
      parameters:
        - $ref: '#/parameters/isrc_array'
        - $ref: '#/parameters/amazon_playlist_id'
        - $ref: '#/parameters/start_date'
        - $ref: '#/parameters/end_date'
        - $ref: '#/parameters/country_code'
        - $ref: '#/parameters/group_by'
        - $ref: '#/parameters/limit'
        - $ref: '#/parameters/offset'
      responses:
        200:
          description: "Amazon Playlist Track Streams data."
          schema:
            $ref: '#/definitions/AmazonPlaylistTrackStreamStatsResponse'
  /delphi/amazon/playlists/streams:
    get:
      summary: "Query for aggregate counts of Amazon Playlist Streams"
      produces:
        - "application/json"
      parameters:
        - $ref: '#/parameters/amazon_playlist_id_array'
        - $ref: '#/parameters/start_date'
        - $ref: '#/parameters/end_date'
        - $ref: '#/parameters/country_code'
        - $ref: '#/parameters/group_by'
        - $ref: '#/parameters/limit'
        - $ref: '#/parameters/offset'
      responses:
        200:
          description: "Amazon Playlists Streams data."
          schema:
            $ref: '#/definitions/AmazonPlaylistsStatsResponse'
  /delphi/amazon/tracks/streams:
    get:
      summary: "Query for aggregate counts of Amazon Track Streams"
      produces:
        - "application/json"
      parameters:
        - $ref: '#/parameters/isrc_array'
        - $ref: '#/parameters/start_date'
        - $ref: '#/parameters/end_date'
        - $ref: '#/parameters/country_code'
        - $ref: '#/parameters/group_by'
        - $ref: '#/parameters/limit'
        - $ref: '#/parameters/offset'
      responses:
        200:
          description: "Amazon Tracks Streams data."
          schema:
            $ref: '#/definitions/AmazonTrackStreamStatsResponse'
  /delphi/streams_monitoring_data:
    get:
      summary: "Returns Apple, Spotify and Amazon streams monitoring data in compact format."
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: "isrc"
          type: "array"
          required: true
          items:
            type: "string"
          description: "Track ISRC value"
        - in: "query"
          name: "start_date"
          required: true
          type: "string"
          description: "Date range start date (ISO8601-formatted)"
        - in: "query"
          name: "end_date"
          required: true
          type: "string"
          description: "Date range end date (ISO8601-formatted)"
      responses:
        200:
          description: "Dict with Apple and Spotify streaming data."
          schema:
            type: "object"
            properties:
              spotify:
                type: "object"
                properties:
                  total_streams_num:
                    type: "integer"
                  active_streams_num:
                    type: "integer"
                  playlist_streams_num:
                    type: "integer"
                  non_playlist_streams_num:
                    type: "integer"
              apple:
                type: "object"
                properties:
                  total_streams_num:
                    type: "integer"
              amazon:
                type: "object"
                properties:
                  total_streams_num:
                    type: "integer"
  /delphi/date_range_streams:
    get:
      summary: "Returns count of streams for given market between two dates."
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: "isrc"
          type: "array"
          items:
            type: "string"
          required: true
          description: "Track ISRC value."
        - in: "query"
          name: "start_date"
          type: "string"
          required: true
          description: "Date range start date (ISO8601-formatted)"
        - in: "query"
          name: "end_date"
          type: "string"
          required: true
          description: "Date range end date (ISO8601-formatted)"
        - in: "query"
          name: "market"
          type: "string"
          required: true
          description: "Market code."
      responses:
        200:
          description: "Streams count."
          schema:
            type: "object"
            properties:
              results:
                type: "integer"
  /delphi/total_streams_count:
    get:
      summary: "Returns total count of streams."
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: "isrc"
          type: "array"
          items:
            type: "string"
          required: true
          description: "Track ISRC value."
        - in: "query"
          name: "market"
          type: "string"
          description: "Market name."
        - in: "query"
          name: "end_date"
          type: "string"
          required: false
          description: "Optional end date parameter for CA requests."
      responses:
        200:
          description: "Total streams count."
          schema:
            type: "object"
            required: [ "global" ]
            properties:
              global:
                type: "integer"
              market:
                type: "integer"
              first_stream_date:
                type: "object"
                properties:
                  spotify:
                    $ref: '#/definitions/string_date'
                  apple:
                    $ref: '#/definitions/string_date'
                  amazon:
                    $ref: '#/definitions/string_date'
  /delphi/stream_graph:
    get:
      summary: "Returns data for Stream Graph."
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: "isrc"
          type: "array"
          items:
            type: "string"
          required: true
          description: "Track ISRC value."
        - in: "query"
          name: "market"
          type: "string"
          description: "Market name."
        - in: "query"
          name: "start_date"
          type: "string"
          required: true
          description: "Date range start date (ISO8601-formatted)"
        - in: "query"
          name: "end_date"
          type: "string"
          required: true
          description: "Date range end date (ISO8601-formatted)"
      responses:
        200:
          description: "Data with coordinates for Stream Graph."
          schema:
            type: "object"
            properties:
              spotify:
                $ref: '#/definitions/Coordinates'
              apple:
                $ref: '#/definitions/Coordinates'
              amazon:
                $ref: '#/definitions/Coordinates'

  /analytics/v1/daily-and-weekly-streams-count:
    get:
      summary: "Returns Apple, Spotify and Amazon chart week and day based streams data. Chart week - last whole 7 days from Fr to Th"
      produces:
      - "application/json"
      parameters:
      - in: "query"
        name: "isrc"
        type: "string"
        required: true
        description: "Track ISRC value."
      - in: "query"
        name: "per_vendors"
        type: "boolean"
        default: "false"
        description: "Display detailed per vendors response."
      - in: "query"
        name: "market"
        type: "string"
        required: false
        description: "Market code value, leave empty for global one."
      - in: "query"
        name: "last_date"
        type: "string"
        required: false
        description: "Date range end date (ISO8601-formatted)."
      responses:
        200:
          description: "Daily and chart week based streams data."
          schema:
            type: "object"
            properties:
              market:
                type: "string"
              global_streams:
                $ref: '#/definitions/DayAndWeekStreams'
              market_streams:
                $ref: '#/definitions/DayAndWeekStreams'
              dates:
                $ref: '#/definitions/CurrPrevDaysAndWeeks'
              vendors:
                type:
                  "object"
                properties:
                  spotify:
                    $ref: "#/definitions/StreamsCounters"
                  apple:
                    $ref: "#/definitions/StreamsCounters"
                  amazon:
                    $ref: "#/definitions/StreamsCounters"
            required:
              - global_streams
              - dates

  /analytics/v1/weekly-streams-count:
    get:
      summary: "Returns Apple, Spotify and Amazon weekly based streams data. Current week - 7 days ago from current date, Previous week - 7 days ago from yesterday"
      produces:
      - "application/json"
      parameters:
      - in: "query"
        name: "isrc"
        type: "string"
        required: true
        description: "Track ISRC value."
      - in: "query"
        name: "per_vendors"
        type: "boolean"
        default: "false"
        description: "Display detailed per vendors response."
      - in: "query"
        name: "market"
        type: "string"
        required: false
        description: "Market code value, leave empty for global one."
      - in: "query"
        name: "last_date"
        type: "string"
        required: false
        description: "Date range end date (ISO8601-formatted)."
      responses:
        200:
          description: "Week based streams data."
          schema:
            type: "object"
            properties:
              market:
                type: "string"
              global_streams:
                $ref: '#/definitions/DayAndWeekStreams'
              market_streams:
                $ref: '#/definitions/DayAndWeekStreams'
              dates:
                $ref: '#/definitions/CurrPrevWeeks'
              vendors:
                type:
                  "object"
                properties:
                  spotify:
                    $ref: "#/definitions/WeekStreams"
                  apple:
                    $ref: "#/definitions/WeekStreams"
                  amazon:
                    $ref: "#/definitions/WeekStreams"
            required:
              - global_streams
              - dates

  /analytics/v1/date-range-streams:
    get:
      summary: "Returns num of streams in a specific dates range and for specific market and global one for all 3 vendors."
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: "isrc"
          type: "string"
          required: true
          description: "Track ISRC value."
        - in: "query"
          name: "per_vendors"
          type: "boolean"
          default: "false"
          description: "Display detailed per vendors response."
        - in: "query"
          name: "market"
          type: "string"
          required: false
          description: "Market code value, leave empty for global one."
        - in: "query"
          name: "start_date"
          type: "string"
          required: true
          description: "Date range end date (ISO8601-formatted)."
        - in: "query"
          name: "end_date"
          type: "string"
          required: true
          description: "Date range end date (ISO8601-formatted)."
      responses:
        200:
          description: "Track streams num in a specific dates range."
          schema:
            type: "object"
            properties:
              streams:
                type: "number"
              vendors:
                type:
                  "object"
                properties:
                  spotify:
                    type: "number"
                  apple:
                    type: "number"
                  amazon:
                    type: "number"
            required:
              - streams

  /analytics/v1/tracks-date-range-streams:
    get:
      summary: "Returns tracks num of streams in a specific dates range and for specific market and global one for all 3 vendors."
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: "isrc"
          type: "array"
          required: true
          items:
            type: "string"
          description: "Comma-separated list of tracks ISRCs values."
        - in: "query"
          name: "per_vendors"
          type: "boolean"
          default: "false"
          description: "Display detailed per vendors response."
        - in: "query"
          name: "market"
          type: "string"
          required: false
          description: "Market code value, leave empty for global one."
        - in: "query"
          name: "start_date"
          type: "string"
          required: true
          description: "Date range end date (ISO8601-formatted)."
        - in: "query"
          name: "end_date"
          type: "string"
          required: true
          description: "Date range end date (ISO8601-formatted)."
      responses:
        200:
          description: "Track streams num in a specific dates range."
          schema:
            type: "object"
            properties:
              streams:
                $ref: "#/definitions/TracksISRCStreams"
              vendors:
                type: "object"
                properties:
                  spotify:
                    $ref: "#/definitions/TracksISRCStreams"
                  apple:
                    $ref: "#/definitions/TracksISRCStreams"
                  amazon:
                    $ref: "#/definitions/TracksISRCStreams"
            required:
              - streams

  /analytics/v1/total-streams-count:
    get:
      summary: "Returns total num of streams for specific market and global one for all 3 vendors."
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: "isrc"
          type: "string"
          required: true
          description: "Track ISRC value."
        - in: "query"
          name: "per_vendors"
          type: "boolean"
          default: "false"
          description: "Display detailed per vendors response."
        - in: "query"
          name: "market"
          type: "string"
          required: false
          description: "Market code value, leave empty for global one."
        - in: "query"
          name: "last_date"
          type: "string"
          required: false
          description: "Date range end date (ISO8601-formatted)."
      responses:
        200:
          description: "Daily and chart week based streams data."
          schema:
            type: "object"
            properties:
              global_streams:
                type: "number"
              market_streams:
                type: "number"
              vendors:
                type:
                  "object"
                properties:
                  spotify:
                    $ref: "#/definitions/VendorStreamsCounters"
                  apple:
                    $ref: "#/definitions/VendorStreamsCounters"
                  amazon:
                    $ref: "#/definitions/VendorStreamsCounters"
            required:
              - global_streams

  /analytics/v1/streams-dates:
    get:
      summary: "Returns Apple, Spotify and Amazon first stream dates and Spotify last strem date."
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: "isrc"
          type: "array"
          required: true
          items:
            type: "string"
          description: "Track ISRC list"
        - in: "query"
          name: "include_last_dates"
          type: "boolean"
          description: "Include last dates or not"
      responses:
        200:
          description: "Vendors first and last strem dates."
          schema:
            type: "object"
            properties:
              first_stream_date:
                type: "object"
                properties:
                  spotify:
                    type: "object"
                    description: "ISRC to date mapping."
                  apple:
                    type: "object"
                    description: "ISRC to date mapping."
                  amazon:
                    type: "object"
                    description: "ISRC to date mapping."
              last_stream_date:
                type: "object"
                properties:
                  spotify:
                    $ref: '#/definitions/string_date'

definitions:
  Coordinate:
    type: object
    properties:
      x:
        type: number
      y:
        type: number
  Coordinates:
    type: array
    items:
      $ref: '#/definitions/Coordinate'
  VendorStreamsCounters:
    type: object
    properties:
      global_streams:
        type: "number"
      market_streams:
        type: "number"
    required:
      - global_streams
  StreamsCounters:
    type: object
    properties:
      global_streams:
        $ref: '#/definitions/DayAndWeekStreams'
      market_streams:
        $ref: '#/definitions/DayAndWeekStreams'
    required:
      - global_streams
  DayAndWeekStreams:
    type: object
    properties:
      prev_week:
        type: number
      current_week:
        type: number
      prev_day:
        type: number
      current_day:
        type: number
  WeekStreams:
    type: object
    properties:
      prev_week:
        type: number
      current_week:
        type: number
  PlaylistTrackStreams:
    type: object
    additionalProperties:
      type: string
      properties:
        playlist_id:
          type: string
        streams:
          type: integer
    example:
      "pl.5ldgfdd54324": 6547
      "pl.7797thgfgfh": 21
  TracksISRCStreams:
    type: object
    additionalProperties:
      type: string
      properties:
        isrc:
          type: string
        streams:
          type: integer
    example:
      "USAT21907135": 6547
      "USSM19400325": 21345234
  AmazonDeviceType:
    properties:
      cell_phone_app_mobile_web:
        $ref: '#/definitions/int_string'
      connected_home_audio_tether:
        $ref: '#/definitions/int_string'
      connected_home_tv:
        $ref: '#/definitions/int_string'
      desktop:
        $ref: '#/definitions/int_string'
      gaming_system:
        $ref: '#/definitions/int_string'
      in_dash_car_integration:
        $ref: '#/definitions/int_string'
      mobile_to_car_tether:
        $ref: '#/definitions/int_string'
      other:
        $ref: '#/definitions/int_string'
      tablet_app:
        $ref: '#/definitions/int_string'
      voice_controlled_device:
        $ref: '#/definitions/int_string'
    type: object
  AmazonEngagement:
    properties:
      lean_back:
        $ref: '#/definitions/int_string'
      lean_forward:
        $ref: '#/definitions/int_string'
    type: object
  AmazonOperatingSystem:
    properties:
      alexa:
        $ref: '#/definitions/int_string'
      android:
        $ref: '#/definitions/int_string'
      fire_os:
        $ref: '#/definitions/int_string'
      ios:
        $ref: '#/definitions/int_string'
      mac_osx:
        $ref: '#/definitions/int_string'
      third_party_device_os:
        $ref: '#/definitions/int_string'
      unknown:
        $ref: '#/definitions/int_string'
      windows:
        $ref: '#/definitions/int_string'
    type: object
  AmazonPlaylistStats:
    properties:
      country_code:
        description: Country code
        example: us
        type: string
      date:
        description: '(optional) If group_by provided, this will include the date'
        $ref: '#/definitions/string_date'
      device_type:
        $ref: '#/definitions/AmazonDeviceType'
      device_type_streams:
        description: Total number of streams for `device_type`
        example: '123456'
        pattern: '^[0-9]*$'
        type: string
      engagement:
        $ref: '#/definitions/AmazonEngagement'
      engagement_streams:
        description: Total number of streams for `engagement`
        example: '123456'
        pattern: '^[0-9]*$'
        type: string
      operating_system:
        $ref: '#/definitions/AmazonOperatingSystem'
      operating_system_streams:
        description: Total number of streams for `operating_system`
        example: '123456'
        pattern: '^[0-9]*$'
        type: string
      playlist_id:
        $ref: '#/definitions/amazon_playlist_id'
      referral_source_type:
        $ref: '#/definitions/AmazonReferralSourceType'
      referral_source_type_streams:
        description: Total number of streams for `referral_source_type`
        example: '123456'
        pattern: '^[0-9]*$'
        type: string
      royalty_bearing_play_no:
        example: '123456'
        pattern: '^[0-9]*$'
        type: string
      royalty_bearing_play_yes:
        example: '123456'
        pattern: '^[0-9]*$'
        type: string
      selection_source_type:
        $ref: '#/definitions/AmazonSelectionSourceType'
      selection_source_type_streams:
        description: Total number of streams for `selection_source_type`
        example: '123456'
        pattern: '^[0-9]*$'
        type: string
      stream_source_type:
        $ref: '#/definitions/AmazonStreamSourceType'
      stream_source_type_streams:
        description: Total number of streams for `stream_source_type`
        example: '123456'
        pattern: '^[0-9]*$'
        type: string
      streams:
        description: Grand total number of streams
        example: '123456'
        pattern: '^[0-9]*$'
        type: string
    type: object
  AmazonPlaylistTrackStreamStats:
    properties:
      country_code:
        description: Country code
        example: us
        type: string
      date:
        description: '(optional) If group_by provided, this will include the date'
        $ref: '#/definitions/string_date'
      device_type:
        $ref: '#/definitions/AmazonDeviceType'
      device_type_streams:
        description: Total number of streams for `device_type`
        example: '123456'
        pattern: '^[0-9]*$'
        type: string
      engagement:
        $ref: '#/definitions/AmazonEngagement'
      engagement_streams:
        description: Total number of streams for `engagement`
        example: '123456'
        pattern: '^[0-9]*$'
        type: string
      isrc:
        $ref: '#/definitions/isrc'
      operating_system:
        $ref: '#/definitions/AmazonOperatingSystem'
      operating_system_streams:
        description: Total number of streams for `operating_system`
        example: '123456'
        pattern: '^[0-9]*$'
        type: string
      playlist_id:
        $ref: '#/definitions/amazon_playlist_id'
      referral_source_type:
        $ref: '#/definitions/AmazonReferralSourceType'
      referral_source_type_streams:
        description: Total number of streams for `referral_source_type`
        example: '123456'
        pattern: '^[0-9]*$'
        type: string
      royalty_bearing_play_no:
        example: '123456'
        pattern: '^[0-9]*$'
        type: string
      royalty_bearing_play_yes:
        example: '123456'
        pattern: '^[0-9]*$'
        type: string
      selection_source_type:
        $ref: '#/definitions/AmazonSelectionSourceType'
      selection_source_type_streams:
        description: Total number of streams for `selection_source_type`
        example: '123456'
        pattern: '^[0-9]*$'
        type: string
      stream_source_type:
        $ref: '#/definitions/AmazonStreamSourceType'
      stream_source_type_streams:
        description: Total number of streams for `stream_source_type`
        example: '123456'
        pattern: '^[0-9]*$'
        type: string
      streams:
        description: Grand total number of streams
        example: '123456'
        pattern: '^[0-9]*$'
        type: string
    type: object
  AmazonPlaylistTrackStreamStatsResponse:
    properties:
      count:
        $ref: '#/definitions/count'
      items:
        items:
          $ref: '#/definitions/AmazonPlaylistTrackStreamStats'
        type: array
    type: object
  AmazonPlaylistsStatsResponse:
    properties:
      count:
        $ref: '#/definitions/count'
      items:
        items:
          $ref: '#/definitions/AmazonPlaylistStats'
        type: array
    type: object
  AmazonReferralSourceType:
    properties:
      not_available:
        $ref: '#/definitions/int_string'
      recommended_content_promotions:
        $ref: '#/definitions/int_string'
      search_result:
        $ref: '#/definitions/int_string'
      sme_paid_promotion:
        $ref: '#/definitions/int_string'
      sme_promotional_marketing_inventory:
        $ref: '#/definitions/int_string'
      websites_or_hyperlinks:
        $ref: '#/definitions/int_string'
    type: object
  AmazonSelectionSourceType:
    properties:
      album:
        $ref: '#/definitions/int_string'
      artist:
        $ref: '#/definitions/int_string'
      auto_playlist:
        $ref: '#/definitions/int_string'
      prime_playlist:
        $ref: '#/definitions/int_string'
      prime_station:
        $ref: '#/definitions/int_string'
      songs:
        $ref: '#/definitions/int_string'
      user_playlist:
        $ref: '#/definitions/int_string'
    type: object
  AmazonStreamSourceType:
    properties:
      all_other_areas:
        $ref: '#/definitions/int_string'
      api_partner:
        $ref: '#/definitions/int_string'
      artist_profile_page:
        $ref: '#/definitions/int_string'
      charts_and_algorithmic:
        $ref: '#/definitions/int_string'
      content_pages:
        $ref: '#/definitions/int_string'
      followed_saved_third_party:
        $ref: '#/definitions/int_string'
      promotional:
        $ref: '#/definitions/int_string'
      recent_activity:
        $ref: '#/definitions/int_string'
      search_results_page:
        $ref: '#/definitions/int_string'
      semi_interactive_radio_station:
        $ref: '#/definitions/int_string'
      user_created_playlists:
        $ref: '#/definitions/int_string'
    type: object
  AmazonTrackStreamStats:
    properties:
      country_code:
        description: Country code
        example: us
        type: string
      date:
        description: '(optional) If group_by provided, this will include the date'
        $ref: '#/definitions/string_date'
      device_type:
        $ref: '#/definitions/AmazonDeviceType'
      device_type_streams:
        description: Total number of streams for `device_type`
        example: '123456'
        pattern: '^[0-9]*$'
        type: string
      engagement:
        $ref: '#/definitions/AmazonEngagement'
      engagement_streams:
        description: Total number of streams for `engagement`
        example: '123456'
        pattern: '^[0-9]*$'
        type: string
      isrc:
        $ref: '#/definitions/isrc'
      operating_system:
        $ref: '#/definitions/AmazonOperatingSystem'
      operating_system_streams:
        description: Total number of streams for `operating_system`
        example: '123456'
        pattern: '^[0-9]*$'
        type: string
      referral_source_type:
        $ref: '#/definitions/AmazonReferralSourceType'
      referral_source_type_streams:
        description: Total number of streams for `referral_source_type`
        example: '123456'
        pattern: '^[0-9]*$'
        type: string
      royalty_bearing_play_no:
        example: '123456'
        pattern: '^[0-9]*$'
        type: string
      royalty_bearing_play_yes:
        example: '123456'
        pattern: '^[0-9]*$'
        type: string
      selection_source_type:
        $ref: '#/definitions/AmazonSelectionSourceType'
      selection_source_type_streams:
        description: Total number of streams for `selection_source_type`
        example: '123456'
        pattern: '^[0-9]*$'
        type: string
      stream_source_type:
        $ref: '#/definitions/AmazonStreamSourceType'
      stream_source_type_streams:
        description: Total number of streams for `stream_source_type`
        example: '123456'
        pattern: '^[0-9]*$'
        type: string
      streams:
        description: Grand total number of streams
        example: '123456'
        pattern: '^[0-9]*$'
        type: string
    type: object
  DatesRange:
    properties:
      start:
        $ref: '#/definitions/string_date'
      end:
        $ref: '#/definitions/string_date'
  CurrPrevDaysAndWeeks:
    properties:
      curr_week:
        $ref: '#/definitions/DatesRange'
      prew_week:
        $ref: '#/definitions/DatesRange'
      current_day:
        $ref: '#/definitions/string_date'
      prev_day:
        $ref: '#/definitions/string_date'
  CurrPrevWeeks:
    properties:
      curr_week:
        $ref: '#/definitions/DatesRange'
      prew_week:
        $ref: '#/definitions/DatesRange'
  AmazonTrackStreamStatsResponse:
    properties:
      count:
        $ref: '#/definitions/count'
      items:
        items:
          $ref: '#/definitions/AmazonTrackStreamStats'
        type: array
    type: object
  amazon_playlist_id:
    example: 00001f08-40d4-461a-a8dc-dd91da8b5cb6
    format: uuid
    type: string
  count:
    default: 0
    description: The number of ``items`` returned in the response
    example: 25
    format: int32
    type: integer
  int_string:
    default: '0'
    description: String representation of an integer for precision portability of large integers
    example: '123456'
    pattern: '^[0-9]*$'
    type: string
  isrc:
    description: The International Standard Recording Code (ISRC) for a song.
    example: USSM11904174
    pattern: '^[A-Z]{2}\w{3}\d{2}\d{5}$'
    type: string
  string_date:
    format: date
    pattern: '^\d{4}-\d{2}-\d{2}$'
    type: string