API des collections

Obtenir une collection

GET /3/collection/{collection_id} renvoie une saga : son nom, un résumé, une affiche, une image de fond et le tableau parts. Chaque partie est un résumé de film avec les champs nécessaires pour une carte : un seul appel peut donc dessiner toute une étagère de saga.

L'exemple charge la collection 10, les films Star Wars, et affiche ses films dans l'ordre de sortie.

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

Paramètres

• collection_idcheminobligatoire
  Identifiant numérique de la collection, par exemple 10.
• api_keyrequêtel'un des deux
  Votre clé. Utilisez-la ou l'en-tête Authorization: Bearer.
• languagerequête
  L'une des 14 langues servies, par exemple en-US ou fr-FR. Fixe la langue du titre et du résumé de chaque partie. Par défaut en-US.

Le name et l'overview propres à la collection sont fournis tels que stockés et ne changent pas avec language. Pour certaines collections, ils ne sont pas en anglais.

Champs de la réponse

Exemple de réponse

Deux des neuf parties sont montrées.

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

Les longues chaînes sont coupées avec ... pour cette page. La vraie réponse contient le texte complet.

Trouver la collection d'un film

On part rarement d'un identifiant de collection. On part d'un film, et la fiche de détails du film indique à quoi il appartient. Le champ belongs_to_collection est un objet avec id, name, poster_path et backdrop_path. Il vaut null pour un film qui ne fait pas partie d'une saga, comme le 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'exemple ci-dessous suit ce lien d'un film à sa saga en deux requêtes.

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

Visuels et recherche

L'affiche et l'image de fond d'une saga sont les champs poster_path et backdrop_path de la fiche de collection. Construisez-en l'adresse du fichier comme décrit sur images. amodb ne propose pas les chemins /collection/{collection_id}/images et /collection/{collection_id}/translations : une collection n'a donc ni liste d'affiches alternatives ni lignes par langue. Les titres des parties suivent plutôt le paramètre language, et traductions couvre les chemins qui renvoient des lignes par langue.

Pour trouver une collection par son nom, utilisez GET /3/search/collection?query=matrix, décrit sur recherche. Chaque résultat a id, name, overview, poster_path, backdrop_path, original_language, original_name et adult.

Erreurs

Voir erreurs pour la liste complète et limites de débit pour les limites des offres.

Remarques pratiques

• Les collections ne regroupent que des films. Un film porte au plus un objet belongs_to_collection : un film correspond donc à une seule saga.
• Les parties arrivent dans l'ordre de sortie. Les films dont la date est vide viennent en dernier : indiquez donc qu'ils ne sont pas encore datés.
• La fiche de collection est mise en cache 6 heures en périphérie comme les autres détails : une page de saga peut donc réutiliser une réponse pendant tout ce temps.
• Une partie ne porte que des champs de résumé. Récupérez la durée, la distribution et les notes film par film via les détails du film quand l'utilisateur l'ouvre.
• Utilisez parts[].id comme clé d'un film, pas sa position dans la saga. Les ordres et les dates sont corrigés avec le temps.
• Vérifiez que name est dans votre langue d'affichage avant de l'afficher. Certaines collections portent un nom dans une autre langue, et language ne le change pas.