API de recherche

Rechercher des films

GET /3/search/movie prend une requête texte et renvoie une liste paginée de films correspondants, la meilleure correspondance en premier. Utilisez-le pour transformer ce qu'un utilisateur a saisi en identifiant de film, puis appelez les détails du film avec cet identifiant.

L'exemple cherche Inception, restreint à 2010, et affiche l'id, le titre et la date de sortie.

curl -sSf --get "https://api.amodb.dev/3/search/movie" \
  --data-urlencode "query=inception" \
  --data-urlencode "year=2010" \
  -H "Authorization: Bearer $AMODB_KEY"

const params = new URLSearchParams({ query: 'inception', year: '2010', language: 'en-US' });
const res = await fetch(`https://api.amodb.dev/3/search/movie?${params}`, {
  headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` },
});
if (!res.ok) throw new Error(`amodb returned ${res.status}`);
const { results, total_results } = await res.json();
console.log(`${total_results} matches`);
for (const m of results.slice(0, 5)) console.log(m.id, m.title, m.release_date);

import os
import requests

r = requests.get(
    "https://api.amodb.dev/3/search/movie",
    params={"query": "inception", "year": 2010, "language": "en-US"},
    headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
    timeout=10,
)
r.raise_for_status()
data = r.json()
print(data["total_results"], "matches")
for m in data["results"][:5]:
    print(m["id"], m["title"], m["release_date"])

<?php
$url = 'https://api.amodb.dev/3/search/movie?' . http_build_query([
    'query' => 'inception',
    'year' => 2010,
    '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");
}
$data = json_decode($body, true);
foreach (array_slice($data['results'], 0, 5) as $m) {
    echo $m['id'], ' ', $m['title'], ' ', $m['release_date'], PHP_EOL;
}

package main

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

type SearchPage struct {
	TotalResults int `json:"total_results"`
	Results      []struct {
		ID          int    `json:"id"`
		Title       string `json:"title"`
		ReleaseDate string `json:"release_date"`
	} `json:"results"`
}

func main() {
	q := url.Values{"query": {"inception"}, "year": {"2010"}, "language": {"en-US"}}
	req, _ := http.NewRequest("GET", "https://api.amodb.dev/3/search/movie?"+q.Encode(), 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 p SearchPage
	if err := json.NewDecoder(res.Body).Decode(&p); err != nil {
		panic(err)
	}
	fmt.Println(p.TotalResults, "matches")
	for _, m := range p.Results {
		fmt.Println(m.ID, m.Title, m.ReleaseDate)
	}
}

Paramètres

• queryrequêteobligatoire
  Texte à chercher. Encodez-le pour l'URL : les espaces deviennent %20 ou +.
• api_keyrequêtel'un des deux
  Votre clé. Utilisez-la ou l'en-tête Authorization: Bearer.
• yearrequête
  Année à quatre chiffres. Garde les films dont une date de sortie, dans n'importe quel pays, tombe cette année-là.
• primary_release_yearrequête
  Année à quatre chiffres. Correspond uniquement à la date de sortie principale : il peut donc renvoyer moins de titres que year.
• regionrequête
  Code pays à 2 lettres en majuscules comme US. Remplace release_date par la date dans ce pays quand elle est connue. Ne retire aucun titre.
• include_adultrequête
  Accepté et ignoré. Les titres pour adultes ne sont jamais renvoyés.
• languagerequête
  Balise TMDB comme en-US ou it-IT. 14 langues de base sont servies, tout le reste se replie sur l'anglais. Par défaut en-US.
• pagerequête
  Numéro de page de 1 à 500. Par défaut 1.

Champs de la réponse

Exemple de réponse

{
  "page": 1,
  "results": [
    {
      "adult": false,
      "backdrop_path": "/zSBVQIvx4UIHoFf1oDvixHyIQrz.jpg",
      "genre_ids": [28, 878, 80],
      "id": 27205,
      "original_language": "en",
      "original_title": "Inception",
      "overview": "Cobb, a skilled thief who commits corporate espionage by infiltrating the subconscious of his targets is of...",
      "popularity": 60.9811,
      "poster_path": "/xlaY2zyzMfkhk0HSC5VUwzoZPU1.jpg",
      "release_date": "2010-07-15",
      "title": "Inception",
      "video": false,
      "vote_average": 8.373,
      "vote_count": 40459
    },
    {
      "adult": false,
      "backdrop_path": "/p8K8Z4yjaslJx5mTsIC5L6LJxQB.jpg",
      "genre_ids": [16, 28, 53],
      "id": 64956,
      "original_language": "en",
      "original_title": "Inception: The Cobol Job",
      "overview": "Cobb, Arthur and Nash are enlisted by Cobol Engineering.",
      "popularity": 1.9401,
      "poster_path": "/sNxqwtyHMNQwKWoFYDqcYTui5Ok.jpg",
      "release_date": "2010-12-07",
      "title": "Inception: The Cobol Job",
      "video": false,
      "vote_average": 7.2,
      "vote_count": 320
    },
    {
      "adult": false,
      "backdrop_path": null,
      "genre_ids": [10402],
      "id": 973484,
      "original_language": "en",
      "original_title": "Inception: Music from the Motion Picture",
      "overview": "The Special Features Blu-ray disc contains a lossless DTS-HD MA 5.1 surround mix of the Inception soundtrack.",
      "popularity": 0.4911,
      "poster_path": "/7uM4DyRVAcgagvhZoWrkrqMPbqV.jpg",
      "release_date": "2010-12-07",
      "title": "Inception: Music from the Motion Picture",
      "video": true,
      "vote_average": 7,
      "vote_count": 3
    }
  ],
  "total_pages": 1,
  "total_results": 3
}

La réponse contient les trois correspondances. Elle a été récupérée depuis l'API réelle et seules les longues chaînes overview ont été raccourcies.

Autres points de terminaison de recherche

Tous les chemins ci-dessous partagent la base https://api.amodb.dev/3, demandent query et renvoient la même enveloppe page, results, total_pages et total_results. Chacun accepte aussi page de 1 à 500. include_adult est accepté partout et ignoré.

Pour les séries, first_air_date_year garde les séries dont la première diffusion tombe cette année-là, alors que year garde aussi les séries plus anciennes diffusées cette année-là. Une recherche de the avec year=2010 renvoie The Simpsons, dont la première diffusion date de 1989, alors que la même recherche avec first_air_date_year=2010 ne la renvoie pas. Si vous envoyez les deux, les deux doivent correspondre. Les entrées de personnes portent jusqu'à 3 titres known_for, chacun avec media_type. /search/multi ignore year.

Les entités trouvées ici se poursuivent sur séries TV, personnes, collections, sociétés et chaînes et mots-clés.

Recherche multi

media_type vaut movie, tv ou person, et il indique quels champs attendre. Les entrées de films portent title, et celles de séries et de personnes portent name.

const byType = { movie: [], tv: [], person: [] };
for (const r of results) byType[r.media_type]?.push(r.title || r.name);
console.log(byType);

Erreurs

/search/tv et /search/person répondent à une requête sans correspondance par HTTP 200, un tableau results vide et total_results à 0. Pour le moment, /search/movie, /search/multi, /search/keyword, /search/company et /search/collection répondent au même cas par HTTP 500 et status_code 11. Considérez un 500 sur ces chemins comme « aucun résultat », sauf s'il se répète pour des requêtes dont vous savez qu'elles correspondent.

Voir erreurs pour la liste complète et limites de débit pour les fenêtres.

Remarques pratiques

• La périphérie met une recherche en cache 10 minutes et partage la copie entre les clés. Chaque appel compte quand même dans vos 20, 40 ou 120 requêtes par minute, car la limite de débit passe avant le cache.
• Pour une zone de recherche, attendez 300 ms après la dernière frappe et annulez la requête en cours. Une zone qui déclenche une requête à chaque touche peut épuiser une offre à 20 requêtes par minute en quelques secondes.
• Passez la requête en minuscules et supprimez les espaces en bordure avant de l'utiliser comme clé de cache de votre côté.
• Pour chercher un titre par id IMDb, laissez la recherche de côté et utilisez la recherche par identifiant externe.
• Un id de mot-clé issu de /search/keyword alimente le filtre with_keywords de découverte, et un id de société alimente with_companies.