API de colecciones

Obtener una colección

GET /3/collection/{collection_id} devuelve una saga: su nombre, una sinopsis, un póster, una imagen de fondo (backdrop) y el array parts. Cada parte es un resumen de película con los campos que necesitas para una tarjeta, así que una sola llamada puede dibujar una fila completa de la saga.

El ejemplo carga la colección 10, las películas de Star Wars, e imprime sus películas en orden de estreno.

curl -s "https://api.amodb.dev/3/collection/10?language=en-US" \
  -H "Authorization: Bearer $AMODB_KEY"

const url = 'https://api.amodb.dev/3/collection/10?language=en-US';
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` } });
if (!res.ok) throw new Error(`amodb returned ${res.status}`);
const collection = await res.json();
console.log(collection.name);
for (const p of collection.parts) console.log(p.release_date || 'not dated', p.title);

import os
import requests

r = requests.get(
    "https://api.amodb.dev/3/collection/10",
    params={"language": "en-US"},
    headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
    timeout=10,
)
r.raise_for_status()
collection = r.json()
print(collection["name"])
for p in collection["parts"]:
    print(p.get("release_date") or "not dated", p["title"])

<?php
$url = 'https://api.amodb.dev/3/collection/10?language=en-US';
$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");
}
$collection = json_decode($body, true);
echo $collection['name'], PHP_EOL;
foreach ($collection['parts'] as $p) {
    echo $p['release_date'] ?: 'not dated', ' ', $p['title'], PHP_EOL;
}

package main

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

type Collection struct {
	Name  string `json:"name"`
	Parts []struct {
		Title       string `json:"title"`
		ReleaseDate string `json:"release_date"`
	} `json:"parts"`
}

func main() {
	url := "https://api.amodb.dev/3/collection/10?language=en-US"
	req, _ := http.NewRequest("GET", url, 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 c Collection
	if err := json.NewDecoder(res.Body).Decode(&c); err != nil {
		panic(err)
	}
	fmt.Println(c.Name)
	for _, p := range c.Parts {
		date := p.ReleaseDate
		if date == "" {
			date = "not dated"
		}
		fmt.Println(date, p.Title)
	}
}

Parámetros

• collection_idrutaobligatorio
  Id numérico de la colección, por ejemplo 10.
• api_keyconsultauno de los dos
  Tu clave. Usa esta o el encabezado Authorization: Bearer.
• languageconsulta
  Uno de los 14 idiomas servidos, por ejemplo en-US o fr-FR. Define el idioma del título y la sinopsis de cada parte. Valor por defecto en-US.

El name y el overview de la propia colección llegan tal como están guardados y no cambian con language. En algunas colecciones no están en inglés.

Campos de la respuesta

Ejemplo de respuesta

Se muestran dos de las nueve partes.

{
  "id": 10,
  "name": "Star Wars Collection",
  "overview": "An epic space-opera theatrical film series, which depicts the adventures of various cha...",
  "poster_path": "/pWVLFh4OuejTpUaDQbB1C4zoS2p.jpg",
  "backdrop_path": "/iY2ujEY2m68OTTlPFTiHub9joHS.jpg",
  "parts": [
    {
      "adult": false,
      "backdrop_path": "/zqkmTXzjkAgXmEWLRsY4UpTWCeo.jpg",
      "genre_ids": [12, 28, 878],
      "id": 11,
      "original_language": "en",
      "original_title": "Star Wars",
      "overview": "Princess Leia is captured and held hostage by the evil Imperial forces in their effort...",
      "popularity": 70.481,
      "poster_path": "/fai0rspsNeJCS69wHNjOdWxcI7P.jpg",
      "release_date": "1977-05-25",
      "title": "Star Wars",
      "video": false,
      "vote_average": 8.207,
      "vote_count": 23025,
      "media_type": "movie"
    },
    {
      "adult": false,
      "backdrop_path": "/k9pshruhCpJAdH9RaGJO6jaWQ4X.jpg",
      "genre_ids": [12, 28, 878],
      "id": 1891,
      "original_language": "en",
      "original_title": "The Empire Strikes Back",
      "overview": "The epic saga continues as Luke Skywalker, in hopes of defeating the evil Galactic Empi...",
      "popularity": 29.9034,
      "poster_path": "/nNAeTmF4CtdSgMDplXTDPOpYzsX.jpg",
      "release_date": "1980-05-20",
      "title": "The Empire Strikes Back",
      "video": false,
      "vote_average": 8.393,
      "vote_count": 18990,
      "media_type": "movie"
    }
  ]
}

Las cadenas largas se cortan con ... en esta página. La respuesta real contiene el texto completo.

Encontrar la colección de una película

Pocas veces empiezas desde un id de colección. Empiezas desde una película, y el registro de detalles de película te dice a cuál pertenece. El campo belongs_to_collection es un objeto con id, name, poster_path y backdrop_path. Es null cuando la película no forma parte de una saga, como la película 550.

{
  "id": 11,
  "title": "Star Wars",
  "belongs_to_collection": {
    "id": 10,
    "name": "Star Wars Collection",
    "poster_path": "/pWVLFh4OuejTpUaDQbB1C4zoS2p.jpg",
    "backdrop_path": "/iY2ujEY2m68OTTlPFTiHub9joHS.jpg"
  }
}

El siguiente ejemplo sigue ese vínculo desde una película hasta su saga en dos solicitudes.

const base = 'https://api.amodb.dev/3';
const headers = { Authorization: `Bearer ${process.env.AMODB_KEY}` };

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 movie = await getJson('/movie/11');
if (movie.belongs_to_collection) {
  const collection = await getJson(`/collection/${movie.belongs_to_collection.id}`);
  console.log(movie.title, 'is one of', collection.parts.length, 'films in', collection.name);
}

Imágenes y búsqueda

El póster y la imagen de fondo de una saga son los campos poster_path y backdrop_path del registro de la colección. Construye la dirección del archivo a partir de ellos, como se describe en imágenes. amodb no ofrece las rutas /collection/{collection_id}/images y /collection/{collection_id}/translations, así que una colección no tiene una lista de pósters alternativos ni filas por idioma. Los títulos de las partes siguen el parámetro language, y traducciones cubre las rutas que sí devuelven filas por idioma.

Para encontrar una colección por nombre, usa GET /3/search/collection?query=matrix, descrita en búsqueda. Cada resultado tiene id, name, overview, poster_path, backdrop_path, original_language, original_name y adult.

Errores

Consulta errores para ver la lista completa y límites de solicitudes para los límites de cada plan.

Notas prácticas

• Las colecciones agrupan solo películas. Una película tiene como máximo un objeto belongs_to_collection, así que cada película corresponde a una sola saga.
• Las partes llegan en orden de estreno. Las películas con fecha vacía van al final, así que márcalas como sin fecha todavía.
• El registro de la colección se guarda en la caché perimetral 6 horas, como el resto de los detalles, así que una página de saga puede reutilizar una respuesta durante ese tiempo.
• Una parte trae solo campos de resumen. Pide la duración, los créditos y las puntuaciones de cada película en los detalles de película cuando el usuario la abra.
• Usa parts[].id como clave de una película, no su posición en la saga. Los órdenes y las fechas se corrigen con el tiempo.
• Comprueba que name esté en tu idioma de visualización antes de mostrarlo. Algunas colecciones traen el nombre en otro idioma, y language no lo cambia.