API de detalhes de filmes

Obter os detalhes de um filme

GET /3/movie/{movie_id} retorna o registro principal de um filme: títulos, sinopse, duração, gêneros, data de lançamento, orçamento, receita, produtoras e caminhos de imagens. O id é o mesmo id numérico que o TMDB usa, então um filme que você já guarda como 550 mantém esse id aqui.

O exemplo abaixo pede o filme em inglês e acrescenta as avaliações dele na mesma chamada.

curl -s "https://api.amodb.dev/3/movie/550?language=en-US&append_to_response=ratings" \
  -H "Authorization: Bearer $AMODB_KEY"

const url = 'https://api.amodb.dev/3/movie/550?language=en-US&append_to_response=ratings';
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` } });
if (!res.ok) throw new Error(`amodb returned ${res.status}`);
const movie = await res.json();
console.log(movie.title, movie.runtime, movie.ratings.imdb?.value);

import os
import requests

r = requests.get(
    "https://api.amodb.dev/3/movie/550",
    params={"language": "en-US", "append_to_response": "ratings"},
    headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
    timeout=10,
)
r.raise_for_status()
movie = r.json()
imdb = movie["ratings"]["imdb"]
print(movie["title"], movie["runtime"], imdb and imdb["value"])

<?php
$url = 'https://api.amodb.dev/3/movie/550?language=en-US&append_to_response=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");
}
$movie = json_decode($body, true);
echo $movie['title'], ' ', $movie['runtime'], ' ', $movie['ratings']['imdb']['value'] ?? 'n/a', PHP_EOL;

package main

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

type Movie struct {
	Title   string `json:"title"`
	Runtime int    `json:"runtime"`
}

func main() {
	url := "https://api.amodb.dev/3/movie/550?language=en-US"
	req, _ := http.NewRequest("GET", url, nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("AMODB_KEY"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK {
		panic(res.Status)
	}
	var m Movie
	json.NewDecoder(res.Body).Decode(&m)
	fmt.Println(m.Title, m.Runtime)
}

Parâmetros

• movie_idcaminhoobrigatório
  Id numérico do filme, por exemplo 550.
• api_keyconsultaum dos dois
  Sua chave. Use este parâmetro ou o header Authorization: Bearer.
• languageconsulta
  Tag do TMDB como en-US, ru-RU ou pt-BR. 14 idiomas base são atendidos. Padrão en-US.
• append_to_responseconsulta
  Lista separada por vírgulas com até 20 subrecursos para juntar à resposta.

Campos da resposta

Exemplo de resposta

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

{
  "adult": false,
  "backdrop_path": "/b9HyPoxwxjxkWEUL5ErZdhApQe2.jpg",
  "belongs_to_collection": null,
  "budget": 63000000,
  "genres": [
    {
      "id": 18,
      "name": "Drama"
    },
    {
      "id": 53,
      "name": "Thriller"
    }
  ],
  "homepage": "https://www.20thcenturystudios.com/movies/fight-club",
  "id": 550,
  "imdb_id": "tt0137523",
  "origin_country": [
    "US",
    "DE"
  ],
  "original_language": "en",
  "original_title": "Fight Club",
  "overview": "A ticking-time-bomb insomniac and a slippery soap salesman channel primal male aggression into a shocking n...",
  "popularity": 39.0054,
  "poster_path": "/jSziioSwPVrOy9Yow3XhWIBDjq1.jpg",
  "production_companies": [
    {
      "id": 25,
      "logo_path": "/nM2MfoMqzJQRiSynsDabOtFKetD.png",
      "name": "20th Century Fox",
      "origin_country": "US"
    },
    {
      "id": 508,
      "logo_path": "/4sGWXoboEkWPphI6es6rTmqkCBh.png",
      "name": "Regency Enterprises",
      "origin_country": "US"
    }
  ],
  "production_countries": [
    {
      "iso_3166_1": "US",
      "name": "United States of America"
    },
    {
      "iso_3166_1": "DE",
      "name": "Germany"
    }
  ],
  "release_date": "1999-10-15",
  "revenue": 101209702,
  "runtime": 139,
  "spoken_languages": [
    {
      "english_name": "English",
      "iso_639_1": "en",
      "name": "English"
    }
  ],
  "status": "Released",
  "tagline": "Mischief. Mayhem. Soap.",
  "title": "Fight Club",
  "video": false,
  "vote_average": 8.437,
  "vote_count": 33039,
  "ratings": {
    "imdb": {
      "value": 8.8,
      "votes": 2669989
    },
    "kinopoisk": {
      "value": 8.7,
      "votes": null
    },
    "metacritic": {
      "value": 67,
      "votes": null
    },
    "rotten_tomatoes": {
      "value": 81,
      "votes": null
    },
    "tmdb": {
      "value": 8.437,
      "votes": 33039
    }
  }
}

O bloco ratings vem de append_to_response. Cada provedor é um objeto {value, votes} ou null, como descrito em avaliações.

Combinar dados com append_to_response

Uma chamada pode substituir seis. Liste os subrecursos de que você precisa e cada um chega sob a própria chave. Os valores padrão do TMDB funcionam: credits, videos, images, keywords, translations, external_ids, release_dates, alternative_titles, recommendations, similar, reviews, lists e watch/providers. O amodb acrescenta mais cinco.

Cada bloco acrescentado conta como parte de uma única requisição HTTP. Uma requisição com dez valores acrescentados ainda usa uma das suas 20, 40 ou 120 requisições por minuto. Os blocos ratings, moods e soundtracks acrescentados omitem a chave id que os caminhos isolados retornam.

Endpoints de filmes relacionados

Todos os caminhos abaixo compartilham a base https://api.amodb.dev/3 e o parâmetro language.

As listas de recomendados 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 listas paginadas no resto da API aceitam page de 1 a 500.

Créditos, imagens, vídeos, traduções, palavras-chave e ids externos têm páginas próprias: créditos, imagens, vídeos e trailers, traduções, palavras-chave e buscar por ID externo. O amodb não oferece os caminhos changes do TMDB.

Erros

Os erros usam o corpo do TMDB, por exemplo {"success": false, "status_code": 34, "status_message": "The resource you requested could not be found."}.

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

Notas práticas

• Guarde id e imdb_id juntos. Qualquer um dos dois encontra o filme de novo por meio de buscar por ID externo.
• Peça o idioma que você exibe. Um campo de texto pode vir vazio quando não existe tradução nesse idioma, então verifique se há uma string vazia e peça de novo em en-US se precisar de um fallback.
• Guarde os detalhes em cache do seu lado por algumas horas. O cache do servidor já os mantém por 6 horas, então um cache menor no cliente não traz ganho.
• Para listar filmes em vez de ler um só, veja a busca, o discover e em alta e listas.