# TheTVDB API alternative

> TheTVDB is TV focused and offers several episode orderings, such as aired, DVD and absolute. amodb covers TV, movies and people with one key and maps a TVDB id to its own id with one call. It lists a show's episode groups but not their contents, so alternate numbering stays on TheTVDB.

## Which one fits a TV project

TheTVDB is TV focused and keeps several episode orderings for a show, including aired, DVD and absolute, behind an API key model. Check their docs for licensing before you plan a commercial product. Pick amodb when you want TV, movies and people from one key, TMDB v3 paths and 14 languages. Pick TheTVDB when exact alternate numbering is the center of your app, because amodb lists the episode groups of a show but does not serve what is inside them.

## How TV data maps between the two

The concepts line up, but the names differ. This table covers what a TV app usually reads.

| Need                         | TheTVDB approach                  | amodb call                                          |
| ---------------------------- | --------------------------------- | --------------------------------------------------- |
| One series                   | Series record by TVDB id          | `GET /3/tv/1396`, after a `tvdb_id` lookup          |
| Season list                  | Check their docs                  | `seasons` array in series details                   |
| One season with episodes     | Check their docs                  | `GET /3/tv/1396/season/1`                           |
| One episode                  | Check their docs                  | `GET /3/tv/1396/season/1/episode/1`                 |
| Which orderings exist        | Aired, DVD and absolute orderings | `GET /3/tv/1396/episode_groups`                     |
| Episodes inside one ordering | Check their docs                  | Not offered, `/3/tv/episode_group/{id}` answers 404 |
| Next episode to air          | Check their docs                  | `next_episode_to_air` in series details             |

