API de detalles de película

Obtener los detalles de una película

GET /3/movie/{movie_id} devuelve el registro principal de una película: títulos, sinopsis, duración, géneros, fecha de estreno, presupuesto, ingresos, productoras y rutas de imágenes. El id es el mismo id numérico que usa TMDB, así que una película que ya guardas como 550 conserva ese id aquí.

El ejemplo de abajo pide la película en inglés y añade sus puntuaciones en la misma llamada.

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_idrutaobligatorio
  Id numérico de la película, por ejemplo 550.
• api_keyconsultauno de los dos
  Tu clave. Usa esta o el encabezado Authorization: Bearer.
• languageconsulta
  Etiqueta de TMDB como en-US, ru-RU o pt-BR. Se sirven 14 idiomas base. Valor por defecto en-US.
• append_to_responseconsulta
  Lista separada por comas de hasta 20 subrecursos que se unen a la respuesta.

Campos de la respuesta

Ejemplo de respuesta

GET /3/movie/550?language=en-US&append_to_response=ratings, con arrays y textos largos acortados:

{
  "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
    }
  }
}

El bloque ratings viene de append_to_response. Cada proveedor es un objeto {value, votes} o null, como se describe en puntuaciones.

Combinar datos con append_to_response

Una llamada puede reemplazar seis. Enumera los subrecursos que necesitas y cada uno llega bajo su propia clave. Funcionan los valores estándar de TMDB: credits, videos, images, keywords, translations, external_ids, release_dates, alternative_titles, recommendations, similar, reviews, lists y watch/providers. amodb añade cinco más.

Cada bloque añadido cuenta como parte de una sola solicitud HTTP. Una solicitud con diez valores añadidos sigue usando una de tus 20, 40 o 120 solicitudes por minuto. Los bloques añadidos ratings, moods y soundtracks omiten la clave id que devuelven las rutas independientes.

Otros endpoints de películas

Todas las rutas de abajo comparten la base https://api.amodb.dev/3 y el parámetro language.

Las listas de recomendadas y similares siempre devuelven la página 1 con 20 elementos. La respuesta de lists se pagina con page, 20 listas por página. Las listas paginadas del resto de la API aceptan page de 1 a 500.

Los créditos, las imágenes, los vídeos, las traducciones, las palabras clave y los ids externos tienen sus propias páginas: créditos, imágenes, vídeos y tráilers, traducciones, palabras clave y buscar por id externo. amodb no ofrece las rutas changes de TMDB.

Errores

Los errores usan el cuerpo de TMDB, por ejemplo {"success": false, "status_code": 34, "status_message": "The resource you requested could not be found."}.

La lista completa está en la página de errores, y los límites de cada plan en límites de solicitudes.

Notas prácticas

• Guarda el id y el imdb_id juntos. Cualquiera de los dos vuelve a encontrar la película con la búsqueda por id externo.
• Pide el idioma que muestras. Un campo de texto puede venir vacío cuando no existe traducción en ese idioma, así que comprueba si es una cadena vacía y vuelve a pedir en en-US si necesitas una alternativa.
• Guarda los detalles en caché de tu lado durante unas horas. La caché del servidor ya los conserva 6 horas, así que una caché de cliente más corta no aporta nada.
• Para listar películas en lugar de leer una, consulta la búsqueda, discover y tendencias y listas.