Alternativa à API do TheTVDB

Qual escolher para um projeto de TV

O TheTVDB é focado em TV e mantém várias ordenações de episódios por série, incluindo exibição, DVD e absoluta, sob um modelo de chave de API. Consulte a documentação deles sobre licenciamento antes de planejar um produto comercial. Escolha o amodb quando quiser TV, filmes e pessoas com uma chave, caminhos TMDB v3 e 14 idiomas. Escolha o TheTVDB quando a numeração alternativa exata for o centro do seu app, porque o amodb lista os grupos de episódios de uma série, mas não serve o que há dentro deles.

Como os dados de TV se correspondem

Os conceitos se alinham, mas os nomes diferem. Esta tabela cobre o que um app de TV costuma ler.

Os campos de episódio usam os nomes do TMDB: air_date, episode_number, season_number, runtime e still_path. Os external_ids de temporada e episódio são todos null, então o ID do TVDB de uma única temporada ou episódio não pode ser lido no amodb. Una os registros por season_number e episode_number. Os detalhes estão em temporadas e episódios.

O que a lista de grupos de episódios retorna

A chamada de lista mostra quais ordenações existem para uma série. Ela não retorna os episódios dentro delas.

Esta é uma resposta real para 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
    }
  ]
}

Algumas séries retornam uma ordem de exibição e outras várias, e algumas retornam um array results vazio. Teste as séries que importam para você. Como o conteúdo de um grupo não é oferecido, um app que precisa do número em DVD ou absoluto de cada episódio não consegue obtê-lo no amodb.

Comparação de recursos

Onde o amodb se diferencia

• Uma chave para o catálogo inteiro. Uma série, seu elenco, seus trailers e um filme que compartilha um ator usam a mesma URL base e o mesmo limite.
• Avaliações ao lado do guia de episódios. append_to_response=ratings nos detalhes da série acrescenta o IMDb e outras notas em uma chamada.
• Cabeçalhos simples para controlar o ritmo. X-RateLimit-Remaining e X-RateLimit-Reset dizem a um job de sincronização quantas requisições restam na janela de 60 segundos.
• Nomes originais preservados. Uma série mantém original_name enquanto name segue o seu language, o que ajuda quando você mostra um título nativo.

Onde o TheTVDB é mais indicado

• A ordenação é o produto. Se os seus usuários discutem ordem de DVD, de exibição ou absoluta, o TheTVDB trata isso como parte central do seu modelo. O amodb nomeia as ordenações de uma série, mas não retorna os episódios delas, e os grupos que existem variam por série.
• Integrações existentes. Se o seu pipeline já guarda IDs do TheTVDB e lê as ordenações dele, mantenha essa parte e acrescente o amodb para os dados extras.
• Foco em TV. Se você nunca mostra filmes ou pessoas, uma fonte construída em torno de TV tem menos a aprender.

Migrar para o amodb

Mapeie uma vez os IDs do TVDB que você guarda. Depois, use o ID do amodb em toda chamada. O endpoint find resolve apenas IDs de série. Seus arrays tv_season_results e tv_episode_results são sempre vazios, então mapeie temporadas e episódios por número.

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);
}

A primeira requisição retorna Breaking Bad com o ID 1396. A segunda lista as ordenações que existem para essa série, com seus tamanhos. Para comparar a numeração com o que você guarda hoje, leia a ordem de exibição em /tv/{id}/season/{n} e mantenha qualquer ordem alternativa no lado do TheTVDB. Faça essa verificação nas suas dez séries mais assistidas antes de migrar o resto.

Cada chamada conta como uma requisição na janela de 60 segundos, e um 429 traz Retry-After. Veja busca por ID externo e limites de requisições.

Preços

O amodb é pré-pago, sem renovação automática. Escolha 1, 3, 6, 12 ou 24 meses e um de três planos de 20, 40 ou 120 requisições por minuto. Períodos mais longos dão 10, 20, 30 ou 40 por cento de desconto, e todo plano recebe todos os dados. Não há plano gratuito. Os valores estão em preços.