swagger: '2.0'
info:
  title: Orchard OWS analytics API
  version: v1
host: qa-ows-analytics.theorchard.io
schemes:
  - https
consumes:
  - application/json
produces:
  - application/json
tags:
  - name: Analytics Overview
  - name: Analytics Streaming Insights
  - name: Internal
    description: Service endpoints not used by the frontend app
security:
  - grass_account_type: []
    grass_account_id:  []
paths:
  '/hello/':
    get:
      tags:
        - Internal
      summary: Hello World health check
      produces:
        - text/plain
      security: []
      responses:
        200:
          description: Healthcheck passed successfully
          schema:
            type: string
            example: 'Hello World!'
  '/':
    get:
      summary: Get all analytics filtered by user-supplied params
      description: |
        This endpoint is for analytics requests
        smaller than 1 year worth of data.
      parameters:
        - name: from_date
          in: query
          type: string
          required: true
          example: '2017-05-01'
          format: date
          description: 'Date in YYYY-MM-DD format'
        - name: to_date
          in: query
          type: string
          required: true
          example: '2017-05-02'
          format: date
          description: 'Date in YYYY-MM-DD format'
        - name: transaction_types
          in: query
          type: string
          example: 'CA,SR'
          format: string
          description: 'Comma delimited list of transaction type codes.'
        - name: format
          in: query
          type: string
          enum: ['mobile']
          format: string
          description: 'Flag if mobile-formatted response'
      tags:
        - Analytics Overview
      responses:
        200.1:
          description: 'HTTP 200 OK, standard format'
          schema:
            type: object
            properties:
              stats:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/definitions/Transaction'
        200.2:
          description: 'HTTP 200 OK, mobile format'
          schema:
            type: object
            properties:
              stats:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/definitions/TransactionMobileFormat'
        400:
          examples:
            validation_error:
              code: validation_error
              message: Invalid date range.
          description: |
            Request parameters validation failure
  '/all/':
    get:
      tags:
        - Analytics Overview
      deprecated: true
      summary: Please, use root endpoint instead
      description: Schema is the same as in the root endpoint
      responses:
        200:
          description: OK
  '/{entityType}/{entityId}/':
    get:
      tags:
        - Analytics Overview
      parameters:
        - name: entityType
          in: path
          description: |
            The type of entity in Dynamodb.
            It is used to create the key
          required: true
          type: string
          enum: ['label', 'subaccount', 'album']
        - name: entityId
          description: The id of an entity
          in: path
          required: true
          type: string
          example: '33'
        - name: from_date
          in: query
          type: string
          required: true
          example: '2017-05-01'
          format: date
          description: 'Date in YYYY-MM-DD format'
        - name: to_date
          in: query
          type: string
          required: true
          example: '2017-05-02'
          format: date
          description: 'Date in YYYY-MM-DD format'
        - name: transaction_types
          in: query
          type: string
          example: 'CA,SR'
          format: string
          description: 'Comma delimited list of transaction type codes.'
        - name: format
          in: query
          type: string
          enum: ['mobile']
          format: string
          description: 'Flag if mobile-formatted response'
      responses:
        200.1:
          description: 'HTTP 200 OK, standard format'
          schema:
            type: object
            properties:
              stats:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/definitions/Transaction'
        200.2:
          description: 'HTTP 200 OK, mobile format'
          schema:
            type: object
            properties:
              stats:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/definitions/TransactionMobileFormat'
        400.1:
          produces:
            - text/html
          description: Invalid params of the request
        400.2:
          description:
            DynamoDB error
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  $ref: '#/definitions/DynamoError'
  '/stream-charts/':
    get:
      tags:
        - Analytics Streaming Insights
      summary: Get source of streams charts for a vendor
      description: Vendor is determined by auth credentials
      parameters:
        - name: Grass-Account-Type
          description: Grass account type. Provided by ows-grass proxy in QA/Prod.
          enum:
            - vendor
            - subaccount
          in: header
          type: string
          required: true
        - name: Grass-Account-Id
          description: Grass account id. Provided by ows-grass proxy in QA/Prod.
          in: header
          pattern: ^\d+$
          type: string
          required: true
        - name: from_date
          in: query
          type: string
          required: true
          example: '2017-05-01'
          format: date
          description: 'Date in YYYY-MM-DD format'
        - name: to_date
          in: query
          type: string
          required: true
          example: '2017-06-01'
          format: date
          description: 'Date in YYYY-MM-DD format'
        - name: stores
          in: query
          type: string
          required: true
          format: string
          description: |
            Comma-delimited list of store ids
            Apple Music: 1
            Spotify: 286
          example: '1,286'
        - name: limit
          in: query
          type: integer
          default: 500
          description: 'Max number of entities of the responce'
        - name: isrcs
          in: query
          type: string
          required: false
          format: string
          description: |
            Comma-delimited list of the International Standard Recording Codes.
            This feature is in development and not currently functional.
          example: USRZR0907107,USRZR0907108,USRZR0907109
        - name: artist_ids
          in: query
          type: string
          required: false
          format: string
          description: |
           Comma-delimited list of artist ids
          example: '29140,29142,29163'
      responses:
        200:
          description: 'HTTP 200 OK'
          schema:
            $ref: '#/definitions/StreamingInsight'
        400:
          examples:
            validation_error:
              code: validation_error
              message: Invalid date range.
          description: |
            Request parameters validation failure
  '/playlist-placements/':
    get:
      tags:
        - Analytics Streaming Insights
      summary: Get playlist placements data within a timeframe for a vendor
      description: Vendor is determined by auth credentials
      parameters:
        - name: Grass-Account-Type
          description: Grass account type. Provided by ows-grass proxy in QA/Prod.
          enum:
            - vendor
            - subaccount
          in: header
          type: string
          required: true
        - name: Grass-Account-Id
          description: Grass account id. Provided by ows-grass proxy in QA/Prod.
          in: header
          pattern: ^\d+$
          type: string
          required: true
        - name: from_date
          in: query
          type: string
          required: true
          example: '2017-05-01'
          format: date
          description: 'Date in YYYY-MM-DD format'
        - name: to_date
          in: query
          type: string
          required: true
          example: '2017-06-01'
          format: date
          description: 'Date in YYYY-MM-DD format'
        - name: stores
          in: query
          type: string
          required: True
          format: string
          description: |
            Comma delimited list of store ids
            Apple Music: 1
            Spotify: 286
          example: '1,286'
        - name: limit
          in: query
          type: integer
          default: 500
          description: 'Max number of response records'
        - name: artist_ids
          in: query
          type: string
          required: false
          format: string
          description: |
           Comma-delimited list of artist ids
          example: '29140,29142,29163'
        - name: isrcs
          in: query
          type: string
          required: false
          format: string
          description: |
            Comma-delimited list of the International Standard Recording Codes.
            This feature is in development and not currently functional.
          example: USRZR0907107,USRZR0907108,USRZR0907109
      responses:
        200:
          description: 'HTTP 200 OK'
          schema:
            $ref: '#/definitions/PlaylistPlacement'
        400:
          examples:
            validation_error:
              code: validation_error
              message: Invalid date range.
          description: |
            Request parameters validation failure
  '/playlist-metadata/':
    get:
      tags:
        - Analytics Streaming Insights
      parameters:
        - name: playlist_links
          description: Links to individual playlists for fetching metadata. Add multiple parameters for multiple playlists.
          in: query
          required: true
          type: array
          collectionFormat: multi
          example: [https://open.spotify.com/playlist/37i9dQZF1DX153gOfbCM2i, https://open.spotify.com/playlist/2pi9dQZF1DX8CwbNGNKurt]
          items:
            type: string
      responses:
        200:
          description: OK
          produces:
            - application/json
          schema:
            $ref:
              '#/definitions/PlaylistMetadata'
        400.1:
          description: Bad request - possiblity missing playlist_links param(s)
          produces:
            - text/html
        400.2:
          description: Returned when links have unsupported formats.
          produces:
            - text/html
          example: Some links have unsupported format.
        400.3:
          description: Returned when there is an API error or URI is invalid
          produces:
            - application/json
          schema:
            $ref:
              '#definitions/ServiceError'
  '/demographic_insights/':
    get:
      tags:
        - Analytics Demographic Insights
      summary: Get demographic insights data for a vendor
      description: Vendor is determined by auth credentials
      parameters:
        - name: from_date
          in: query
          type: string
          required: true
          example: '2017-05-01'
          format: date
          description: Date in YYYY-MM-DD format
        - name: to_date
          in: query
          type: string
          required: true
          example: '2017-06-01'
          format: date
          description: Date in YYYY-MM-DD format
        - name: stores
          in: query
          type: string
          required: True
          format: string
          description: |
            Comma delimited list of store ids
            Apple Music: 1
            Spotify: 286
          example: '1,286'
        - name: isrcs
          in: query
          type: string
          required: false
          format: string
          description: |
            Comma-delimited list of the International Standard Recording Codes.
          example: 'USRZR0907107'
        - name: artist_ids
          in: query
          type: string
          required: false
          format: string
          description: |
           Comma-delimited list of artist ids
          example: '29140,29142,29163'
      responses:
        200:
          description: Successful request
          schema:
            $ref: '#/definitions/DemographicInsights'
        204:
          description: No data returned for given store and date range
        400:
          examples:
            validation_error:
              code: validation_error
              message: Invalid date range.
          description: |
            Request parameters validation failure
  '/geographic-insights-by-territory':
    get:
      tags:
        - Analytics Geographic Insights
      summary: Get geographic insights data by territory
      parameters:
        - name: Grass-Account-Type
          description: Grass account type. Provided by ows-grass proxy in QA/Prod.
          enum:
            - vendor
            - subaccount
          in: header
          type: string
          required: true
        - name: Grass-Account-Id
          description: Grass account id. Provided by ows-grass proxy in QA/Prod.
          in: header
          type: string
          required: true
        - name: from_date
          in: query
          type: string
          required: true
          example: '2017-05-01'
          format: date
          description: 'Date in YYYY-MM-DD format'
        - name: to_date
          in: query
          type: string
          required: true
          example: '2018-01-01'
          format: date
          description: 'Date in YYYY-MM-DD format'
        - name: artist_ids
          in: query
          type: string
          required: false
          format: string
          description: 'Comma-delimited list.'
          example: 123,456,789
        - name: stores
          in: query
          type: string
          required: False
          format: string
          description: |
            Comma delimited list of store ids
            Apple Music: 1
            Spotify: 286
          example: '1,286'
        - name: isrcs
          in: query
          type: string
          required: false
          format: string
          description: 'Comma-delimited list'
          example: USRZR0907107,USRZR0907108,USRZR0907109
        - name: territory_code
          in: query
          type: string
          required: false
          example: 'FR'
          format: string
          description: 'Territory code'
      responses:
        200:
          description: Successful request
          schema:
            type: array
            example:
              [
                {
                  "territory_code": "US",
                  "unique_listeners": 123,
                  "number_of_streams": 456
                },
                {
                  "territory_code": "FR",
                  "unique_listeners": 321,
                  "number_of_streams": 654
                }
              ]
        204:
          description: No data returned for given properties
        400:
          examples:
            validation_error:
              code: validation_error
              message: Parameter start_date & end_date is required.
          description: |
            Request parameters validation failure
  '/geographic-insights-by-region':
    get:
      tags:
        - Analytics Geographic Insights
      summary: Get geographic insights data by region
      parameters:
        - name: Grass-Account-Type
          description: Grass account type. Provided by ows-grass proxy in QA/Prod.
          enum:
            - vendor
            - subaccount
          in: header
          type: string
          required: true
        - name: Grass-Account-Id
          description: Grass account id. Provided by ows-grass proxy in QA/Prod.
          in: header
          type: string
          required: true
        - name: from_date
          in: query
          type: string
          required: true
          example: '2017-05-01'
          format: date
          description: 'Date in YYYY-MM-DD format'
        - name: to_date
          in: query
          type: string
          required: true
          example: '2018-01-01'
          format: date
          description: 'Date in YYYY-MM-DD format'
        - name: artist_ids
          in: query
          type: string
          required: false
          format: string
          description: 'Comma-delimited list.'
          example: 123,456,789
        - name: stores
          in: query
          type: string
          required: False
          format: string
          description: |
            Comma delimited list of store ids
            Apple Music: 1
            Spotify: 286
          example: '1,286'
        - name: isrcs
          in: query
          type: string
          required: false
          format: string
          description: 'Comma-delimited list'
          example: USRZR0907107,USRZR0907108,USRZR0907109
      responses:
        200:
          description: Successful request
          schema:
            type: array
            example:
              [
                {
                    'region_name': 'Provence-Alpes',
                    'region_code': 'FR-U',
                    'territory_code': 'FR',
                    'unique_listeners': 123,
                    'number_of_streams': 321
                },
                {
                    'region_name': 'New-York',
                    'region_code': '501',
                    'territory_code': 'US',
                    'unique_listeners': 456,
                    'number_of_streams': 654
                }
              ]
        204:
          description: No data returned for given properties
        400:
          examples:
            validation_error:
              code: validation_error
              message: Parameter start_date & end_date is required.
          description: |
            Request parameters validation failure
  '/geographic-orchard-regions':
    get:
      tags:
        - Analytics Geographic Insights
      summary: Get geographic orchard regions
      parameters:
        - name: Grass-Account-Type
          description: Grass account type. Provided by ows-grass proxy in QA/Prod.
          enum:
            - vendor
            - subaccount
          in: header
          type: string
          required: true
        - name: Grass-Account-Id
          description: Grass account id. Provided by ows-grass proxy in QA/Prod.
          in: header
          type: string
          required: true
      responses:
        200:
          description: Successful request
          schema:
            type: array
            example:
              [
                {
                    'territory_code': 'FR',
                    'region_code': Null,
                    'region_name': 'Provence-Alpes'
                },
                {
                    'territory_code': 'GB',
                    'region_code': 'GB-LDN',
                    'region_name': 'London'
                }
              ]
        204:
          description: No data returned
  '/geographics-latest-date':
    get:
      tags:
        - Analytics Geographic Insights
      summary: Get geographics orchard latest available date.
      parameters:
        - name: Grass-Account-Type
          description: Grass account type. Provided by ows-grass proxy in QA/Prod.
          enum:
            - vendor
            - subaccount
          in: header
          type: string
          required: true
        - name: Grass-Account-Id
          description: Grass account id. Provided by ows-grass proxy in QA/Prod.
          in: header
          type: string
          required: true
      responses:
        200:
          description: Successful request
          schema:
            type: object
            example:
              {
                'last_activity_date': '2018-04-30'
              }
  '/top-tracks':
    get:
      summary: Get the top tracks for a label
      description: Returns a list of highest streaming tracks (by ISRC) for a given label.
      parameters:
        - name: Grass-Account-Type
          description: Grass account type. Provided by ows-grass proxy in QA/Prod.
          enum:
            - vendor
            - subaccount
          in: header
          type: string
          required: true
        - name: Grass-Account-Id
          description: Grass account id. Provided by ows-grass proxy in QA/Prod.
          in: header
          type: string
          required: true
      responses:
        200:
          description: 'HTTP 200 OK'
          schema:
            properties:
              items:
                type: array
                items:
                  type: object
                  properties:
                    isrc:
                      type: string
                      example: 'US53Q1200099'
                      description: International Standard Recording Code
                    trackName:
                      type: string
                      example: 'Frozen Pines'
                      description: Title of the track
                    artistName:
                      type: string
                      example: 'Lord Huron'
                      description: Primary artist for most recent product relating to the track
                    streams:
                      type: integer
                      example: 2430
                      description: Total number of streams for this track in the last 7 days
                    growthPercentage:
                      type: number
                      example: 12.4
                      description: (current streams - past streams) / past streams
                    imageLocation:
                      type: string
                      example: 'https://images.theorchard.io/product/large_cover/49c461c020422c4ab37860bd29e27c64.jpg'
                      description: Url for serving image via orchard images server
        400:
          examples:
            validation_error:
              code: bad_grass_request_error
              message: 'Missing Grass Headers'
          description: Request missing required grass headers
securityDefinitions:
  grass_account_type:
    type: "apiKey"
    name: "Grass-Account-Type"
    in: "header"
  grass_account_id:
    type: "apiKey"
    name: "Grass-Account-Id"
    in: "header"
definitions:
  Transaction:
    type: object
    properties:
      title:
        type: string
        example: 'Audio UGC Matches'
      stat_id:
        type: integer
        example: 33
      sequence_id:
        type: integer
        example: 33
      object_id:
        type: integer
        example: 33
      activities:
        type: integer
        example: 214
      source_type:
        type: string
        enum: ['store_ids', 'social_media_ids']
      transaction_type_id:
        type: integer
        example: 33
      data_scope:
        type: object
        properties:
          mark:
            type: string
            enum: ['month']
          point:
            type: string
            enum: ['day']
          zebra:
            type: string
            enum: ['week']
      lines:
        type: array
        items:
          type: object
          properties:
            title:
              type: string
              example: 'Audio UGC Matches'
            all_line_activities:
              type: integer
              example: 214
            name:
              type: string
              example: 'Audio UGC Matches'
            activities_paid:
              type: integer
              example: 0
            display_date:
              type: string
              format: date
              example: '2017-05-01'
            total_reported_sales_count:
              type: array
              items:
                type: array
                items:
                  type: integer
              example: [[1493596800, 2], [1493683200, 100]]
            activities:
              type: integer
              example: 214
            transaction_type_id:
              type: integer
              example: 33
            all_line:
              type: boolean
            transaction_type_abbr:
              $ref: '#/definitions/TransactionAbbr'
  TransactionMobileFormat:
    type: object
    properties:
      transaction_abbr:
        $ref: '#/definitions/TransactionAbbr'
      transaction_name:
        type: string
        example: 'Video Download Purchases'
      series:
        type: array
        items:
          type: array
          items:
            type: integer
        example: [[1493596800, 2], [1493683200, 100]]
      total_units:
        type: integer
        example: 6
      sequence_id:
        type: integer
        example: 12
  DynamoError:
    type: object
    properties:
      message:
        type: string
        example: 'Requested resource not found: Table: tablename not found'
  TransactionAbbr:
    description: Possible transaction type codes
    type: string
    enum: [
      'CA', 'SR', 'RC', 'DR', 'RB', 'UA', 'UT', 'UV', 'AV', 'AS', 'DV',
      'RD', 'TL', 'VB', 'VR', 'SV', 'TR', 'DT', 'TD', 'SE', 'MV',
      'DA', 'RV', 'PR', 'NR', 'CL', 'TA', 'VS', 'US', 'VU', 'S',
      'CV', 'CAV', 'AEA', 'AEV', 'MT', 'FFA', 'FFR', 'FEI'
    ]
  Placement:
    type: object
    properties:
      artist:
        type: string
        example: 'Belvedere'
        description: 'Artist name. Not returned for /playlist-placements/<isrc>'
      artist_id:
        type: integer
        example: 12345
        description: 'Unique artist ID'
      date_added:
        type: string
        example: '2017-04-01'
        format: date
        description: 'Date of addition to playlist. In YYYY-MM-DD format'
      isrc:
        type: string
        example: 'CAZ4W1600001'
        description: 'isrc of track. Not returned for /playlist-placements/<isrc>'
      labelid:
        type: integer
        example: 6971
        description: 'Current labelid'
      playlist_link:
        type: string
        example: 'https://music.amazon.com/playlists/B073DXLTRP'
        description: 'Placement playlist link'
      order_number:
        type: string
        example: '1'
        description: 'Rank based on # of streams for this track in playlist'
      storeid:
        type: integer
        example: 286
        description: 'Store id of playlist source'
      streams:
        type: integer
        example: 10516
        description: 'Total # of streams for this track in timeframe'
      track_title:
        type: string
        example: 'Bayside'
        description: 'Name of track. Not returned for /playlist-placements/<isrc>'
      upc:
        type: string
        example: '191773002763'
        description: 'upc of track. Not returned for /playlist-placements/<isrc>'
  PlaylistPlacement:
    type: object
    properties:
      items:
        type: array
        items:
          $ref: '#/definitions/Placement'
      total:
        type: integer
        description: 'Total number of placements in response'
  StreamingDayTotals:
    type: object
    properties:
      date:
        type: string
        example: '2017-05-01'
        format: date
        description: 'Date in YYYY-MM-DD format'
      overall_number_of_streams:
        type: integer
        example: 633917
      streams_from_collection:
        type: integer
        example: 349374
      streams_from_active_discovery:
        type: integer
        example: 92833
      streams_from_passive_discovery:
        type: integer
        example: 191710
  StreamingInsight:
    type: object
    properties:
      overall_number_of_streams:
        type: integer
        example: 20458665
      streams_from_collection:
        type: integer
        example: 10962503
      streams_from_collection_pct:
        type: integer
        example: 54
      streams_from_active_discovery:
        type: integer
        example: 3131213
      streams_from_active_discovery_pct:
        type: integer
        example: 15
      streams_from_passive_discovery:
        type: integer
        example: 6364949
      streams_from_passive_discovery_pct:
        type: integer
        example: 31
      items:
        type: array
        items:
          $ref:
            '#/definitions/StreamingDayTotals'
  GenderBreakdown:
    type: object
    properties:
      women_percentage:
        type: integer
        example: 50
        description: Percentage of streams by women
      men_percentage:
        type: integer
        example: 49
        description: Percentage of streams by men
      unknown_percentage:
        type: integer
        example: 1
        description: Percentage of streams by unknown gender
      women_streams_number:
        type: integer
        example: 2500
        description: Number of streams by women
      men_streams_number:
        type: integer
        example: 2450
        description: Number of streams by men
      unknown_streams_number:
        type: integer
        example: 50
        description: Number of streams by unknown gender
      streams_number:
        type: integer
        example: 5000
        description: Total number of streams
  AgeBreakdown:
    type: object
    properties:
      age_group:
        type: string
        example: '35-44'
        description: Age group
      women_percentage:
        type: integer
        example: 50
        description: Percentage of overall streams by women in age group
      men_percentage:
        type: integer
        example: 50
        description: Percentage of overall streams by men in age group
      all_percentage:
        type: integer
        example: 100
        description: Percentage of overall streams in age group
      women_streams_number:
        type: integer
        example: 2500
        description: Number of streams by women in age group
      men_streams_number:
        type: integer
        example: 2500
        description: Number of streams by men in age group
      all_streams_number:
        type: integer
        example: 5000
        description: Number of streams in age group
  TopAudiences:
    type: object
    properties:
      gender:
        type: string
        example: 'women'
        description: Gender
      age_group:
        type: string
        example: '35-44'
        description: Age group
      percentage:
        type: integer
        example: 100
        description: Percentage given gender-age cohort represents among top audiences
      total_streams_number:
        type: integer
        example: 2500
        description: Number of streams by cohort
  DemographicInsights:
    type: object
    properties:
      gender_breakdown:
        type: object
        $ref: '#/definitions/GenderBreakdown'
        description: Listener data broken down by gender
      age_breakdown:
        type: array
        items:
          $ref: '#/definitions/AgeBreakdown'
        description: Listener data broken down by age
      top_audiences:
        type: array
        items:
          $ref: '#/definitions/TopAudiences'
        description: Data about gender-age cohorts with most streams
  PlaylistMetadata:
    type: array
    items:
      type: object
      properties:
        status_code:
          type: integer
          example: 200
          description: HTTP status code. Equals to 200 if the playlist was found. 404 if the playlist wasn't found. 429 - Store API throttling, 504 - Gateway Timeout.
        playlist_link:
          type: string
          example: http://open.spotify.com/playlist/37324HS271
          description: Requested playlist link
        display_link:
          type: string
          example: http://open.spotify.com/user/spotify/playlist/37324HS271
          description: Actual link to the playlist (Spotify only)
        playlist_title:
          type: string
          example: "All '50s"
          description: Store playlist title
        playlist_author:
          type: string
          example: "Amazon Unlimited"
          description: Store playlist author
        followers:
          type: integer
          example: 1581384
          description: Number of playlist followers (Spotify only)
        image:
          type: string
          example: https://i.scdn.co/image/fsdkj28dsk229
          description: Playlist image link (Spotify and Apple Music only)
  ServiceError:
    type: object
    properties:
      code:
        type: string
        example: some_error_code
      message:
        type: string
        example: Some error message