# allfeeds.ai Podcast API

Search, discover, and pull complete metadata for podcasts — backed by a
continuously-updated database of podcasts crawled from iTunes/Apple Podcasts
feeds. Built for podcast discovery apps, media monitoring tools, market
research, content curation, and anywhere else you need structured podcast
data without scraping RSS feeds yourself.

## What you can do with this API

- **Search** by keyword, iTunes genre code, and/or language/country — find
  podcasts matching a topic, category, or audience.
- **Look up** any podcast by its numeric iTunes ID and get back full
  metadata: title, description, feed URL, website, language, genres, author,
  owner contact info, copyright, explicit flag, latest episode date, and
  episode count.
- **Check account status** — daily call usage and remaining quota for your
  plan.

## Endpoints

### `GET /find_podcasts`
Search the podcast directory. Provide any combination of:
- `keyword` — matched against title, subtitle, description, author, and owner name
- `genre` — a 4-digit iTunes genre code (e.g. `1310` for Music)
- `language` — a 2-letter ISO 639-1 code (e.g. `en`), optionally with a
  country suffix (e.g. `en-us`)

At least one of the three is required. Results are paginated with the
`page` parameter; results per page depend on your plan.

```
GET /find_podcasts?keyword=banjo&genre=1310&language=en
```

```json
{
  "results": [
    {
      "itunes_id": "1052989183",
      "title": "Pantheon - The Music Podcast Network",
      "image_url": "https://megaphone.imgix.net/podcasts/FBIGmetallicP1500.jpg",
      "feed_url": "https://feeds.megaphone.fm/pantheon"
    }
  ],
  "total_results": 1,
  "total_pages": 1,
  "this_page": 0
}
```

### `GET /podcast_by_itunesid`
Get complete metadata for a single podcast by its iTunes ID.

```
GET /podcast_by_itunesid?itunes_id=201671138
```

```json
{
  "results": {
    "itunes_id": "201671138",
    "title": "This American Life",
    "subtitle": "...",
    "description": "...",
    "feed_url": "http://feed.thisamericanlife.org/talpodcast",
    "website": "https://www.thisamericanlife.org",
    "language": "en",
    "genres": "1302,26,1324,1301",
    "author": "This American Life",
    "owner_email": "rich@thislife.org",
    "copyright": "Copyright 1995-2021 This American Life",
    "latest_episode_date": "2021-08-15",
    "episode_count": "10"
  },
  "total_results": 1
}
```

Not every podcaster fills in every field — expect blanks on some entries.

### `GET /account_info`
Returns your current plan, daily limit, calls used today, and calls
remaining. Useful for monitoring usage before you hit a quota.

```json
{
  "results": {
    "status": "active",
    "level": "basic",
    "daily_limit": 1000,
    "used_today": 355,
    "remaining_today": 645
  },
  "total_results": 1
}
```

## Errors

All errors return JSON with a `400` (bad request — missing/invalid
parameters) or `500` (server error) status:

```json
{ "results": { "error": "Description of the error" } }
```

## Plans

| Plan | Requests/day | Results per page |
|---|---|---|
| Free | 100 | 10 |
| Standard | 1,000 | 30 |
| Pro | Unlimited | 100 |

## Why allfeeds.ai

Most podcast databases either stop at iTunes' own limited public data or
require scraping thousands of individual RSS feeds yourself. allfeeds.ai
keeps a pre-crawled, searchable index so you get structured, ready-to-use
results with a single call.