API de séries de TV

Obter os detalhes de uma série de TV

GET /3/tv/{series_id} retorna o registro principal de uma série: nomes, sinopse, status, gêneros, emissoras, a lista de temporadas e ponteiros para o último e o próximo episódio. O id é o id numérico de TV do TMDB, então uma série que você guarda como 1396 mantém esse id aqui. Ids de filmes e ids de séries são espaços separados, então guarde sempre o tipo de mídia junto do número.

O exemplo pede Breaking Bad em inglês e acrescenta as classificações indicativas e as notas externas na mesma chamada.

curl -sSf "https://api.amodb.dev/3/tv/1396?language=en-US&append_to_response=content_ratings,ratings" \
  -H "Authorization: Bearer $AMODB_KEY"

const params = new URLSearchParams({ language: 'en-US', append_to_response: 'content_ratings,ratings' });
const res = await fetch(`https://api.amodb.dev/3/tv/1396?${params}`, {
  headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` },
});
if (!res.ok) throw new Error(`amodb returned ${res.status}`);
const show = await res.json();
const us = show.content_ratings.results.find((r) => r.iso_3166_1 === 'US');
console.log(show.name, show.status, show.number_of_seasons, us?.rating);

import os
import requests

r = requests.get(
    "https://api.amodb.dev/3/tv/1396",
    params={"language": "en-US", "append_to_response": "content_ratings,ratings"},
    headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
    timeout=10,
)
r.raise_for_status()
show = r.json()
us = next((x for x in show["content_ratings"]["results"] if x["iso_3166_1"] == "US"), None)
print(show["name"], show["status"], show["number_of_seasons"], us and us["rating"])

<?php
$url = 'https://api.amodb.dev/3/tv/1396?' . http_build_query([
    'language' => 'en-US',
    'append_to_response' => 'content_ratings,ratings',
]);
$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AMODB_KEY')],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status !== 200) {
    throw new RuntimeException("amodb returned $status");
}
$show = json_decode($body, true);
echo $show['name'], ' ', $show['status'], ' ', $show['number_of_seasons'], PHP_EOL;

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"net/url"
	"os"
	"time"
)

type Show struct {
	Name             string `json:"name"`
	Status           string `json:"status"`
	NumberOfSeasons  int    `json:"number_of_seasons"`
	NumberOfEpisodes int    `json:"number_of_episodes"`
	Next             *struct {
		AirDate string `json:"air_date"`
	} `json:"next_episode_to_air"`
}

func main() {
	q := url.Values{"language": {"en-US"}}
	req, _ := http.NewRequest("GET", "https://api.amodb.dev/3/tv/1396?"+q.Encode(), nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("AMODB_KEY"))
	client := &http.Client{Timeout: 10 * time.Second}
	res, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK {
		panic(res.Status)
	}
	var s Show
	if err := json.NewDecoder(res.Body).Decode(&s); err != nil {
		panic(err)
	}
	next := "none scheduled"
	if s.Next != nil {
		next = s.Next.AirDate
	}
	fmt.Println(s.Name, s.Status, s.NumberOfSeasons, s.NumberOfEpisodes, next)
}

Parâmetros

• series_idcaminhoobrigatório
  Id numérico da série, por exemplo 1396.
• api_keyconsultaum dos dois
  Sua chave. Use este parâmetro ou o header Authorization: Bearer.
• languageconsulta
  Tag do TMDB como en-US, uk-UA ou es-ES. 14 idiomas base são atendidos. Padrão en-US.
• append_to_responseconsulta
  Lista separada por vírgulas de subrecursos para juntar à resposta, até 20 valores.

Campos da resposta

Exemplo de resposta

GET /3/tv/1396?language=en-US&append_to_response=content_ratings,ratings, com arrays e textos longos abreviados:

{
  "adult": false,
  "backdrop_path": "/ycFcYYnzVc8mWw41neszGPMyKc3.jpg",
  "created_by": [],
  "episode_run_time": [
    48,
    49
  ],
  "first_air_date": "2008-01-20",
  "genres": [
    {
      "id": 18,
      "name": "Drama"
    },
    {
      "id": 80,
      "name": "Crime"
    }
  ],
  "homepage": "",
  "id": 1396,
  "in_production": false,
  "languages": [
    "en"
  ],
  "last_air_date": "2013-09-29",
  "last_episode_to_air": {
    "air_date": "2013-09-29",
    "episode_number": 16,
    "episode_type": "standard",
    "id": 62161,
    "name": "פלינה",
    "overview": "הסדרה זוכת הפרסים מגיעה לסיום דרמתי בפרק החותם אותה.",
    "production_code": "",
    "runtime": 56,
    "season_number": 5,
    "show_id": 1396,
    "still_path": "/pA0YwyhvdDXP3BEGL2grrIhq8aM.jpg",
    "vote_average": 0,
    "vote_count": 0
  },
  "name": "Breaking Bad",
  "next_episode_to_air": null,
  "networks": [
    {
      "id": 174,
      "logo_path": "/pmvRmATOCaDykE6JrVoeYxlFHw3.png",
      "name": "AMC",
      "origin_country": "US"
    }
  ],
  "number_of_episodes": 62,
  "number_of_seasons": 5,
  "origin_country": [
    "US"
  ],
  "original_language": "en",
  "original_name": "Breaking Bad",
  "overview": "Walter White, a New Mexico chemistry teacher, is diagnosed with Stage III cancer and given a prognosis of o...",
  "popularity": 268.4968,
  "poster_path": "/anFx9aTOOYqgS3v7x3R84Kz67ly.jpg",
  "production_companies": [
    {
      "id": 2605,
      "logo_path": null,
      "name": "Gran Via Productions",
      "origin_country": "US"
    },
    {
      "id": 11073,
      "logo_path": "/wHs44fktdoj6c378ZbSWfzKsM2Z.png",
      "name": "Sony Pictures Television",
      "origin_country": "US"
    }
  ],
  "production_countries": [
    {
      "iso_3166_1": "US",
      "name": "United States of America"
    }
  ],
  "seasons": [
    {
      "air_date": "2009-02-17",
      "episode_count": 9,
      "id": 3577,
      "name": "特别篇",
      "overview": "",
      "poster_path": "/ikBSCmgG5Z4jequUUAjKpf1QG3T.jpg",
      "season_number": 0,
      "vote_average": 0
    },
    {
      "air_date": "2008-01-20",
      "episode_count": 7,
      "id": 3572,
      "name": "Season 1",
      "overview": "High school chemistry teacher Walter White's life is suddenly transformed by a dire medical diagnosis. Stre...",
      "poster_path": "/91EIXdWxmp2mHNRsSuDW3WyDJLj.jpg",
      "season_number": 1,
      "vote_average": 0
    }
  ],
  "spoken_languages": [
    {
      "english_name": "English",
      "iso_639_1": "en",
      "name": "English"
    },
    {
      "english_name": "Spanish",
      "iso_639_1": "es",
      "name": "Español"
    }
  ],
  "status": "Ended",
  "tagline": "Change the equation.",
  "vote_average": 9,
  "vote_count": 18863,
  "content_ratings": {
    "results": [
      {
        "descriptors": [],
        "iso_3166_1": "AT",
        "rating": "16"
      },
      {
        "descriptors": [],
        "iso_3166_1": "AU",
        "rating": "MA 15+"
      }
    ]
  },
  "ratings": {
    "imdb": {
      "value": 9.5,
      "votes": 2671962
    },
    "kinopoisk": {
      "value": 8.9,
      "votes": null
    },
    "metacritic": null,
    "rotten_tomatoes": {
      "value": 96,
      "votes": null
    },
    "tmdb": {
      "value": 9,
      "votes": 18863
    }
  }
}

Os blocos content_ratings e ratings vêm de append_to_response. Nomes e sinopses dentro de seasons, last_episode_to_air e next_episode_to_air são guardados por registro e podem não seguir language, como mostra o nome de episódio em hebraico acima. Leia o texto localizado de temporadas e episódios no endpoint de temporada.

Status e ponteiros de episódio

status diz em que ponto da vida a série está, e next_episode_to_air diz quando olhar de novo.

Uma série em andamento entre temporadas tem next_episode_to_air null, então leia null como “sem data conhecida” e não como “encerrada”.

O array seasons lista um resumo por temporada, e a temporada 0 guarda os especiais. Para ler os episódios de uma temporada, chame o endpoint de temporadas e episódios.

Endpoints de séries relacionados

Todos os caminhos compartilham a base https://api.amodb.dev/3, e os endpoints com texto localizado também aceitam language.

As listas de recomendações e de semelhantes sempre retornam a página 1 com 20 itens. A resposta de lists é paginada com page, 20 listas por página. As outras listas paginadas da API aceitam page de 1 a 500.

As classificações indicativas voltam como entradas de results com iso_3166_1, rating e descriptors, então escolha a entrada que corresponde ao país do espectador. Os provedores de streaming são indexados por código de país, e cada país traz um link mais as listas flatrate, rent e buy com provider_id, provider_name, logo_path e display_priority. Os ids de provedores para filtrar vêm das listas de consulta em gêneros e listas de consulta.

A lista de grupos de episódios retorna id (uma string), name, description, type, episode_count, group_count e network. O amodb lista os grupos, mas não oferece um endpoint que retorne os episódios de um grupo. Ele também não oferece os caminhos changes do TMDB.

Juntar mais dados em uma só chamada

Liste subrecursos em append_to_response e cada um chega sob a própria chave. A chamada inteira conta uma vez nas suas 20, 40 ou 120 requisições por minuto. Funcionam até 20 valores, e nomes desconhecidos são ignorados sem erro. Estes valores funcionam em uma série:

Erros

Uma chamada com falha retorna o corpo de erro do TMDB. Um id errado dá status_code 34 com a mensagem “The resource you requested could not be found.”

A lista completa está em erros, e os limites por plano estão em limites de requisições.

Notas práticas

• Os detalhes da série e todos os subrecursos acima têm cache de 6 horas. Consulte last_episode_to_air no máximo algumas vezes por dia.
• Peça o idioma que você exibe. Um overview vazio significa que não existe tradução, então peça de novo com en-US para ter um fallback.
• Use number_of_seasons como limite do laço quando buscar todas as temporadas, uma chamada para cada.
• Para listar séries em vez de ler uma só, veja busca, discover e em alta e listas.