podcasts

Discover Top Podcasts with ListenNotes Cognitive Actions

25 Apr 2025
Discover Top Podcasts with ListenNotes Cognitive Actions

ListenNotes is an innovative podcast directory service that provides developers with powerful Cognitive Actions to enhance their applications with podcast-related functionalities. By integrating these actions, developers can easily access a vast array of podcasts, making it simpler for users to discover new content tailored to their interests. The benefits of using ListenNotes include faster access to curated podcast lists, improved content discovery, and a more personalized listening experience. Whether you're building a podcast app, creating a recommendation engine, or simply looking to enhance user engagement, these actions can significantly streamline your development process.

Prerequisites

To get started with ListenNotes Cognitive Actions, you'll need an API key and a basic understanding of how to make API calls.

Fetch Best Podcasts by Genre

This action allows you to retrieve a curated list of top podcasts categorized by genre. By obtaining genre IDs from the /api/v1/genres endpoint, developers can enhance their applications with popular podcast content tailored to specific interests.

Input Requirements:

  • page: Specifies the page number for pagination (default is 2).
  • region: Determines the region for the request (default is 'fr').
  • genreId: Identifies the genre by ID (default is 125).
  • safeMode: Indicates whether safe mode is enabled (default is 1).

Expected Output: The output includes the genre ID, genre name, total number of podcasts, and a list of podcasts within that genre, complete with details such as title, description, publisher, and more.

Use Cases for this specific action:

  • Ideal for applications that want to showcase popular podcasts based on user-selected genres.
  • Useful for music or entertainment platforms looking to integrate podcast discovery features.
  • Enhances user engagement by providing personalized content recommendations.

