How To: Fetch Episodes from a Podcast

Getting Started

The SeekrAlign™ Podcast Intelligence API enables users to retrieve a list of episodes for a specific podcast show. This API call is perfect for obtaining episode-level metadata, such as titles, descriptions, civility scores, and publication dates, for a particular podcast (e.g., The Joe Rogan Experience). If you want detailed information for a single episode, use the Fetch Episode Details API call instead.

Purpose

This API call retrieves all episodes from a specific podcast show, enabling users to browse and filter through episodes using various query parameters.

API Endpoint

API Reference:
GET Podcast Episodes

Base URL:
https://services-api.seekr.com/api/v1/podcasts/{podcastId}/episodes

Path Parameters

Parameter	Type	Required	Description
`podcastId`	string	Yes	Unique identifier for the podcast show.

Query Parameters

Parameter	Type	Description
`limit`	integer	Maximum number of results returned (default: 20, max: 100).
`offset`	integer	Starting index for the results in the current result set (default: 0).
`publishedDateMin`	string	The earliest published date for filtering results (inclusive).
`publishedDateMax`	string	The latest published date for filtering results (inclusive).
`sortBy`	string	Field used to sort the results. Valid value: `publishedDate`.
`sortDirection`	string	Direction of the sort. Valid values: `asc`, `desc` (default: desc).
`isExplicit`	boolean	Indicates whether to filter for explicit content.

Authentication

All API requests must include an API key for authentication.
Header Format:

Authorization: Bearer <api_key>

Response Format

Responses are returned in JSON format, providing metadata for episodes of the specified podcast.

Using the Fetch Episodes from a Podcast API

Step 1: Identify the Podcast ID

Use the Fetch Podcast Information API to retrieve the podcastId for the desired show.

Step 2: Make the API Call

Submit a GET request to the endpoint, including the podcastId in the URL, and apply any desired query parameters.

Example Request

curl --request GET \
--url https://services-api.seekr.com/api/v1/podcasts/abc123xyz456/episodes \
--header 'accept: application/json' \
--header 'authorization: Bearer your_api_key'

Example Response

{
  "apiVersion": "1.0.0",
  "status": 200,
  "results": [
    {
      "audioLinkUrl": "https://my-podcast.com/episode1/audio.mp3",
      "civilityScore": 81,
      "civilityScoreLabel": "high",
      "description": "This is a description of the episode",
      "duration": 60000,
      "episodeId": "f3a6cf0edf0e53c71d29dcb970f3caf8",
      "episodeNumber": 1,
      "episodeTitle": "My Episode",
      "excusableAttacks": 10,
      "garm": [
        {
          "category": "Firearms",
          "level": "high"
        }
      ],
      "imageUrl": "https://imageurl.com/image",
      "inexcusableAttacks": 10,
      "podcastId": "abc123xyz456",
      "podcastTitle": "The Joe Rogan Experience",
      "publishedDate": "2023-09-23",
      "season": 1
    }
  ]
}

Use Case Examples

Example 1: Retrieve All Episodes from a Podcast

Objective: Retrieve all episodes of The Joe Rogan Experience.
Steps:

Identify the podcastId (e.g., abc123xyz456).
Make the API call to retrieve the episode list.
Result: A list of episodes is returned with their metadata.

Best Practices

Filter Results: Use publishedDateMin and publishedDateMax to narrow down results to specific date ranges.
Optimize Pagination: Use limit and offset parameters to handle large episode lists efficiently.
Explicit Content Filtering: Use the isExplicit parameter to include or exclude explicit episodes.

For more details, visit the SeekrAlign API Documentation.

Would you like to proceed with the fourth API call?