Episode fields use the TMDB names: `air_date`, `episode_number`, `season_number`, `runtime` and `still_path`. Season and episode `external_ids` are all null, so a TVDB id of a single season or episode cannot be read from amodb. Join on `season_number` and `episode_number` instead. Details are on [seasons and episodes](https://amodb.dev/tv-seasons-episodes/).

## What the episode group list returns

The list call shows which orderings exist for a series. It does not return the episodes inside them.

| Field           | Meaning                                         |
| --------------- | ----------------------------------------------- |
| `id`            | Id of the group, a string                       |
| `name`          | Name of the ordering, such as `DVD / PVOD`      |
| `description`   | Text from the source, often empty               |
| `type`          | A number that says which kind of ordering it is |
| `episode_count` | Episodes in the ordering                        |
| `group_count`   | Blocks in the ordering, such as seasons         |
| `network`       | An object with the network, or null             |

This is a real reply for Breaking Bad.

```json
{
  "id": 1396,
  "results": [
    {
      "description": "Seasons grouped as they appear on DVD, as well as paid video-on-demand services, such as Prime Video and YouTube.",
      "episode_count": 62,
      "group_count": 6,
      "id": "69f50757054263b7bc87e32a",
      "name": "DVD / PVOD",
      "network": null,
      "type": 3
    }
  ]
}
```

Some shows return one aired order and others several, and some return an empty `results` array. Test the shows you care about. Because the contents of a group are not offered, an app that needs the DVD or absolute number of each episode cannot get it from amodb.

## Feature comparison

| Feature         | TheTVDB                                       | amodb                                                 |
| --------------- | --------------------------------------------- | ----------------------------------------------------- |
| Pricing model   | API key model, check their docs for licensing | Prepaid periods of 1 to 24 months                     |
| Free tier       | Check their docs                              | None, and no trial                                    |
| Authentication  | API key, check their docs for the flow        | `api_key` or Bearer header                            |
| Response format | JSON, check their docs                        | JSON in TMDB v3 shape                                 |
| Languages       | Check their docs                              | 14 interface languages                                |
| Movies          | Check their docs                              | Yes                                                   |
| TV              | Yes, its main focus                           | Yes, with seasons and episodes                        |
| People          | Check their docs                              | Yes                                                   |
| Images          | Check their docs                              | `img.amodb.dev`, no key needed                        |
| Ratings         | Check their docs                              | IMDb and four other sources where known               |
| Rate limit      | Check their docs                              | 20, 40 or 120 per minute per key                      |
| Commercial use  | Check their docs for licensing                | Paid plans, see [pricing](https://amodb.dev/pricing/) |
| Compatibility   | Its own API                                   | TMDB v3 reads and OMDb                                |

## Where amodb differs

- **One key for the whole catalog.** A series, its cast, its trailers and a movie that shares an actor all use the same base URL and the same limit.
- **Ratings next to the episode guide.** `append_to_response=ratings` on series details adds IMDb and other scores in one call.
- **Plain headers for pacing.** `X-RateLimit-Remaining` and `X-RateLimit-Reset` tell a sync job how many requests are left in the 60 second window.
- **Original names preserved.** A series keeps `original_name` while `name` follows your `language`, which helps when you show a native title.

## Where TheTVDB is a better fit

- **Ordering is the product.** If your users argue about DVD against aired against absolute order, TheTVDB treats that as a core part of its model. amodb names the orderings of a show but does not return their episodes, and which groups exist differs by show.
- **Existing integrations.** If your pipeline already stores TheTVDB ids and reads its orderings, keep that part and add amodb for the extra data.
- **TV focus.** If you never show movies or people, a source built around TV has less to learn.

## Migrate to amodb

Map your stored TVDB ids once. After that, use the amodb id for every call. The find endpoint resolves series ids only. Its `tv_season_results` and `tv_episode_results` arrays are always empty, so map seasons and episodes by number.

```js
const key = process.env.AMODB_KEY;
const headers = { Authorization: `Bearer ${key}` };
const base = 'https://api.amodb.dev/3';

async function getJson(path) {
  const res = await fetch(`${base}${path}`, { headers });
  if (!res.ok) throw new Error(`${path} returned ${res.status}`);
  return res.json();
}

const found = await getJson('/find/81189?external_source=tvdb_id');
const show = found.tv_results[0];
console.log(show.id, show.name);

const groups = await getJson(`/tv/${show.id}/episode_groups`);
for (const g of groups.results) {
  console.log(g.name, g.type, g.episode_count);
}
```

The first request returns Breaking Bad with id 1396. The second lists the orderings that exist for that show, with their sizes. To compare numbering with what you store now, read the aired order from `/tv/{id}/season/{n}` and keep any alternate order on the TheTVDB side. Do that check on your ten most watched shows before you move the rest.

Each call counts as one request in the 60 second window, and a 429 carries `Retry-After`. See [find by external id](https://amodb.dev/find-by-external-id/) and [rate limits](https://amodb.dev/rate-limits/).

## Pricing

amodb is prepaid with no automatic renewal. Choose 1, 3, 6, 12 or 24 months and one of three plans at 20, 40 or 120 requests per minute. Longer periods take 10, 20, 30 or 40 percent off, and every plan gets all data. There is no free tier. Amounts are on [pricing](https://amodb.dev/pricing/).

## Questions and answers

### Can I convert TVDB ids to amodb ids?

Yes. Call /3/find/81189 with external_source=tvdb_id. The tv_results array holds the matching series, so Breaking Bad comes back with id 1396. Store the pair and use the numeric id from then on. The reverse works too: /3/tv/1396/external_ids returns tvdb_id.

### Does amodb support DVD and absolute episode order?

Only in part. GET /3/tv/{id}/episode_groups lists the groups of a show with name, type, episode_count and group_count. The contents of a group are not offered, and /3/tv/episode_group/{id} answers 404. You can see that a DVD ordering exists but cannot read its numbering.

### Is TheTVDB free to use?

TheTVDB uses an API key model, and its licensing terms are set by TheTVDB. Check their docs for the current licence and any fees. amodb is a prepaid paid API with no free tier.

### Do I get movie data as well?

Yes. Movies, people, images, videos and translations are on the same key and base URL as TV. That removes the need for a second provider if your app lists both.

### How do I find which episode airs next?

Series details include next_episode_to_air and last_episode_to_air, each with season_number, episode_number and air_date. The next one is null for a show that has ended. Details are cached for 6 hours at the edge, so poll a few times per day at most.

## Related pages

- [TV seasons and episodes API](https://amodb.dev/tv-seasons-episodes/): TV seasons and episodes API with the same paths and JSON as TMDB v3. Read a season with all its episodes, or one episode with air date, runtime and still.
- [Find by external id](https://amodb.dev/find-by-external-id/): Look up a movie, series or person by IMDb, TVDB, Wikidata or Kinopoisk id with the TMDB find endpoint, and read external ids and Wikidata facts for a title.
- [Episode guide API](https://amodb.dev/episode-guide-api/): Episode guide API with TMDB v3 season and episode endpoints: names, air dates, runtimes, stills and episode group lists for any series, in 14 languages.
- [TV series API, the TV show endpoint](https://amodb.dev/tv-series/): TV show API reference for GET /3/tv/{series_id}: names, status, seasons, networks and the next episode, in TMDB v3 JSON with content ratings and providers.
- [Quickstart](https://amodb.dev/quickstart/): Make your first amodb call: get a key, request movie details in curl, JavaScript, Python, PHP or Go, then load the poster from img.amodb.dev. Under 2 minutes.
- [Rate limits, and TMDB API limits compared](https://amodb.dev/rate-limits/): TMDB API limits compared with amodb rate limits: 20, 40 or 120 requests per minute per key in a sliding 60 second window, no daily cap, 429 with Retry-After.

Updated: 2026-10-18. Source: https://amodb.dev/thetvdb-api-alternative/