```python
import requests
import json

# Replace with your actual Cognitive Actions API key and endpoint
# Ensure your environment securely handles the API key
COGNITIVE_ACTIONS_API_KEY = "YOUR_COGNITIVE_ACTIONS_API_KEY"
# This endpoint URL is hypothetical and should be documented for users
COGNITIVE_ACTIONS_EXECUTE_URL = "https://api.cognitiveactions.com/actions/execute"

action_id = "37365210-2df7-4204-8600-acd57e53e106" # Action ID for: Fetch Best Podcasts by Genre

# Construct the exact input payload based on the action's requirements
# This example uses the predefined example_input for this action:
payload = {
  "page": 2,
  "region": "fr",
  "genreId": 125,
  "safeMode": 1
}

headers = {
    "Authorization": f"Bearer {COGNITIVE_ACTIONS_API_KEY}",
    "Content-Type": "application/json",
    # Add any other required headers for the Cognitive Actions API
}

# Prepare the request body for the hypothetical execution endpoint
request_body = {
    "action_id": action_id,
    "inputs": payload
}

print(f"--- Calling Cognitive Action: {action.name or action_id} ---")
print(f"Endpoint: {COGNITIVE_ACTIONS_EXECUTE_URL}")
print(f"Action ID: {action_id}")
print("Payload being sent:")
print(json.dumps(request_body, indent=2))
print("------------------------------------------------")

try:
    response = requests.post(
        COGNITIVE_ACTIONS_EXECUTE_URL,
        headers=headers,
        json=request_body
    )
    response.raise_for_status() # Raise an exception for bad status codes (4xx or 5xx)

    result = response.json()
    print("Action executed successfully. Result:")
    print(json.dumps(result, indent=2))

except requests.exceptions.RequestException as e:
    print(f"Error executing action {action_id}: {e}")
    if e.response is not None:
        print(f"Response status: {e.response.status_code}")
        try:
            print(f"Response body: {e.response.json()}")
        except json.JSONDecodeError:
            print(f"Response body (non-JSON): {e.response.text}")
    print("------------------------------------------------")



## Fetch Supported Country Codes for Podcasts
This action retrieves a list of supported country codes and names, essential for regional queries in the best podcasts API. 

**Input Requirements:**
- No specific input parameters are required for this action.

**Expected Output:**
The output includes a list of country codes along with their corresponding country names, facilitating localized podcast searches.

**Use Cases for this specific action:**
- Allows developers to implement country-specific podcast recommendations in their applications.
- Essential for apps targeting specific regions or languages, enhancing user experience by providing relevant content.


import requests
import json

# Replace with your actual Cognitive Actions API key and endpoint
# Ensure your environment securely handles the API key
COGNITIVE_ACTIONS_API_KEY = "YOUR_COGNITIVE_ACTIONS_API_KEY"
# This endpoint URL is hypothetical and should be documented for users
COGNITIVE_ACTIONS_EXECUTE_URL = "https://api.cognitiveactions.com/actions/execute"

action_id = "458dc23e-af6f-431c-85b7-8416acb8266e" # Action ID for: Fetch Supported Country Codes for Podcasts

# Construct the exact input payload based on the action's requirements
# This example uses the predefined example_input for this action:
payload = {}

headers = {
    "Authorization": f"Bearer {COGNITIVE_ACTIONS_API_KEY}",
    "Content-Type": "application/json",
    # Add any other required headers for the Cognitive Actions API
}

# Prepare the request body for the hypothetical execution endpoint
request_body = {
    "action_id": action_id,
    "inputs": payload
}

print(f"--- Calling Cognitive Action: {action.name or action_id} ---")
print(f"Endpoint: {COGNITIVE_ACTIONS_EXECUTE_URL}")
print(f"Action ID: {action_id}")
print("Payload being sent:")
print(json.dumps(request_body, indent=2))
print("------------------------------------------------")

try:
    response = requests.post(
        COGNITIVE_ACTIONS_EXECUTE_URL,
        headers=headers,
        json=request_body
    )
    response.raise_for_status() # Raise an exception for bad status codes (4xx or 5xx)

    result = response.json()
    print("Action executed successfully. Result:")
    print(json.dumps(result, indent=2))

except requests.exceptions.RequestException as e:
    print(f"Error executing action {action_id}: {e}")
    if e.response is not None:
        print(f"Response status: {e.response.status_code}")
        try:
            print(f"Response body: {e.response.json()}")
        except json.JSONDecodeError:
            print(f"Response body (non-JSON): {e.response.text}")
    print("------------------------------------------------")



## Fetch Random Podcast Episode
This action retrieves a random podcast episode from the ListenNotes database, providing users with unexpected and engaging content.

**Input Requirements:**
- No specific input parameters are required for this action.

**Expected Output:**
The output includes details of a random episode, such as the episode title, description, audio link, and publisher information.

**Use Cases for this specific action:**
- Great for applications that want to introduce serendipity into the podcast listening experience.
- Useful for users who are unsure of what to listen to next, encouraging exploration of diverse content.


import requests
import json

# Replace with your actual Cognitive Actions API key and endpoint
# Ensure your environment securely handles the API key
COGNITIVE_ACTIONS_API_KEY = "YOUR_COGNITIVE_ACTIONS_API_KEY"
# This endpoint URL is hypothetical and should be documented for users
COGNITIVE_ACTIONS_EXECUTE_URL = "https://api.cognitiveactions.com/actions/execute"

action_id = "45c79c0f-f2ed-4ecf-9391-c45c65cf64b0" # Action ID for: Fetch Random Podcast Episode

# Construct the exact input payload based on the action's requirements
# This example uses the predefined example_input for this action:
payload = {}

headers = {
    "Authorization": f"Bearer {COGNITIVE_ACTIONS_API_KEY}",
    "Content-Type": "application/json",
    # Add any other required headers for the Cognitive Actions API
}

# Prepare the request body for the hypothetical execution endpoint
request_body = {
    "action_id": action_id,
    "inputs": payload
}

print(f"--- Calling Cognitive Action: {action.name or action_id} ---")
print(f"Endpoint: {COGNITIVE_ACTIONS_EXECUTE_URL}")
print(f"Action ID: {action_id}")
print("Payload being sent:")
print(json.dumps(request_body, indent=2))
print("------------------------------------------------")

try:
    response = requests.post(
        COGNITIVE_ACTIONS_EXECUTE_URL,
        headers=headers,
        json=request_body
    )
    response.raise_for_status() # Raise an exception for bad status codes (4xx or 5xx)

    result = response.json()
    print("Action executed successfully. Result:")
    print(json.dumps(result, indent=2))

except requests.exceptions.RequestException as e:
    print(f"Error executing action {action_id}: {e}")
    if e.response is not None:
        print(f"Response status: {e.response.status_code}")
        try:
            print(f"Response body: {e.response.json()}")
        except json.JSONDecodeError:
            print(f"Response body (non-JSON): {e.response.text}")
    print("------------------------------------------------")



## Search Podcasts and Episodes
This action allows developers to perform a full-text search for episodes or podcasts using various filters such as genre, language, and publication date.

**Input Requirements:**
- `q`: The search query string (default is 'star wars').
- Additional optional parameters for filtering based on network category ID, content type, language, and more.

**Expected Output:**
The output includes search results with relevant podcasts or episodes, complete with details such as title, description, and audio links.

**Use Cases for this specific action:**
- Perfect for applications that require robust search functionalities for podcasts.
- Ideal for building personalized podcast discovery features based on user input.


import requests
import json

# Replace with your actual Cognitive Actions API key and endpoint
# Ensure your environment securely handles the API key
COGNITIVE_ACTIONS_API_KEY = "YOUR_COGNITIVE_ACTIONS_API_KEY"
# This endpoint URL is hypothetical and should be documented for users
COGNITIVE_ACTIONS_EXECUTE_URL = "https://api.cognitiveactions.com/actions/execute"

action_id = "709e6f87-48a7-49ed-b1cb-ca4ad7d68aec" # Action ID for: Search Podcasts and Episodes

# Construct the exact input payload based on the action's requirements
# This example uses the predefined example_input for this action:
payload = {
  "q": "star wars",
  "type": "episode",
  "offset": 0,
  "onlyIn": "title",
  "genreIds": "68,82",
  "language": "English",
  "safeMode": 1,
  "sortByDate": 0,
  "lengthMaximum": 10,
  "lengthMinimum": 2,
  "publishedAfter": 1390190241000,
  "publishedBefore": 1490190241000
}

headers = {
    "Authorization": f"Bearer {COGNITIVE_ACTIONS_API_KEY}",
    "Content-Type": "application/json",
    # Add any other required headers for the Cognitive Actions API
}

# Prepare the request body for the hypothetical execution endpoint
request_body = {
    "action_id": action_id,
    "inputs": payload
}

print(f"--- Calling Cognitive Action: {action.name or action_id} ---")
print(f"Endpoint: {COGNITIVE_ACTIONS_EXECUTE_URL}")
print(f"Action ID: {action_id}")
print("Payload being sent:")
print(json.dumps(request_body, indent=2))
print("------------------------------------------------")

try:
    response = requests.post(
        COGNITIVE_ACTIONS_EXECUTE_URL,
        headers=headers,
        json=request_body
    )
    response.raise_for_status() # Raise an exception for bad status codes (4xx or 5xx)

    result = response.json()
    print("Action executed successfully. Result:")
    print(json.dumps(result, indent=2))

except requests.exceptions.RequestException as e:
    print(f"Error executing action {action_id}: {e}")
    if e.response is not None:
        print(f"Response status: {e.response.status_code}")
        try:
            print(f"Response body: {e.response.json()}")
        except json.JSONDecodeError:
            print(f"Response body (non-JSON): {e.response.text}")
    print("------------------------------------------------")



## Get Episode Recommendations
This action retrieves up to 8 podcast episode recommendations based on a provided episode ID, leveraging the ListenNotes directory.

**Input Requirements:**
- `id`: A unique string that identifies the episode request.
- `safeMode`: A numeric value indicating the level of safety checks to apply during the request processing.

**Expected Output:**
The output includes a list of recommended episodes, complete with details such as title, publisher, and audio links.

**Use Cases for this specific action:**
- Ideal for applications that want to offer users additional content based on their current listening habits.
- Enhances user engagement by providing curated recommendations that align with user interests.


import requests
import json

# Replace with your actual Cognitive Actions API key and endpoint
# Ensure your environment securely handles the API key
COGNITIVE_ACTIONS_API_KEY = "YOUR_COGNITIVE_ACTIONS_API_KEY"
# This endpoint URL is hypothetical and should be documented for users
COGNITIVE_ACTIONS_EXECUTE_URL = "https://api.cognitiveactions.com/actions/execute"

action_id = "a0d919d4-a226-4892-a348-bd3e4f1a6cfe" # Action ID for: Get Episode Recommendations

# Construct the exact input payload based on the action's requirements
# This example uses the predefined example_input for this action:
payload = {
  "id": "deecd6ee486f4f47abe61998efc2c0c2",
  "safeMode": 1
}

headers = {
    "Authorization": f"Bearer {COGNITIVE_ACTIONS_API_KEY}",
    "Content-Type": "application/json",
    # Add any other required headers for the Cognitive Actions API
}

# Prepare the request body for the hypothetical execution endpoint
request_body = {
    "action_id": action_id,
    "inputs": payload
}

print(f"--- Calling Cognitive Action: {action.name or action_id} ---")
print(f"Endpoint: {COGNITIVE_ACTIONS_EXECUTE_URL}")
print(f"Action ID: {action_id}")
print("Payload being sent:")
print(json.dumps(request_body, indent=2))
print("------------------------------------------------")

try:
    response = requests.post(
        COGNITIVE_ACTIONS_EXECUTE_URL,
        headers=headers,
        json=request_body
    )
    response.raise_for_status() # Raise an exception for bad status codes (4xx or 5xx)

    result = response.json()
    print("Action executed successfully. Result:")
    print(json.dumps(result, indent=2))

except requests.exceptions.RequestException as e:
    print(f"Error executing action {action_id}: {e}")
    if e.response is not None:
        print(f"Response status: {e.response.status_code}")
        try:
            print(f"Response body: {e.response.json()}")
        except json.JSONDecodeError:
            print(f"Response body (non-JSON): {e.response.text}")
    print("------------------------------------------------")



## Generate Search Suggestions
This action produces search term suggestions for queries within the ListenNotes podcast directory, with optional filtering for safe mode, genre, and podcasts.

**Input Requirements:**
- `query`: The search term used to query the database (default is 'star').
- Additional optional parameters to filter results by genre and podcast.

**Expected Output:**
The output includes suggested search terms, genres, and relevant podcasts, helping users refine their searches.

**Use Cases for this specific action:**
- Useful for applications that want to enhance the search experience by providing users with relevant suggestions.
- Perfect for guiding users to discover new content based on their interests.


import requests
import json

# Replace with your actual Cognitive Actions API key and endpoint
# Ensure your environment securely handles the API key
COGNITIVE_ACTIONS_API_KEY = "YOUR_COGNITIVE_ACTIONS_API_KEY"
# This endpoint URL is hypothetical and should be documented for users
COGNITIVE_ACTIONS_EXECUTE_URL = "https://api.cognitiveactions.com/actions/execute"

action_id = "de2b2229-07e4-4627-9e43-025ffb1d73f4" # Action ID for: Generate Search Suggestions

# Construct the exact input payload based on the action's requirements
# This example uses the predefined example_input for this action:
payload = {
  "query": "star",
  "safeMode": 1,
  "showGenres": 1,
  "showPodcasts": 1
}

headers = {
    "Authorization": f"Bearer {COGNITIVE_ACTIONS_API_KEY}",
    "Content-Type": "application/json",
    # Add any other required headers for the Cognitive Actions API
}

# Prepare the request body for the hypothetical execution endpoint
request_body = {
    "action_id": action_id,
    "inputs": payload
}

print(f"--- Calling Cognitive Action: {action.name or action_id} ---")
print(f"Endpoint: {COGNITIVE_ACTIONS_EXECUTE_URL}")
print(f"Action ID: {action_id}")
print("Payload being sent:")
print(json.dumps(request_body, indent=2))
print("------------------------------------------------")

try:
    response = requests.post(
        COGNITIVE_ACTIONS_EXECUTE_URL,
        headers=headers,
        json=request_body
    )
    response.raise_for_status() # Raise an exception for bad status codes (4xx or 5xx)

    result = response.json()
    print("Action executed successfully. Result:")
    print(json.dumps(result, indent=2))

except requests.exceptions.RequestException as e:
    print(f"Error executing action {action_id}: {e}")
    if e.response is not None:
        print(f"Response status: {e.response.status_code}")
        try:
            print(f"Response body: {e.response.json()}")
        except json.JSONDecodeError:
            print(f"Response body (non-JSON): {e.response.text}")
    print("------------------------------------------------")



## Fetch Supported Podcast Languages
This action retrieves a list of languages available in the Listen Notes database, which can be used as query parameters in the podcast search API.

**Input Requirements:**
- No specific input parameters are required for this action.

**Expected Output:**
The output includes a list of languages, enabling developers to filter podcasts based on language preferences.

**Use Cases for this specific action:**
- Essential for applications targeting multilingual audiences, allowing for a more tailored podcast search experience.
- Useful for enhancing user satisfaction by enabling searches in the user's preferred language.


import requests
import json

# Replace with your actual Cognitive Actions API key and endpoint
# Ensure your environment securely handles the API key
COGNITIVE_ACTIONS_API_KEY = "YOUR_COGNITIVE_ACTIONS_API_KEY"
# This endpoint URL is hypothetical and should be documented for users
COGNITIVE_ACTIONS_EXECUTE_URL = "https://api.cognitiveactions.com/actions/execute"

action_id = "edab7500-3986-4248-85ba-2529162bbeb3" # Action ID for: Fetch Supported Podcast Languages

# Construct the exact input payload based on the action's requirements
# This example uses the predefined example_input for this action:
payload = {}

headers = {
    "Authorization": f"Bearer {COGNITIVE_ACTIONS_API_KEY}",
    "Content-Type": "application/json",
    # Add any other required headers for the Cognitive Actions API
}

# Prepare the request body for the hypothetical execution endpoint
request_body = {
    "action_id": action_id,
    "inputs": payload
}

print(f"--- Calling Cognitive Action: {action.name or action_id} ---")
print(f"Endpoint: {COGNITIVE_ACTIONS_EXECUTE_URL}")
print(f"Action ID: {action_id}")
print("Payload being sent:")
print(json.dumps(request_body, indent=2))
print("------------------------------------------------")

try:
    response = requests.post(
        COGNITIVE_ACTIONS_EXECUTE_URL,
        headers=headers,
        json=request_body
    )
    response.raise_for_status() # Raise an exception for bad status codes (4xx or 5xx)

    result = response.json()
    print("Action executed successfully. Result:")
    print(json.dumps(result, indent=2))

except requests.exceptions.RequestException as e:
    print(f"Error executing action {action_id}: {e}")
    if e.response is not None:
        print(f"Response status: {e.response.status_code}")
        try:
            print(f"Response body: {e.response.json()}")
        except json.JSONDecodeError:
            print(f"Response body (non-JSON): {e.response.text}")
    print("------------------------------------------------")



## Conclusion
Integrating the ListenNotes Cognitive Actions into your application can significantly enhance the podcast discovery experience for users. From fetching curated lists of top podcasts to providing personalized recommendations and search functionalities, these actions offer a powerful toolkit for developers. As you consider your next steps, think about how you can leverage these capabilities to create engaging and dynamic podcast experiences that resonate with your audience.
← Back to All Articles