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 / |
| One episode | Check their docs | GET / |
| Which orderings exist | Aired, DVD and absolute orderings | GET / |
| Episodes inside one ordering | Check their docs | Not offered, / 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.
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.
{
"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 |
| 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_on series details adds IMDb and other scores in one call.to_ response= ratings - Plain headers for pacing.
X-RateLimit-RemainingandX-RateLimit-Resettell a sync job how many requests are left in the 60 second window. - Original names preserved. A series keeps
original_namewhilenamefollows yourlanguage, 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.
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 and 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.