NAV

Introduction

Intro text goes here

Limits and Restrictions

If you really need some or all of the restrictions below lifting do get in touch. I’m open to loosening up the rules for entities that need more flexibility in exchange for a monthly or annual pro usage license fee

Data usage

The data provided by The Podcast Database may be used for both commercial and non-commerical purposes, with the limitation that you must link back to https://poddb.net on any page you use the data in a way that doesn’t imply your usage is endorsed. Something like “Podcast data provided by The Podcast Database” would do the trick.

The pro usage license is whitelabel friendly, with the license you no longer have to link back in any way.

Rate limiting

There’s no strict rate limiting, but please do try to average your requests at around the one per five seconds mark. The pro usage license lifts all rate limits.

Duplication of Data

Please don’t use the data provided by The Podcast Database to make a podcast database of your own. That’s not what it’s for. Caching data is fine and expected (and appreciated!) but a straight up copy of the site is not ok. Lets be real, it’s a right pain in the arse to make a database with all this data, that’s why you’re using this one. Please don’t abuse the effort.

The pro usage license lifts this restriction and optionally provides you access to a daily database dump so you don’t have to crawl the API.

Identify yourself

Server access

Set your user agent to something that can be used to ping you a message if something’s going wrong. The standard for this is in the format

Your App Name v1.1 (https://example.com/bot) or Your App Name v1.1 (hello@example.com)

In the example your site’s /bot page would be a contact form or display some way of getting in touch with you. It doesn’t have to be /bot, it could be /contact for example. In both cases example.com should be the site where you’re using the data (or at least contain a link to the app that uses the data)

If there’s a way we can discuss any rogue robot action then nobody gets their access blocked. Win win!

Client side access

For any requests where you’re using the API on the frontend (e.g. AJAX-ally running a podcast search) please also add the URL parameter “via” with the value of your site/app domain. e.g.

https://api.poddb.net/podcasts?title=Your+user+search+query&via=example.com

This will not change the results in any way, it just gives us a way to get in touch if needed.

Client side access without a via parameter may encounter a global rate limit instead of a per-app limit. In the ideal world this wont happen but if the API is getting hammered by unknown requests it may be required.

Podcast Endpoint

All of the following keys can be searched by adding them as URL parameters. Mix and match to find what you’re after.

curl https://api.poddb.net/podcasts?your=params&go=here

Example return value

{
    "status": "ok",
    "data": {
        "id": "abc123xyz",
        "title": "Podcast Name",
        "feed": "https://example.com/podcast.xml",
        "old-feed": [
            "https://example.com/old-podcast-feed.xml",
            "https://example.net/even-older-podcast-feed.xml"
        ],
        "generator": "Name of the site/software that generated the pod feed",
        "description": "Lorem impsum podcast desctiptsum",
        "copyright": "© Podcast copyright text",
        "language": "en-gb",
        "pubDate": "",
        "lastBuildDate": "",
        "link": "https://example.com",
        "image": {
            "title": "Podcast Name Again Usually",
            "url": "https://example.com/podcast/artwork.png",
            "link": "https://example.com"
        },
        "categories": [
            "Category Name",
            "Another Category",
            "A Third Category"
        ],
        "type": "episodic",
        "author": "Podcast Author Name",
        "summary": "Podcast summary",
        "subtitle": "Podcast summary.. I mean subtitle. It's usually the same as summary.",
        "keywords": [
            "a",
            "bunch",
            "of",
            "keywords"
        ],
        "owner": {
            "name": "Someone's Name",
            "email": "Someone's Email",
        },
        "complete": "no",
        "explicit": "clean",
        "block": "no",
	"hosts": [
            {
                "name": "John Smith",
                "etc": "See the Person endpoint"
            },
            {
                "name": "Jen Smith",
                "etc": "See the Person endpoint"
            }
        ],
        "guests": [
            {
                "name": "Jim Smith",
                "etc": "See the Person endpoint"
            }
        ]
    }
}
Parameter What it contains
id Alphanumeric ID. Unique to Pod DB, may clash with IDs from elsewhere
title The podcast’s name/title
feed The RSS feed URL. Auto-updates if we bump into an itunes:new-feed-url
old-feed An array of RSS feed URLs. When we get pinged a new-feed-url we update feed and track the previous URLs here
generator The name of the site/software that generated the RSS feed. Usually gives an idea of where it’s hosted
description The description of the podcast
copyright The copyright string for this podcast. Usually in the format “© ” but it’s not a strict format
language The podcast language in the form en-gb, en-us, etc
pubDate When the latest episode was published
lastBuildDate Last time the feed was updated
link The podcast’s website
image.title Usually the podcast name again. It’s what you’d use in an alt tag
image.url The URL of the artwork
image.link Where the artwork should link to if it was wrapped in an a href
categories An array of categories. First listed is the main category in itunes. Comma separated in your search. Or provide multiple &categories[]= parameters
type Episodic or Serial. The idea is it tells the podcast client which order to display episodes. Episodic = New to Old. Serial = Old to New
author The Johnny Smith that authors the podcast. Usually the main host(s) are listed here.
summary Usually an excerpt of the description
subtitle Usually the exact same as the summary
keywords An array of keywords. Nice and simple. Comma separated in your search. Or provide multiple &keyword[]= parameters
owner.name The name of the entity that owns the podcast
owner.email Usually some Johnny Delboy’s itunes email address
complete Is the podcast done with? yes/no
explicit yes has swearing, nohas no swearing, clean has bleeped swearing
block yes or no. I have no idea what it means
hosts An array of objects. The objects match the Person endpoint specification
guests An array of objects. The objects match the Person endpoint specification

Query filters

In addition to the searches above you can apply the filters

Key Values
orderBy Order by one of the parameters above. Numbers get sorted numerically, strings alphabetically
order asc, desc