API delle collezioni

Ottenere una collezione

GET /3/collection/{collection_id} restituisce una saga: nome, una trama, una locandina, un'immagine di sfondo e l'array parts. Ogni parte è un riepilogo di film con i campi che servono per una scheda, quindi una sola chiamata può disegnare un intero scaffale della saga.

L'esempio carica la collezione 10, i film di Star Wars, e ne stampa i film in ordine di uscita.

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

Parametri

• collection_idpercorsoobbligatorio
  ID numerico della collezione, per esempio 10.
• api_keyqueryuno dei due
  La tua chiave. Usa questa o l'header Authorization: Bearer.
• languagequery
  Una delle 14 lingue servite, per esempio en-US o fr-FR. Imposta la lingua di titolo e trama di ogni parte. Predefinito en-US.

Il name e l'overview della collezione arrivano come salvati e non cambiano con language. Per alcune collezioni non sono in inglese.

Campi della risposta

Risposta di esempio

Sono mostrate due delle nove parti.

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

Le stringhe lunghe sono tagliate con ... per questa pagina. La risposta reale contiene il testo completo.

Trovare la collezione di un film

Raramente si parte dall'ID di una collezione. Si parte da un film, e la scheda dei dettagli del film dice a cosa appartiene. Il campo belongs_to_collection è un oggetto con id, name, poster_path e backdrop_path. Vale null per un film che non fa parte di una saga, come il film 550.

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

L'esempio qui sotto segue quel collegamento da un film alla sua saga in due richieste.

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

Immagini e ricerca

La locandina e l'immagine di sfondo di una saga sono i campi poster_path e backdrop_path della scheda della collezione. Costruisci da essi l'indirizzo del file come descritto nella pagina immagini. amodb non offre i percorsi /collection/{collection_id}/images e /collection/{collection_id}/translations, quindi una collezione non ha un elenco di locandine alternative né righe per lingua. I titoli delle parti seguono invece il parametro language, e traduzioni tratta i percorsi che restituiscono righe per lingua.

Per trovare una collezione per nome usa GET /3/search/collection?query=matrix, descritto nella pagina ricerca. Ogni risultato ha id, name, overview, poster_path, backdrop_path, original_language, original_name e adult.

Errori

Vedi errori per l'elenco completo e limiti di richieste per i limiti dei piani.

Note pratiche

• Le collezioni raggruppano solo film. Un film porta al massimo un oggetto belongs_to_collection, quindi un film corrisponde a una sola saga.
• Le parti arrivano in ordine di uscita. I film con data vuota vengono per ultimi, quindi indicali come non ancora datati.
• La scheda della collezione resta in cache sull'edge per 6 ore come gli altri dettagli, quindi una pagina della saga può riusare una risposta per tutto quel tempo.
• Una parte porta solo campi di riepilogo. Recupera durata, crediti e valutazioni film per film tramite i dettagli del film quando l'utente lo apre.
• Usa parts[].id come chiave di un film, non la sua posizione nella saga. Ordini e date vengono corretti nel tempo.
• Controlla che name sia nella tua lingua di visualizzazione prima di mostrarlo. Alcune collezioni hanno un nome in un'altra lingua, e language non lo cambia.