swagger: "2.0" info: version: 1.0.0 title: API Specifications schemes: - https host: qa-ows-playlist.theorchard.io paths: /hello/: get: summary: Check the health of the application. responses: 200: description: 200 OK examples: application/json: { "status": "ok" } /placements: get: summary: Get placements of a song or artist 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: sort_key type: string description: The key according to which to sort the results by. - in: query name: sort_direction type: string description: The direction according to which to sort the result by according to `sort_key`. - in: query name: min_followers type: integer description: The minimum number of followers a playlist should have in the placements. - in: query name: playlist_appearances type: string description: Whether the placements are for `current` or `past`. - in: query name: streams_country type: array collectionFormat: multi items: type: string description: The countries for which stream numbers are fetched. - in: query name: store_id type: array collectionFormat: multi items: type: string description: The ids of the store for which playlists are fetched. - in: query name: playlist_type type: array collectionFormat: multi items: type: string description: The types of playlists which are fetched. - in: query name: curator_country type: array collectionFormat: multi items: type: string description: The country of curator from which the playlist belong to. - in: query name: distributor type: array collectionFormat: multi items: type: string description: The distributor of the song. Possible values are `theorchard` or `sme` - in: query name: isrc type: string description: The isrc for which placements are to be fetched. Either `isrc` or `global_participant_id` is required in the query params - in: query name: global_participant_id type: string description: The participant id for which placements are to be fetched. Either `isrc` or `global_participant_id` is required in the query params responses: 200: description: Array of Placements object schema: $ref: '#/definitions/Placements' 401: description: Access denied when user is unauthorised 403: description: Access denied when user is authenticated but is forbidden from accessing resource /placements_count: get: summary: Get number of placements of a song or artist parameters: - in: query name: min_followers type: integer description: The minimum number of followers a playlist should have in the placements. - in: query name: playlist_appearances type: string description: Whether the placements are for `current` or `past`. - in: query name: streams_country type: array collectionFormat: multi items: type: string description: The countries for which stream numbers are fetched. - in: query name: store_id type: array collectionFormat: multi items: type: string description: The ids of the store for which playlists are fetched. - in: query name: playlist_type type: array collectionFormat: multi items: type: string description: The types of playlists which are fetched. - in: query name: curator_country type: array collectionFormat: multi items: type: string description: The country of curator from which the playlist belong to. - in: query name: distributor type: array collectionFormat: multi items: type: string description: The distributor of the song. Possible values are `theorchard` or `sme` - in: query name: isrc type: string description: The isrc for which placements are to be fetched. Either `isrc` or `global_participant_id` is required in the query params - in: query name: global_participant_id type: string description: The participant id for which placements are to be fetched. Either `isrc` or `global_participant_id` is required in the query params responses: 200: description: Number of placements for a song or artist schema: $ref: '#/definitions/PlacementsCount' 401: description: Access denied when user is unauthorised 403: description: Access denied when user is authenticated but is forbidden from accessing resource /playlist/{store_playlist_id}/placement/{isrc}: get: summary: Get single placement in a playlist for a song parameters: - in: path name: store_playlist_id type: string required: true description: Id of playlist in the store - in: path name: isrc type: string required: true description: Global identifier for a song - in: query name: store_id type: integer description: Id of the store for which playlist is requested. This query parameter is required. - in: query name: storefront type: string description: For apple music playlist a storefront is required with each playlist to disambiguiate - in: query name: streams_country type: array collectionFormat: multi items: type: string description: The countries for which stream numbers are fetched. - in: query name: distributor type: array collectionFormat: multi items: type: string description: The distributor of the song. Possible values are `theorchard` or `sme` responses: 200: description: A Placements object schema: $ref: '#/definitions/Placements' 401: description: Access denied when user is unauthorised 403: description: Access denied when user is authenticated but is forbidden from accessing resource /placements/recent: get: summary: Get recent placements for a label or employee parameters: - in: query name: distributor type: array collectionFormat: multi items: type: string description: The distributor of the song. Possible values are `theorchard` or `sme` - in: query name: label_id type: array collectionFormat: multi items: type: string description: The label ids to filter placements. - in: query name: subaccount_id type: array collectionFormat: multi items: type: string description: The subaccount ids to filter placements. - in: query name: store_id type: array collectionFormat: multi items: type: string description: The ids of the store for which playlists are fetched. - in: query name: playlist_type type: array collectionFormat: multi items: type: string description: The types of playlists which are fetched. - 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. responses: 200: description: Array of Placements object schema: $ref: '#/definitions/Placements' 401: description: Access denied when user is unauthorised 403: description: Access denied when user is authenticated but is forbidden from accessing resource /placements/breakdown: get: summary: Get aggregated number of streams for a song or artist broken down by stores and playlist types parameters: - in: query name: isrc type: string description: The isrc for which placements are to be fetched. Either `isrc` or `global_participant_id` is required in the query params - in: query name: global_participant_id type: string description: The participant id for which placements are to be fetched. Either `isrc` or `global_participant_id` is required in the query params - in: query name: distributor type: array collectionFormat: multi items: type: string description: The distributor of the song. Possible values are `theorchard` or `sme` responses: 200: description: A Placement Breakdown object schema: $ref: '#/definitions/PlacementsBreakdown' 401: description: Access denied when user is unauthorised 403: description: Access denied when user is authenticated but is forbidden from accessing resource /playlist/{store_playlist_id}/placement/{isrc}/positions: get: summary: Get how position of song within a playlist changes over time. parameters: - in: path name: store_playlist_id type: string required: true description: Id of playlist in the store - in: path name: isrc type: string required: true description: Global identifier for a song - in: query name: store_id type: integer required: true description: The store id for the placement. This query parameter is required - in: query name: storefront type: string required: true description: The storefront for the placement. Storefront is described in documentation. It's required for apple music playlists - in: query name: start_date type: string description: The starting date of the timeseries. This parameter accepts a special value `HIGHWATERMARK`. `HIGHWATERMARK` is resolved in the service to the latest date stream numbers are obtained. - in: query name: days type: integer description: This accepts a positive or negative integer offset from start_date. responses: 200: description: A Placement position timeseries object. There is only one data point for each day. schema: $ref: '#/definitions/PlacementPositionTimeSeries' /playlist/{store_playlist_id}/placement/{isrc}/streams: get: summary: Get how number of streams for a song within a playlist changes over time. parameters: - in: path name: store_playlist_id type: string required: true description: Id of playlist in the store - in: path name: isrc type: string required: true description: Global identifier for a song - in: query name: store_id type: integer required: true description: The store id for the placement. This query parameter is required - in: query name: storefront type: string required: true description: The storefront for the placement. Storefront is described in documentation. It's required for apple music playlists - in: query name: start_date type: string description: The starting date of the timeseries. This parameter accepts a special value `HIGHWATERMARK`. `HIGHWATERMARK` is resolved in the service to the latest date stream numbers are obtained. - in: query name: days type: integer description: This accepts a positive or negative integer offset from start_date. - in: query name: streams_country type: array collectionFormat: multi items: type: string description: The countries for which stream numbers are fetched. responses: 200: description: A Placement streams timeseries object. There is only one data point for each day. schema: $ref: '#/definitions/PlacementStreamsTimeSeries' 401: description: Access denied when user is unauthorised 403: description: Access denied when user is authenticated but is forbidden from accessing resource /placements/total_vs_playlist_streams_by_store: get: summary: Get how number of streams for a song within a playlist changes over time. parameters: - in: query name: isrc type: string description: The isrc for which placements are to be fetched. Either `isrc` or `global_participant_id` is required in the query params - in: query name: global_participant_id type: string description: The participant id for which placements are to be fetched. Either `isrc` or `global_participant_id` is required in the query params - in: query name: start_date type: string description: The starting date of the timeseries. This parameter accepts a special value `HIGHWATERMARK`. `HIGHWATERMARK` is resolved in the service to the latest date stream numbers are obtained. - in: query name: days type: integer description: This accepts a positive or negative integer offset from start_date. - in: query name: streams_country type: array collectionFormat: multi items: type: string description: The countries for which stream numbers are fetched. - in: query name: store_id type: array collectionFormat: multi items: type: string description: The ids of the store for which playlists are fetched. responses: 200: description: A TotalVsPlaylistTimeSeries object schema: $ref: '#/definitions/TotalVsPlaylistTimeSeries' 401: description: Access denied when user is unauthorised 403: description: Access denied when user is authenticated but is forbidden from accessing resource /playlist/{store_playlist_id}/placement/{isrc}/breakdown-by-country: get: summary: Get position and streams data in each country for a placement. parameters: - in: path name: store_playlist_id type: string required: true description: Id of playlist in the store - in: path name: isrc type: string required: true description: Global identifier for a song - in: query name: store_id type: integer required: true description: The store id for the placement. This query parameter is required - in: query name: streams_country type: array collectionFormat: multi items: type: string description: The countries for which stream numbers are fetched. - in: query name: playlist_appearances type: string description: Whether the placements are for `current` or `past`. - in: query name: sort_key type: string description: The key according to which to sort the results by. - in: query name: sort_direction type: string description: The direction according to which to sort the result by according to `sort_key`. responses: 200: description: BreakdownByCountry object schema: $ref: '#/definitions/BreakdownByCountry' 401: description: Access denied when user is unauthorised 403: description: Access denied when user is authenticated but is forbidden from accessing resource /playlist/placement/company-brand: post: summary: Get company brand information for playlist placements description: Return the company_brand for a list of playlist placements. Currently for employee use only. parameters: - in: body name: body required: true schema: type: object required: - playlist_placements properties: playlist_placements: type: array description: List of playlist placements to fetch company brand for items: type: object required: - store_playlist_id - store_id - isrc properties: store_playlist_id: type: string description: The playlist identifier specific to the store store_id: type: string description: The streaming service ID (e.g., 1 for Apple Music, 286 for Spotify) isrc: type: string description: The International Standard Recording Code for the song storefront: type: string description: Optional - For Apple Music, the country storefront code responses: 200: description: Successfully retrieved company brand information for placements schema: type: object properties: data: type: object properties: playlist_placements: type: array items: type: object properties: store_playlist_id: type: string description: The playlist identifier specific to the store store_id: type: integer description: The streaming service ID (e.g., 1 for Apple Music, 286 for Spotify) isrc: type: string description: The International Standard Recording Code for the song storefront: type: string description: Optional - For Apple Music, the country storefront code brand_ids_array: type: array items: type: string description: Array of brand UUIDs associated with this placement 400: description: Bad request - Missing or invalid playlist_placements parameter schema: type: object properties: error: type: string 401: description: Unauthorized - User is not authenticated 403: description: Forbidden - User does not have Analytics role definitions: BreakdownByCountry: type: object properties: countries: type: array items: type: object properties: isrc: type: string store_id: type: integer store_playlist_id: type: string current_position: type: integer previous_position: type: integer peak_position: type: integer position_change: type: integer last_added_on_date: type: string removed_on: type: string days_on_playlist: type: integer playlist_name: type: string playlist_artwork_url: type: string playlist_genres: type: string playlist_track_count: type: integer playlist_follower_count: type: integer playlist_type: type: string playlist_uri: type: string curator_name: type: string curator_id: type: string curator_country: type: string streams_last_1_day: type: integer streams_last_7_days: type: integer streams_last_28_days: type: integer streams_last_183_days: type: integer streams_last_365_days: type: integer streams_all_time: type: integer completion_rate_last_1_day: type: integer completion_rate_last_7_days: type: integer completion_rate_last_28_days: type: integer completion_rate_last_183_days: type: integer completion_rate_last_365_days: type: integer completion_rate_all_time: type: integer TotalVsPlaylistTimeSeries: type: object properties: all_stores_aggregation: type: object properties: timeseries: type: array items: type: object properties: date: type: string playlist_streams: type: number streams: type: number timestamp: type: string total_playlist_streams: type: number total_streams: type: number stores: type: array items: type: object properties: store_id: type: integer timeseries: type: array items: type: object properties: date: type: string playlist_streams: type: number streams: type: number timestamp: type: string total_playlist_streams: type: number total_streams: type: number PlacementStreamsTimeSeries: type: object properties: streams: type: array items: type: object properties: streams: type: integer timestamp: type: string PlacementPositionTimeSeries: type: object properties: positions: type: array items: type: object properties: position: type: integer timestamp: type: string PlacementsBreakdown: type: object properties: stores: type: object description: store id as key and metrics as value. Metrics include aggregated stream numbers, completion rate and count types: type: object description: type as key and metrics as value. Metrics include aggregated stream numbers, completion rate and count PlacementsCount: type: object properties: total_count: type: number Placements: type: object properties: isrc: type: string store_id: type: integer store_playlist_id: type: string current_position: type: integer previous_position: type: integer peak_position: type: integer position_change: type: integer last_added_on_date: type: string removed_on: type: string days_on_playlist: type: integer storefront_count: type: integer playlist_name: type: string playlist_artwork_url: type: string playlist_genres: type: string playlist_track_count: type: integer playlist_follower_count: type: integer playlist_type: type: string playlist_uri: type: string curator_name: type: string curator_id: type: string curator_country: type: string streams_last_1_day: type: integer streams_last_7_days: type: integer streams_last_28_days: type: integer streams_last_183_days: type: integer streams_last_365_days: type: integer streams_all_time: type: integer completion_rate_last_1_day: type: integer completion_rate_last_7_days: type: integer completion_rate_last_28_days: type: integer completion_rate_last_183_days: type: integer completion_rate_last_365_days: type: integer completion_rate_all_time: type: integer