cleanup

Author: mre

src/config/swagger.ts

@@ -8,55 +8,7 @@ const options: swaggerJsdoc.Options = {
     info: {
       title: 'Open Podcast Analytics API',
       version: version,
-      description: `
-# Open Podcast Analytics API
-
-Comprehensive podcast analytics API providing metrics from multiple platforms including Spotify, Apple Podcasts, and custom hosting providers.
-
-## Available Data
-
-### Spotify Data
-- Episode and podcast streams (starts and completed streams, daily granularity)
-- Listener counts (unique listeners over time)
-- Followers of the podcast (daily snapshots)
-- Episode performance (median listen percentage, median seconds, percentiles, listen-through curves on a per-second basis)
-- Audience demographics (age groups, gender, country, at both episode and podcast level)
-- Podcast metadata (episode titles, descriptions, artwork, URLs, release dates, explicit flag, duration, language)
-- Historical metadata snapshots (track changes over time)
-- Impressions and funnel data (total impressions, impressions by source such as home, search, library, other, funnel stages from impressions to considerations to streams, conversion percentages per day)
-
-### Apple Podcasts Data
-- Episode metadata (episode name, collection/podcast name, release datetime, GUID, episode number, type)
-- Episode details (plays, total time listened, unique engaged listeners, unique listeners, engaged plays vs. total plays)
-- Playback histograms (listen-through on a time-bucket basis, top countries and cities, median listeners at different quarters of the episode)
-- Trends (daily episode-level metrics: plays, total time listened, unique listeners, engaged listeners)
-- Trends (daily podcast-level metrics: same as above, aggregated across episodes)
-- Listening time split by followers vs. non-followers
-- Follower statistics (total followers, unfollowers, gained/lost per day)
-
-### General Metrics
-- Plays, streams, downloads (episode and podcast level, daily)
-- Listen-through data (per-second or per-bucket playback curves, histograms, medians, percentiles)
-- Audience demographics (age, gender, country)
-- Followers and subscribers (absolute numbers and gained/lost trends)
-- Impressions and funnel steps (Spotify)
-- Metadata (titles, descriptions, release dates, artwork, language)
-- Historical snapshots (to track changes over time)
-
-## Authentication
-
-All endpoints require a Bearer token in the Authorization header:
-
-\`\`\`
-Authorization: Bearer YOUR_TOKEN
-\`\`\`
-
-## Date Parameters
-
-Most endpoints accept date range parameters:
-- \`start\`: Start date in YYYY-MM-DD format
-- \`end\`: End date in YYYY-MM-DD format
-      `,
+      description: 'Podcast analytics API providing metrics from Spotify, Apple Podcasts, and custom hosting providers. See https://github.com/openpodcast/api/blob/main/docs/AVAILABLE_QUERIES.md for a complete list of available queries.',
       contact: {
         name: 'Open Podcast',
         url: 'https://openpodcast.dev',
@@ -127,28 +79,8 @@ Most endpoints accept date range parameters:
     ],
     tags: [
       {
-        name: 'Spotify',
-        description: 'Spotify podcast analytics endpoints',
-      },
-      {
-        name: 'Apple Podcasts',
-        description: 'Apple Podcasts analytics endpoints',
-      },
-      {
-        name: 'Episodes',
-        description: 'Episode-level metrics across platforms',
-      },
-      {
-        name: 'Podcast',
-        description: 'Podcast-level metrics and metadata',
-      },
-      {
-        name: 'Hoster',
-        description: 'Generic hosting provider metrics',
-      },
-      {
-        name: 'Charts',
-        description: 'Chart rankings and positions',
+        name: 'Analytics',
+        description: 'Query podcast analytics data from multiple sources',
       },
     ],
   },

src/index.ts

@@ -280,16 +280,18 @@ app.get(
  *   get:
  *     summary: Get analytics data for a podcast
  *     description: |
- *       Returns analytics data for a specific podcast and query endpoint.
+ *       Query analytics data for a specific podcast.
  *
- *       Supports multiple data sources (Spotify, Apple Podcasts, generic hosters) and various metrics including:
- *       - Episode and podcast performance metrics
- *       - Audience demographics
- *       - Listen-through data
- *       - Follower statistics
- *       - Chart rankings
+ *       The `query` parameter specifies which metric to retrieve. Common queries include:
+ *       - `reportSpotifyPodcastBaseMetrics` - Spotify podcast metrics (streams, listeners, followers)
+ *       - `reportApplePodcastBaseMetrics` - Apple Podcasts metrics (plays, listeners, engagement)
+ *       - `episodesTotalMetrics` - Combined episode metrics across platforms
+ *       - `reportHosterPlatforms` - Platform/app distribution (e.g., Apple Podcasts, Spotify, Overcast)
+ *       - `reportHosterClients` - Client/device distribution
  *
- *       Results can be returned in JSON or CSV format.
+ *       See [AVAILABLE_QUERIES.md](https://github.com/openpodcast/api/blob/main/docs/AVAILABLE_QUERIES.md) for the complete list of 50+ available queries.
+ *
+ *       Results can be returned in JSON (default) or CSV format by appending `/csv` to the path.
  *     tags:
  *       - Analytics
  *     parameters:
@@ -344,21 +346,43 @@ app.get(
  *                   properties:
  *                     query:
  *                       type: string
+ *                       example: reportHosterPlatforms
  *                     podcastId:
  *                       type: string
+ *                       example: "123"
  *                     date:
  *                       type: string
  *                       format: date-time
+ *                       example: "2024-09-24T12:00:00Z"
  *                     startDate:
  *                       type: string
  *                       format: date
+ *                       example: "2024-08-01"
  *                     endDate:
  *                       type: string
  *                       format: date
+ *                       example: "2024-08-31"
  *                 data:
  *                   type: array
  *                   items:
  *                     type: object
+ *             example:
+ *               meta:
+ *                 query: reportHosterPlatforms
+ *                 podcastId: "123"
+ *                 date: "2024-09-24T12:00:00Z"
+ *                 startDate: "2024-08-01"
+ *                 endDate: "2024-08-31"
+ *               data:
+ *                 - platform_name: "Apple Podcasts"
+ *                   total_downloads: 15420
+ *                   percentage: 45.2
+ *                 - platform_name: "Spotify"
+ *                   total_downloads: 10280
+ *                   percentage: 30.1
+ *                 - platform_name: "Overcast"
+ *                   total_downloads: 4120
+ *                   percentage: 12.1
  *           text/csv:
  *             schema:
  *               type: string