How To: Fetch All Podcast Episodes

Getting Started

The SeekrAlign Podcast Intelligence API allows users to search across all podcast episodes that meet specific criteria, such as civility score, publication date, or title. This API call is ideal for identifying episodes of interest without needing a specific podcast ID.

If you need information about episodes from a specific podcast, use the Fetch Episodes from a Podcast API call instead.

Purpose

This API call retrieves general episode-level information for podcasts across the platform, based on the user's specified filters. It’s designed for broad searches to discover episodes that meet particular requirements.

API Endpoint

API Reference:
GET Podcast Episodes

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

Query Parameters

Parameter	Type	Required	Description
`civilityScoreMax`	integer	No	Maximum civility score in the results (range: 1-100).
`civilityScoreMin`	integer	No	Minimum civility score in the results (range: 1-100).
`isExplicit`	boolean	No	Indicates whether the episode contains explicit content.
`limit`	integer	No	Maximum number of results to return (default: 20, max: 100).
`offset`	integer	No	Starting index for the result set (default: 0).
`publishedDateMax`	string (date)	No	Latest published date for filtering results.
`publishedDateMin`	string (date)	No	Earliest published date for filtering results.
`podcastTitle`	string	No	Filters results by the podcast title.
`sortBy`	string	No	Field to sort results. Valid value: `publishedDate`.
`sortDirection`	string	No	Direction to sort results. Valid values: `asc`, `desc` (default: `desc`).
`episodeTitle`	string	No	Filters results by the episode title.

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 a list of podcast episodes matching the query parameters.

Using the Fetch Podcast Episodes API

Step 1: Define Your Filters

Choose filters like civilityScoreMin, publishedDateMin, or podcastTitle to narrow down your results.

Step 2: Make the API Call

Submit a GET request to the endpoint with the required filters in the query string.

Example Request

curl --request GET \
--url https://services-api.seekr.com/api/v1/podcasts/episodes?civilityScoreMin=80&limit=5 \
--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": "My Podcast",
      "publishedDate": "2023-09-23",
      "season": 1
    }
  ]
}

Use Case Examples

Example 1: Identify Civility-Friendly Episodes

Objective: Find episodes with a civility score above 80.
Steps:

Set civilityScoreMin=80 in the query parameters.
Review the list of episodes returned.
Result: High-civility episodes are retrieved for potential inclusion in campaigns.

Best Practices

Use Filters Effectively: Combine parameters like publishedDateMin and civilityScoreMin for more targeted results.
Limit Your Results: Set the limit parameter to prevent retrieving unnecessary data.
Sort by Date: Use sortBy=publishedDate to organize episodes chronologically.

For more details, visit the SeekrAlign API Documentation.

Would you like to revisit or refine any of the previous API calls or move on to the next task?