swagger: "2.0"
info:
  description: "https://github.com/filtr/apollo-api"
  version: "1.0.0"
  title: "Apollo API"
host: "127.0.0.1:5000"
basePath: "/api"
schemes:
- "http"
securityDefinitions:
  apiKey:
    type: apiKey
    in: "header"
    name: "Authorization"
    description: "Service API key"
  userId:
    type: apiKey
    in: "header"
    name: "X-User-Id"
    description: "Current user ID"
security:
  - apiKey: []
    userId: []
paths:
  /compared-tracks/:
    get:
      summary: "Returns current state of user's track comparison page."
      parameters:
      - in: "query"
        name: "market"
        type: "string"
      produces:
      - "application/json"
      responses:
        200:
          description: "List of objects containing IDs of compared tracks."
          schema:
            $ref: '#/definitions/ComparisonTrackList'
    post:
      summary: "Updates saved state of comparison page when new track is added to comparison."
      produces:
      - "application/json"
      parameters:
      - in: "query"
        name: "market"
        type: "string"
      - in: "body"
        name: "body"
        description: "Spotify or Apple Music ID of the added track."
        required: true
        schema:
          type: object
          properties:
            spotify_id:
              type: "string"
            apple_id:
              type: "integer"
      responses:
        200:
          description: "For empty body clear non Sony tracks for the market and return a list of comparison tracks."
          schema:
            $ref: '#/definitions/ComparisonTrackList'
        201:
          description: "Track data saved successfully."
          schema:
            description: "Details of the added track."
            type: "object"
            properties:
              spotify_id:
                type: "string"
              apple_id:
                type: "integer"
              isrc:
                type: "string"
    delete:
      summary: "Updates saved state of user's comparison page when some track is removed from comparison."
      produces:
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "Spotify or Apple Music ID of the removed track."
        required: true
        schema:
          type: object
          properties:
            spotify_id:
              type: "string"
            apple_id:
              type: "integer"
      responses:
        200:
          description: "Track deleted from the state of comparison page."
          schema:
            type: "object"
            properties:
              status:
                type: "string"
                enum:
                - "OK"
                default: "OK"

  /v1/starred-tracks/detailed/:
    get:
      summary: "Get starred tracks detailed data for the current user."
      parameters:
        - in: "query"
          name: "market"
          type: "string"
        - in: "query"
          name: "offset"
          type: "integer"
        - in: "query"
          name: "limit"
          type: "integer"
        - in: "query"
          name: "related"
          type: "boolean"
      produces:
        - "application/json"
      responses:
        200:
          description: "List of starred tracks URI, optionally with pagination parameters."
          schema:
            type: "object"
            properties:
              items:
                type: "array"
                items:
                  type: "object"
                  properties:
                    available:
                      type: "boolean"
                    extra_data:
                      type: "object"
                    isrc:
                      type: "string"
                    uri:
                      type: "string"
                    is_sony:
                      type: "boolean"
                    vendor:
                      type: "string"
                    id:
                      type: "string"
                    streams:
                      type: "integer"
                    related:
                      type: "object"
              count:
                type: "integer"
              previous:
                type: "string"
              next:
                type: "string"

  /v1/starred-tracks/check/:
    get:
      summary: "Check track is starred one by it ISRC value."
      parameters:
        - in: "query"
          name: "isrc"
          type: "string"
          description: "comma-separated list of ISRC values."
      produces:
        - "application/json"
      responses:
        200:
          description: "Key-values pairs of tracks ISRC and is starred flag values."
          schema:
            type: "object"
            additionalProperties:
              type: boolean
            example:
              "QZES71982312": false
              "UATS62572312": true

  /v1/starred-tracks/:
    get:
      summary: "Get starred tracks for the current user."
      produces:
      - "application/json"
      responses:
        200:
          description: "List of starred tracks URI, optionally with pagination parameters."
          schema:
            type: "array"
            items:
              type: "object"
              properties:
                isrc:
                  type: "string"
                uri:
                  type: "string"
    post:
      summary: "Add starred track for the current user."
      produces:
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        required: true
        schema:
          type: "object"
          properties:
            uri:
              type: "string"
            isrc:
              type: "string"
      responses:
        201:
          description: "Starred track was saved successfully."
          schema:
            type: "object"
            properties:
              status:
                type: "string"
                enum:
                - "OK"
                default: "OK"
        400:
          description: "Track is already starred."
    delete:
      summary: "Remove starred track for the current user."
      parameters:
      - in: "query"
        name: "isrc"
        type: "string"
        description: "ISRC track to delete."
      produces:
      - "application/json"
      responses:
        200:
          description: "Starred tracks were removed successfully."
          schema:
            type: "object"
            properties:
              status:
                type: "string"
                enum:
                - "OK"
                default: "OK"
        400:
          description: "Track is already unstarred."

  /track-ids/:
    get:
      summary: "Get vendor track IDs by ISRC."
      parameters:
      - in: "query"
        name: "isrc"
        type: "string"
      - in: "query"
        name: "apple_id"
        type: "integer"
      - in: "query"
        name: "spotify_id"
        type: "string"
      - in: "query"
        name: "vendor"
        type: "string"
        enum: [spotify, apple]
        description: "Only for this vendor."
      - in: "query"
        name: "limit"
        type: "integer"
        description: "ID list length limit per vendor."
      produces:
      - "application/json"
      responses:
        200:
          description: "List of objects containing IDs of starred tracks."
          schema:
            type: "object"
            properties:
              spotify:
                type: "array"
                items:
                  type: "string"
              apple:
                type: "array"
                items:
                  type: "integer"
              isrc:
                type: "string"

  /is-sony/:
    get:
      summary: "Get if tracks are Sony or not."
      parameters:
      - in: "query"
        name: "isrc"
        type: "array"
        items:
          type: "string"
      - in: "query"
        name: "spotify_ids"
        type: "array"
        items:
          type: "string"
      - in: "query"
        name: "apple_ids"
        type: "array"
        items:
          type: "string"
      - in: "query"
        name: "market"
        type: "string"
        required: true
      produces:
      - "application/json"
      responses:
        200:
          description: "Key-values pairs of Sony track IDs/ISRC and is_sony flags."
          schema:
            type: "object"
            additionalProperties:
              type: string
            example:
              "QZES71982312": false
              "0000iGYsxbrtG0PNnL2Mw2": true

  /albums/is-sony/:
    get:
      summary: "Get if albums are Sony or not by UPC."
      parameters:
      - in: "query"
        name: "upc"
        type: "array"
        items:
          type: "string"
      - in: "query"
        name: "market"
        type: "string"
      produces:
      - "application/json"
      responses:
        200:
          description: "List of Sony album's UPC."
          schema:
            type: "array"
            items:
              type: "string"

  /charts/top/:
    parameters:
    - in: "query"
      name: "vendor"
      required: true
      type: "string"
      enum: [spotify, apple]
    - in: "query"
      name: "market"
      required: true
      type: "string"
    - in: "query"
      name: "start"
      type: "integer"
    - in: "query"
      name: "end"
      type: "integer"
    - in: "query"
      name: "is_sony"
      type: "boolean"
    - in: "query"
      name: "as_file"
      type: "boolean"
    - in: "query"
      description: "Chart date, for Spotify only"
      name: "date"
      type: "string"
      format: "date"
    - in: "query"
      description: "Chart type, daily or weekly, for Spotify only"
      name: "type"
      type: "string"
      enum: [weekly, daily]
    - in: "query"
      name: "only_starred_tracks"
      required: false
      type: "boolean"
    - in: "query"
      name: "order_by"
      required: false
      type: "array"
      collectionFormat: multi
      items:
        type: "string"
        enum: [is_starred_track, position, moves, track_name, track_id, -is_starred_track, -position, -moves, -track_name, -track_id]
      default: []
    - in: "query"
      name: "fields"
      required: false
      type: "array"
      collectionFormat: multi
      items:
        type: "string"
        enum: [album_id, artist_id, is_re_enter, trends, image_url, artists, is_sony, is_starred, chart_date]
      default: []
    get:
      summary: "Returns set of chart tracks by position."
      produces:
      - "application/json"
      responses:
        200:
          description: "List of chart tracks and last date of data presence."
          schema:
            type: "object"
            properties:
              chart_date:
                description: "Last data presence"
                type: "string"
                format: "date"
              tracks:
                $ref: '#/definitions/ChartTrackList'

  /charts/out/:
    parameters:
    - in: "query"
      name: "vendor"
      required: true
      type: "string"
      enum: [spotify, apple]
    - in: "query"
      name: "market"
      required: true
      type: "string"
    - in: "query"
      name: "start"
      type: "integer"
    - in: "query"
      name: "end"
      type: "integer"
    - in: "query"
      name: "is_sony"
      type: "boolean"
    - in: "query"
      description: "Chart date, for Spotify only"
      name: "date"
      type: "string"
      format: "date"
    - in: "query"
      description: "Chart type, daily or weekly, for Spotify only"
      name: "type"
      type: "string"
      enum: [weekly, daily]
    - in: "query"
      name: "only_starred_tracks"
      required: false
      type: "boolean"
    - in: "query"
      name: "order_by"
      required: false
      type: "array"
      collectionFormat: multi
      items:
        type: "string"
        enum: [is_starred_track, position, moves, track_name, track_id, -is_starred_track, -position, -moves, -track_name, -track_id]
      default: []
    - in: "query"
      name: "fields"
      required: false
      type: "array"
      collectionFormat: multi
      items:
        type: "string"
        enum: [album_id, artist_id, is_re_enter, trends, image_url, artists, is_sony, is_starred, chart_date]
      default: []
    get:
      summary: "Returns set of chart tracks that moved out of the positions interval."
      produces:
      - "application/json"
      responses:
        200:
          description: "List of chart tracks."
          schema:
            type: "object"
            properties:
              chart_date:
                description: "Last data presence"
                type: "string"
                format: "date"
              tracks:
                $ref: '#/definitions/ChartTrackList'

  /charts/moves/:
    parameters:
    - in: "query"
      name: "vendor"
      required: true
      type: "string"
      enum: [spotify, apple]
    - in: "query"
      name: "market"
      required: true
      type: "string"
    - in: "query"
      name: "change"
      type: "integer"
    - in: "query"
      name: "only_starred_tracks"
      required: false
      type: "boolean"
    - in: "query"
      name: "is_sony"
      type: "boolean"
    - in: "query"
      description: "Chart date, for Spotify only"
      name: "date"
      type: "string"
      format: "date"
    - in: "query"
      description: "Chart type, daily or weekly, for Spotify only"
      name: "type"
      type: "string"
      enum: [weekly, daily]
    - in: "query"
      name: "order_by"
      required: false
      type: "array"
      collectionFormat: multi
      items:
        type: "string"
        enum: [is_starred_track, position, moves, track_name, track_id, -is_starred_track, -position, -moves, -track_name, -track_id]
      default: []
    - in: "query"
      name: "fields"
      required: false
      type: "array"
      collectionFormat: multi
      items:
        type: "string"
        enum: [album_id, artist_id, is_re_enter, trends, image_url, artists, is_sony, is_starred, chart_date]
      default: []
    get:
      summary: "Returns set of chart tracks by absolute position change."
      produces:
      - "application/json"
      responses:
        200:
          description: "List of chart tracks."
          schema:
            type: "object"
            properties:
              chart_date:
                description: "Last data presence"
                type: "string"
                format: "date"
              tracks:
                $ref: '#/definitions/ChartTrackList'

  /charts/additions/:
    parameters:
    - in: "query"
      name: "vendor"
      required: true
      type: "string"
      enum: [spotify, apple]
    - in: "query"
      name: "market"
      required: true
      type: "string"
    - in: "query"
      name: "only_starred_tracks"
      required: false
      type: "boolean"
    - in: "query"
      name: "is_sony"
      type: "boolean"
    - in: "query"
      description: "Chart date, for Spotify only"
      name: "date"
      type: "string"
      format: "date"
    - in: "query"
      description: "Chart type, daily or weekly, for Spotify only"
      name: "type"
      type: "string"
      enum: [weekly, daily]
    - in: "query"
      name: "order_by"
      required: false
      type: "array"
      collectionFormat: multi
      items:
        type: "string"
        enum: [is_starred_track, position, moves, track_name, track_id, -is_starred_track, -position, -moves, -track_name, -track_id]
      default: []
    - in: "query"
      name: "fields"
      required: false
      type: "array"
      collectionFormat: multi
      items:
        type: "string"
        enum: [album_id, artist_id, is_re_enter, trends, image_url, artists, is_sony, is_starred, chart_date]
      default: []
    - in: "query"
      name: "start"
      type: "integer"
    - in: "query"
      name: "end"
      type: "integer"
    get:
      summary: "Returns set of new chart tracks."
      produces:
      - "application/json"
      responses:
        200:
          description: "List of chart tracks."
          schema:
            type: "object"
            properties:
              chart_date:
                description: "Last data presence"
                type: "string"
                format: "date"
              tracks:
                $ref: '#/definitions/ChartTrackList'

  /charts/removals/:
    parameters:
    - in: "query"
      name: "vendor"
      required: true
      type: "string"
      enum: [spotify, apple]
    - in: "query"
      name: "market"
      required: true
      type: "string"
    - in: "query"
      name: "only_starred_tracks"
      required: false
      type: "boolean"
    - in: "query"
      name: "is_sony"
      type: "boolean"
    - in: "query"
      description: "Chart date, for Spotify only"
      name: "date"
      type: "string"
      format: "date"
    - in: "query"
      description: "Chart type, daily or weekly, for Spotify only"
      name: "type"
      type: "string"
      enum: [weekly, daily]
    - in: "query"
      name: "order_by"
      required: false
      type: "array"
      collectionFormat: multi
      items:
        type: "string"
        enum: [is_starred_track, position, moves, track_name, track_id, -is_starred_track, -position, -moves, -track_name, -track_id]
      default: []
    - in: "query"
      name: "fields"
      required: false
      type: "array"
      collectionFormat: multi
      items:
        type: "string"
        enum: [album_id, artist_id, is_re_enter, trends, image_url, artists, is_sony, is_starred, chart_date]
      default: []
    - in: "query"
      name: "start"
      type: "integer"
    - in: "query"
      name: "end"
      type: "integer"
    get:
      summary: "Returns set of tracks that were removed from chart."
      produces:
      - "application/json"
      responses:
        200:
          description: "List of chart tracks."
          schema:
            type: "object"
            properties:
              chart_date:
                description: "Last data presence"
                type: "string"
                format: "date"
              tracks:
                $ref: '#/definitions/ChartTrackList'
  /v1/charts/top/:
    parameters:
    - in: "query"
      name: "vendor"
      required: true
      type: "string"
      enum: [spotify, apple]
    - in: "query"
      name: "market"
      required: true
      type: "string"
    - in: "query"
      name: "start"
      type: "integer"
    - in: "query"
      name: "end"
      type: "integer"
    - in: "query"
      name: "is_sony"
      type: "boolean"
    - in: "query"
      name: "as_file"
      type: "boolean"
    - in: "query"
      description: "Chart date, for Spotify only"
      name: "date"
      type: "string"
      format: "date"
    - in: "query"
      description: "Chart type, daily or weekly, for Spotify only"
      name: "type"
      type: "string"
      enum: [weekly, daily]
    - in: "query"
      name: "only_starred_tracks"
      required: false
      type: "boolean"
    - in: "query"
      name: "order_by"
      required: false
      type: "array"
      collectionFormat: multi
      items:
        type: "string"
        enum: [is_starred_track, position, moves, track_name, track_id, -is_starred_track, -position, -moves, -track_name, -track_id]
      default: []
    - in: "query"
      name: "fields"
      required: false
      type: "array"
      collectionFormat: multi
      items:
        type: "string"
        enum: [album_id, artist_id, is_re_enter, trends, image_url, artists, is_sony, is_starred, chart_date]
      default: []
    get:
      summary: "Returns set of chart tracks by position."
      produces:
      - "application/json"
      responses:
        200:
          description: "List of chart tracks and last date of data presence."
          schema:
            type: "object"
            properties:
              chart_date:
                description: "Last data presence"
                type: "string"
                format: "date"
              tracks:
                $ref: '#/definitions/ChartTrackList'
  /v1/charts/out/:
    parameters:
    - in: "query"
      name: "vendor"
      required: true
      type: "string"
      enum: [spotify, apple]
    - in: "query"
      name: "market"
      required: true
      type: "string"
    - in: "query"
      name: "start"
      type: "integer"
    - in: "query"
      name: "end"
      type: "integer"
    - in: "query"
      name: "is_sony"
      type: "boolean"
    - in: "query"
      description: "Chart date, for Spotify only"
      name: "date"
      type: "string"
      format: "date"
    - in: "query"
      description: "Chart type, daily or weekly, for Spotify only"
      name: "type"
      type: "string"
      enum: [weekly, daily]
    - in: "query"
      name: "only_starred_tracks"
      required: false
      type: "boolean"
    - in: "query"
      name: "order_by"
      required: false
      type: "array"
      collectionFormat: multi
      items:
        type: "string"
        enum: [is_starred_track, position, moves, track_name, track_id, -is_starred_track, -position, -moves, -track_name, -track_id]
      default: []
    - in: "query"
      name: "fields"
      required: false
      type: "array"
      collectionFormat: multi
      items:
        type: "string"
        enum: [album_id, artist_id, is_re_enter, trends, image_url, artists, is_sony, is_starred, chart_date]
      default: []
    get:
      summary: "Returns set of chart tracks that moved out of the positions interval."
      produces:
      - "application/json"
      responses:
        200:
          description: "List of chart tracks."
          schema:
            type: "object"
            properties:
              chart_date:
                description: "Last data presence"
                type: "string"
                format: "date"
              tracks:
                $ref: '#/definitions/ChartTrackList'
  /v1/charts/moves/:
    parameters:
    - in: "query"
      name: "vendor"
      required: true
      type: "string"
      enum: [spotify, apple]
    - in: "query"
      name: "market"
      required: true
      type: "string"
    - in: "query"
      name: "change"
      type: "integer"
    - in: "query"
      name: "only_starred_tracks"
      required: false
      type: "boolean"
    - in: "query"
      name: "is_sony"
      type: "boolean"
    - in: "query"
      description: "Chart date, for Spotify only"
      name: "date"
      type: "string"
      format: "date"
    - in: "query"
      description: "Chart type, daily or weekly, for Spotify only"
      name: "type"
      type: "string"
      enum: [weekly, daily]
    - in: "query"
      name: "order_by"
      required: false
      type: "array"
      collectionFormat: multi
      items:
        type: "string"
        enum: [is_starred_track, position, moves, track_name, track_id, -is_starred_track, -position, -moves, -track_name, -track_id]
      default: []
    - in: "query"
      name: "fields"
      required: false
      type: "array"
      collectionFormat: multi
      items:
        type: "string"
        enum: [album_id, artist_id, is_re_enter, trends, image_url, artists, is_sony, is_starred, chart_date]
      default: []
    get:
      summary: "Returns set of chart tracks by absolute position change."
      produces:
      - "application/json"
      responses:
        200:
          description: "List of chart tracks."
          schema:
            type: "object"
            properties:
              chart_date:
                description: "Last data presence"
                type: "string"
                format: "date"
              tracks:
                $ref: '#/definitions/ChartTrackList'
  /v1/charts/additions/:
    parameters:
    - in: "query"
      name: "vendor"
      required: true
      type: "string"
      enum: [spotify, apple]
    - in: "query"
      name: "market"
      required: true
      type: "string"
    - in: "query"
      name: "only_starred_tracks"
      required: false
      type: "boolean"
    - in: "query"
      name: "is_sony"
      type: "boolean"
    - in: "query"
      description: "Chart date, for Spotify only"
      name: "date"
      type: "string"
      format: "date"
    - in: "query"
      description: "Chart type, daily or weekly, for Spotify only"
      name: "type"
      type: "string"
      enum: [weekly, daily]
    - in: "query"
      name: "order_by"
      required: false
      type: "array"
      collectionFormat: multi
      items:
        type: "string"
        enum: [is_starred_track, position, moves, track_name, track_id, -is_starred_track, -position, -moves, -track_name, -track_id]
      default: []
    - in: "query"
      name: "fields"
      required: false
      type: "array"
      collectionFormat: multi
      items:
        type: "string"
        enum: [album_id, artist_id, is_re_enter, trends, image_url, artists, is_sony, is_starred, chart_date]
      default: []
    - in: "query"
      name: "start"
      type: "integer"
    - in: "query"
      name: "end"
      type: "integer"
    get:
      summary: "Returns set of new chart tracks."
      produces:
      - "application/json"
      responses:
        200:
          description: "List of chart tracks."
          schema:
            type: "object"
            properties:
              chart_date:
                description: "Last data presence"
                type: "string"
                format: "date"
              tracks:
                $ref: '#/definitions/ChartTrackList'
  /v1/charts/removals/:
    parameters:
    - in: "query"
      name: "vendor"
      required: true
      type: "string"
      enum: [spotify, apple]
    - in: "query"
      name: "market"
      required: true
      type: "string"
    - in: "query"
      name: "only_starred_tracks"
      required: false
      type: "boolean"
    - in: "query"
      name: "is_sony"
      type: "boolean"
    - in: "query"
      description: "Chart date, for Spotify only"
      name: "date"
      type: "string"
      format: "date"
    - in: "query"
      description: "Chart type, daily or weekly, for Spotify only"
      name: "type"
      type: "string"
      enum: [weekly, daily]
    - in: "query"
      name: "order_by"
      required: false
      type: "array"
      collectionFormat: multi
      items:
        type: "string"
        enum: [is_starred_track, position, moves, track_name, track_id, -is_starred_track, -position, -moves, -track_name, -track_id]
      default: []
    - in: "query"
      name: "fields"
      required: false
      type: "array"
      collectionFormat: multi
      items:
        type: "string"
        enum: [album_id, artist_id, is_re_enter, trends, image_url, artists, is_sony, is_starred, chart_date]
      default: []
    - in: "query"
      name: "start"
      type: "integer"
    - in: "query"
      name: "end"
      type: "integer"
    get:
      summary: "Returns set of tracks that were removed from chart."
      produces:
      - "application/json"
      responses:
        200:
          description: "List of chart tracks."
          schema:
            type: "object"
            properties:
              chart_date:
                description: "Last data presence"
                type: "string"
                format: "date"
              tracks:
                $ref: '#/definitions/ChartTrackList'

  /charts/date-range/:
    parameters:
    - in: "query"
      name: "vendor"
      required: true
      type: "string"
      enum: [spotify, apple]
    - in: "query"
      name: "market"
      required: true
      type: "string"
    - in: "query"
      description: "Chart type, daily or weekly, for Spotify only"
      name: "type"
      type: "string"
      enum: [weekly, daily]
    get:
      summary: "Returns chart min/max possible dates."
      produces:
      - "application/json"
      responses:
        200:
          description: "Chart min/max possible dates."
          schema:
            type: "object"
            properties:
              min_date:
                type: "string"
                format: "date"
              max_date:
                type: "string"
                format: "date"

  /charts/summary/:
    parameters:
    - in: "query"
      name: "vendor"
      required: true
      type: "string"
      enum: [spotify, apple]
    - in: "query"
      name: "offset"
      type: "integer"
      description: The number of items to skip before starting to collect the result set
    - in: "query"
      name: "limit"
      type: "integer"
      description: The numbers of items to return
    - in: "query"
      name: "isrc"
      type: "string"
      description: ISRC
      required: true
    - in: "query"
      name: "search"
      type: "string"
      required: false
      description: "Search string value"
    get:
      summary: "Returns lists of charts summary for track."
      produces:
      - "application/json"
      responses:
        200:
          description: "List of chart tracks."
          schema:
            type: "object"
            properties:
              top_market:
                type: "string"
              count:
                type: "integer"
              previous:
                type: "string"
              next:
                type: "string"
              items:
                type: "array"
                items:
                  type: "object"
                  properties:
                    added_date:
                      type: "string"
                      format: "date"
                      description: Date when track was added to chart.
                    change:
                      type: "integer"
                      description: Track's position change within two latest dates.
                    country_code:
                      type: "string"
                    position:
                      type: "integer"
                    date:
                      type: "string"
                      format: "date"
                      description: Chart's update date.

  /charts/stats/:
    parameters:
      - in: "query"
        name: "vendor"
        type: "string"
        default: "spotify"
        enum: [spotify, apple]
      - in: "query"
        name: "market"
        type: "string"
        default: "global"
      - in: "query"
        name: "chart_type"
        type: "string"
        default: "daily"
        enum: [daily, weekly]
      - in: "query"
        name: "list_type"
        type: "string"
        default: "regional"
        enum: [regional, viral]
      - in: "query"
        name: "isrc"
        required: true
        type: "array"
        items:
          type: "string"
    get:
      summary: "Returns lists of chart tracks statistics like entry date or peak position."
      produces:
        - "application/json"
      responses:
        200:
          description: "List of chart tracks stats."
          schema:
            type: "array"
            items:
              type: "object"
              properties:
                current_position:
                  type: "integer"
                entry_date:
                  type: "string"
                  format: "date"
                isrc:
                  type: "string"
                peak_position:
                  type: "integer"

  /markets/:
    get:
      summary: 'Returns list of all available markets.'
      produces:
      - "application/json"
      responses:
        200:
          description: "List of markets."
          schema:
            type: "array"
            items:
              $ref: '#/definitions/Market'

  /job-categories/:
    get:
      summary: 'Returns list of all available job categories.'
      produces:
      - "application/json"
      responses:
        200:
          description: "List of job categories."
          schema:
            type: "array"
            items:
              $ref: '#/definitions/JobCategory'
    post:
      summary: 'Save selected job category to Auth0.'
      produces:
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        required: true
        schema:
          type: object
          properties:
            category:
              type: number
      responses:
        200:
          description: "status: 'OK'"
          schema:
            type: "object"
        400:
          description: 'Validation error.'

  /mobile-versions/:
    get:
      summary: "Returns latest saved into db versions data."
      parameters:
        - in: "query"
          name: "os"
          required: true
          type: "string"
          enum: [ios, android]
      produces:
        - "application/json"
      responses:
        200:
          description: "Return version data object."
          schema:
            type: "object"
            properties:
              os:
                type: string
              version:
                type: string
              created_at:
                type: string
              changelog:
                type: string

  /tracks-release-dates/:
    get:
      summary: "Returns tracks release date."
      parameters:
      - in: "query"
        name: "isrc"
        required: true
        type: "array"
        description: "List of tracks ISRC."
        items:
          type: "string"
      produces:
      - "application/json"
      responses:
        200:
          description: "Dictionary, ISRC to release date mapping."
          schema:
            type: "object"
            additionalProperties:
              type: "string"
            example:
              "AAA111111111": "2016-10-20"
              "AAA111111112": "2017-01-10"

  /visited-tracks/:
    get:
      summary: "Returns most visited tracks."
      parameters:
      - in: "query"
        name: "market"
        type: "string"
        description: "Market code, it is used to get is_sony flag"
      produces:
      - "application/json"
      responses:
        200:
          description: "List of objects containing most visited tracks."
          schema:
            type: "array"
            items:
              type: "object"
              properties:
                artist_name:
                  type: "string"
                id:
                  type: "string"
                name:
                  type: "string"
                artists:
                  type: "array"
                  items:
                    type: "string"
                vendor:
                  type: "string"
                visit_count:
                  type: "integer"

  /onboarding/:
    get:
      parameters:
      - in: "query"
        name: "client_type"
        required: false
        type: string
        enum: ['mobile', 'portal']
        default: 'portal'
      summary: "Returns fact of user first login."
      produces:
      - "application/json"
      responses:
        200:
          description: "Object with data of current user."
          schema:
            type: "object"
            properties:
              created_at:
                type: "string"
                format: "date-time"
              user_onboarding:
                type: "boolean"
    post:
      parameters:
      - in: "body"
        name: "body"
        schema:
          type: "object"
          properties:
            client_type:
              description: "Set the fact of user first login."
              type: string
              enum: ['mobile', 'portal']
              default: 'portal'
      produces:
      - "application/json"
      responses:
        200:
          description: "Object with data of current user."
          schema:
            type: "object"
            properties:
              created_at:
                type: "string"
                format: "date-time"
              user_onboarding:
                type: "boolean"

  /push-notifications/register-device/:
    post:
      summary: "Register mobile device token."
      produces:
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "Register mobile device token."
        required: true
        schema:
          type: object
          properties:
            token:
              type: "string"
      responses:
        201:
          description: "Token saved successfully."
        200:
          description: "User with this token is already saved"

  /push-notifications/unregister-device/:
    post:
      summary: "Unregister mobile device token."
      produces:
        - "application/json"
      parameters:
        - in: "body"
          name: "body"
          description: "Register mobile device token."
          required: true
          schema:
            type: object
            properties:
              token:
                type: "string"
      responses:
        200:
          description: "User device token has been inactivated"

  /push-notifications/:
    get:
      summary: "Get list of user's push messages."
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: "offset"
          type: "integer"
          description: The number of items to skip before starting to collect the result set
        - in: "query"
          name: "limit"
          type: "integer"
          description: The numbers of items to return
        - in: "query"
          name: "is_new"
          type: "boolean"
          description: Filter items by is_new flag
      responses:
        200:
          description: "List of push messages for user."
          schema:
            type: "object"
            properties:
              count:
                type: "integer"
              previous:
                type: "string"
              next:
                type: "string"
              items:
                type: "array"
                items:
                  type: "object"
                  properties:
                    id:
                      type: "integer"
                    title:
                      type: "string"
                    time_delta:
                      type: "integer"
                    message:
                      type: "string"
                    created_at:
                      type: "string"
                      format: "date-time"
                    track_name:
                      type: "string"
                    artist_name:
                      type: "string"
                    track_id:
                      type: "string"
                    topic:
                      type: "string"
                      enum: [additions, removals, major_moves]
                    target:
                      type: "string"
                    position:
                      type: "integer"
                    change:
                      type: "integer"

  /push-notifications/bulk/:
    put:
      summary: "Bulk update push messages."
      produces:
        - "application/json"
      parameters:
        - in: "body"
          name: "data"
          description: "Push message objects list"
          schema:
            type: "array"
            items:
              type: object
              properties:
                id:
                  type: "integer"
                is_new:
                  type: "boolean"
      responses:
        200:
          description: "Success."

  /push-notifications/{push_id}/:
    get:
      summary: "Get push message detail"
      produces:
        - "application/json"
      parameters:
        - in: "path"
          name: "push_id"
          description: "ID Push message"
          required: true
          type: "integer"
          format: "int64"
      responses:
        200:
          description: "Push message."
          schema:
            type: "object"
            properties:
                id:
                  type: "integer"
                title:
                  type: "string"
                time_delta:
                  type: "integer"
                message:
                  type: "string"
                created_at:
                  type: "string"
                  format: "date-time"
                track_name:
                  type: "string"
                artist_name:
                  type: "string"
                track_id:
                  type: "string"
                topic:
                  type: "string"
                  enum: [additions, removals, major_moves]
                target:
                  type: "string"
                position:
                  type: "integer"
                change:
                  type: "integer"

  /push-notifications/settings/:
    get:
      summary: "Get all notification settings."
      produces:
        - "application/json"
      responses:
        200:
          description: "Success."
          schema:
            type: "object"
            properties:
              items:
                type: "array"
                items:
                  type: "object"
                  properties:
                    id:
                      type: "string"
                    code:
                      type: "string"
                    enabled:
                      type: "boolean"
    post:
      summary: "Enable setting in user's notification settings"
      produces:
        - "application/json"
      parameters:
        - in: "body"
          name: "body"
          description: "ID of setting."
          required: true
          schema:
            type: object
            properties:
              id:
                type: "integer"
      responses:
        201:
          description: "Setting saved successfully."
    delete:
      summary: "Remove particular setting from user's notification settings."
      produces:
        - "application/json"
      parameters:
        - in: "body"
          name: "body"
          description: "ID of setting."
          required: true
          schema:
            type: object
            properties:
              id:
                type: "integer"
      responses:
        204:
          description: "Setting deleted from user's settings."

  /apple-music/track-top-playlists-history/:
    get:
      summary: "Get tracks top playlists history."
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: "tracks"
          required: true
          type: "array"
          description: "List of track ID."
          items:
            type: "integer"
        - in: "query"
          name: "market"
          description: "Market code."
          type: "string"
        - in: "query"
          name: "limit"
          description: "Max number of items."
          type: "integer"
        - in: "query"
          name: "image_size"
          description: "desirable size for playlist image"
          type: "integer"
      responses:
        200:
          description: "Tracks top playlists history."
          schema:
            type: "object"
            properties:
              playlists:
                type: "array"
                items:
                  type: "object"
                  properties:
                      id:
                        type: "string"
                      name:
                        type: "string"
                      streams:
                        type: "integer"
                      type:
                        type: "string"
                        enum: ["apple"]
                      tracks:
                        type: "array"
                        items:
                          type: "object"
                          properties:
                            first_date:
                              type: "string"
                              format: "date"
                            id:
                              type: "integer"
                            ids:
                              type: "array"
                              items:
                                type: "integer"
                            isrc:
                              type: "string"
                            name:
                              type: "string"
                            periods:
                              type: "array"
                              items:
                                type: "array"
                                items:
                                  type: "string"
                                  format: "date"

  /apple-music/track-playlists/:
    get:
      summary: "Get playlists data for track."
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: "isrc"
          required: true
          type: "string"
          description: "ISRC"
        - in: "query"
          name: "market"
          required: true
          description: "Market code."
          type: "string"
        - in: "query"
          name: "offset"
          type: "integer"
        - in: "query"
          name: "limit"
          type: "integer"
        - in: "query"
          name: "is_sony"
          type: "boolean"
          default: false
        - in: "query"
          name: "search"
          type: "string"
          description: "Search value."
          required: false
      responses:
        200:
          description: "Playlists data for track."
          schema:
            type: "object"
            properties:
              items:
                type: "array"
                items:
                  type: "object"
                  properties:
                    id:
                      type: "string"
                    name:
                      type: "string"
                    image_url:
                      type: "string"
                    position:
                      type: "integer"
                    country_code:
                      type: "string"
                    trend:
                      type: "integer"
                    changed_date:
                      type: "string"
              count:
                type: "integer"
              next:
                type: "string"
              previous:
                type: "string"

  /spotify/track-top-playlists-history/:
    get:
      summary: "Get tracks top playlists history."
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: "tracks"
          required: true
          type: "array"
          description: "List of track ID."
          items:
            type: "string"
        - in: "query"
          name: "market"
          description: "Market code."
          type: "string"
        - in: "query"
          name: "limit"
          description: "Max number of items."
          type: "integer"
      responses:
        200:
          description: "Tracks top playlists history."
          schema:
            type: "object"
            properties:
              playlists:
                type: "array"
                items:
                  type: "object"
                  properties:
                      id:
                        type: "string"
                      name:
                        type: "string"
                      streams:
                        type: "integer"
                      type:
                        type: "string"
                        enum: ["spotify"]
                      tracks:
                        type: "array"
                        items:
                          type: "object"
                          properties:
                            first_date:
                              type: "string"
                              format: "date"
                            id:
                              type: "string"
                            ids:
                              type: "array"
                              items:
                                type: "string"
                            isrc:
                              type: "string"
                            name:
                              type: "string"
                            periods:
                              type: "array"
                              items:
                                type: "array"
                                items:
                                  type: "string"
                                  format: "date"

  /spotify/track-playlists/:
    get:
      summary: "Get playlists data for track."
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: "isrc"
          required: true
          type: "string"
          description: "ISRC"
        - in: "query"
          name: "market"
          required: true
          description: "Market code."
          type: "string"
        - in: "query"
          name: "offset"
          type: "integer"
        - in: "query"
          name: "limit"
          type: "integer"
        - in: "query"
          name: "is_sony"
          type: "boolean"
          default: false
        - in: "query"
          name: "search"
          type: "string"
          description: "Search value."
          required: false
      responses:
        200:
          description: "Playlists data for track."
          schema:
            type: "object"
            properties:
              items:
                type: "array"
                items:
                  type: "object"
                  properties:
                    id:
                      type: "string"
                    name:
                      type: "string"
                    image_url:
                      type: "string"
                    country_code:
                      type: "string"
                    position:
                      type: "integer"
              count:
                type: "integer"
              next:
                type: "string"
              previous:
                type: "string"

  /spotify/track-playlists/trends/:
    get:
      summary: "Get trends for track playlists."
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: "isrc"
          required: true
          type: "string"
          description: "ISRC"
        - in: "query"
          name: "playlist_ids"
          required: true
          type: "string"
          description: "Playlist ID sequence separated by , "
      responses:
        200:
          description: "Dict {playlist_id: integer}."

  /v1/spotify/track-playlists/trends/:
    get:
      summary: "Get trends for track playlists."
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: "isrc"
          required: true
          type: "string"
          description: "ISRC"
        - in: "query"
          name: "playlist_ids"
          required: true
          type: "string"
          description: "Playlist ID sequence separated by , "
      responses:
        200:
          description: "Dict {playlist_id: {position: integer}}."

  /spotify/personalized-playlists/:
    get:
      summary: "Get list of personalized playlists by playlist IDs."
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: "playlist_ids"
          type: "array"
          required: true
          items:
            type: "string"
          description: "Set of playlist ID separated by comma."
      responses:
        200:
          description: "Set of personalized playlist ID."
          schema:
            type: "array"
            items:
              type: "string"

  /spotify/albums/{album_id}/:
    get:
      summary: "Get spotify album with is_sony flag and list of full track data."
      produces:
        - "application/json"
      parameters:
        - in: "path"
          name: "album_id"
          required: true
          type: "string"
          description: "Album ID"
        - in: "query"
          name: "market"
          type: "string"
          description: "Market code"
      responses:
        200:
          description: "Album data with is_sony flag and list of tracks."

  /spotify/track-demographics/:
    get:
      summary: "Get list streams demographic data by isrc"
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: "isrc"
          required: true
          type: "array"
          items:
            type: "string"
          description: "List of isrc to select by"
        - in: "query"
          name: "start"
          required: true
          type: "string"
          format: "date"
          description: "Start date of selected period"
        - in: "query"
          name: "end"
          required: true
          type: "string"
          format: "date"
          description: "End date of selected period"
        - in: "query"
          name: "market"
          required: false
          type: "string"
        - in: "query"
          name: "compact"
          required: false
          type: "boolean"
          description: "Flag to get response in compact format."
      responses:
        200:
          description: "Set of personalized playlist ID."
          schema:
            type: "array"
            items:
              $ref: '#/definitions/DemographicItem'

  /spotify/tracks/playlists-stats/:
    get:
      summary: "Get list streams demographic data by isrc"
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: "isrc"
          required: true
          type: "array"
          items:
            type: "string"
          description: "List of tracks ISRC"
        - in: "query"
          name: "dates"
          required: true
          type: "array"
          items:
            type: "string"
            format: "date"
          description: "List of dates to compare playlists count"
        - in: "query"
          name: "categories"
          type: "array"
          items:
            type: "integer"
          default:
          - 1
          - 5
          description: "List of playlist categories to get"
      responses:
        200:
          description: "Set of tracks playlists stats."
          schema:
            type: "array"
            items:
              type: "object"
              properties:
                isrc:
                  type: "string"
                current:
                  type: "array"
                  items:
                    type: "object"
                    properties:
                      category_id:
                        type: "integer"
                      playlist_count:
                        type: "integer"
                history:
                  type: "array"
                  items:
                    type: "object"
                    properties:
                      category_id:
                        type: "integer"
                      added:
                        type: "integer"
                      removed:
                        type: "integer"
                      date:
                        type: "string"
                        format: "date"

definitions:
  Artist:
    type: object
    properties:
      id:
        description: "Artist id"
        type: string
      name:
        description: "Artist name"
        type: string
        default: ""
      uri:
        description: "Artist uri"
        type: string
        default: ""
  DemographicItem:
    type: object
    properties:
      isrc:
        type: string
      date:
        type: string
        format: "date"
      market:
        type: string
      female_0_17:
        type: integer
      female_18_22:
        type: integer
      female_23_27:
        type: integer
      female_28_34:
        type: integer
      female_35_44:
        type: integer
      female_45_59:
        type: integer
      female_60_150:
        type: integer
      female_unknown:
        type: integer
      male_0_17:
        type: integer
      male_18_22:
        type: integer
      male_23_27:
        type: integer
      male_28_34:
        type: integer
      male_35_44:
        type: integer
      male_45_59:
        type: integer
      male_60_150:
        type: integer
      male_unknown:
        type: integer
      neutral_0_17:
        type: integer
      neutral_18_22:
        type: integer
      neutral_23_27:
        type: integer
      neutral_28_34:
        type: integer
      neutral_35_44:
        type: integer
      neutral_45_59:
        type: integer
      neutral_60_150:
        type: integer
      neutral_unknown:
        type: integer
      unknown_0_17:
        type: integer
      unknown_18_22:
        type: integer
      unknown_23_27:
        type: integer
      unknown_28_34:
        type: integer
      unknown_35_44:
        type: integer
      unknown_45_59:
        type: integer
      unknown_60_150:
        type: integer
      unknown_unknown:
        type: integer
    required:
      - isrc
      - date
      - market
      - female_0_17
      - female_18_22
      - female_23_27
      - female_28_34
      - female_35_44
      - female_45_59
      - female_60_150
      - female_unknown
      - male_0_17
      - male_18_22
      - male_23_27
      - male_28_34
      - male_35_44
      - male_45_59
      - male_60_150
      - male_unknown
      - neutral_0_17
      - neutral_18_22
      - neutral_23_27
      - neutral_28_34
      - neutral_35_44
      - neutral_45_59
      - neutral_60_150
      - neutral_unknown
      - unknown_0_17
      - unknown_18_22
      - unknown_23_27
      - unknown_28_34
      - unknown_35_44
      - unknown_45_59
      - unknown_60_150
      - unknown_unknown
  ChartTrack:
    type: object
    properties:
      id:
        type: string
      name:
        description: "Track name."
        type: string
      artist:
        description: "Artist name."
        type: string
      image_url:
        description: "Track image."
        type: string
        default: ""
      position:
        description: "Track position in chart."
        type: integer
      change:
        description: "Track position change."
        type: integer
      chart_date:
        description: "Current chart date"
        type: string
        format: date
        default: ""
      is_sony:
        description: "Is sony release or not."
        type: boolean
        default: false
      is_new:
        description: "Is new entry or not."
        type: boolean
        default: false
      is_re_enter:
        description: "Is the latest chart new entry was in charts previously."
        type: boolean
        default: false
      trend:
        description: "It is change or (change - 1000) for is_new = True, is used as sort order."
        type: integer
        default: 0
      isrc:
        description: "Track isrc"
        type: string
        default: ""
      streams:
        description: "Number of streams"
        type: integer
      artist_id:
        description: "Artist id"
        type: string
      album_id:
        description: "Album id"
        type: string
      is_starred_track:
        description: "Is track starred"
        type: boolean
        default: false
      artists:
        type: array
        items:
          $ref: '#/definitions/Artist'
        default: []
    required:
      - id
      - name
      - artist
      - isrc
      - image_url
      - position
      - change
      - chart_date
      - is_sony
      - is_new
      - is_re_enter
  ChartTrackList:
    type: array
    items:
      $ref: '#/definitions/ChartTrack'
  JobCategory:
    type: object
    properties:
      id:
        type: number
      name:
        type: string
        description: "Job category name."
    required:
      - id
      - name
  Market:
    type: object
    properties:
      id:
        type: number
      name:
        type: string
        description: "Market name."
      code:
        type: string
        description: "Market country code"
    required:
     - id
     - name
     - code
  ComparisonTrackList:
    type: "array"
    items:
      type: "object"
      properties:
        spotify_id:
          type: "string"
        apple_id:
          type: "integer"
        isrc:
          type: "string"
        is_sony:
          type: "boolean"
        data:
          type: "object"
          description: "Spotify API track info"