API di ricerca

Cercare film

GET /3/search/movie prende un testo di ricerca e restituisce una lista paginata di film corrispondenti, prima la corrispondenza migliore. Usalo per trasformare ciò che un utente ha digitato in un ID film, poi chiama i dettagli del film con quell'ID.

L'esempio cerca Inception, limitato al 2010, e stampa ID, titolo e data di uscita.

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

Parametri

• queryqueryobbligatorio
  Testo da cercare. Codificalo per l'URL: gli spazi diventano %20 o +.
• api_keyqueryuno dei due
  La tua chiave. Usa questa o l'header Authorization: Bearer.
• yearquery
  Anno di quattro cifre. Tiene i film con una qualsiasi data di uscita, in qualsiasi paese, in quell'anno.
• primary_release_yearquery
  Anno di quattro cifre. Corrisponde solo alla data di uscita principale, quindi può restituire meno titoli di year.
• regionquery
  Codice paese di 2 lettere maiuscole come US. Sostituisce release_date con la data in quel paese quando è nota. Non rimuove titoli.
• include_adultquery
  Accettato e ignorato. I titoli per adulti non vengono mai restituiti.
• languagequery
  Tag TMDB come en-US o it-IT. Sono servite 14 lingue di base, tutto il resto ripiega sull'inglese. Predefinito en-US.
• pagequery
  Numero di pagina da 1 a 500. Predefinito 1.

Campi della risposta

Risposta di esempio

{
  "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 risposta contiene tutte e tre le corrispondenze. È stata recuperata dall'API reale e sono state accorciate solo le stringhe overview lunghe.

Altri endpoint di ricerca

Tutti i percorsi qui sotto condividono la base https://api.amodb.dev/3, richiedono query e restituiscono la stessa busta page, results, total_pages e total_results. Ognuno accetta anche page da 1 a 500. include_adult è accettato ovunque e ignorato.

Per le serie TV, first_air_date_year tiene le serie la cui prima messa in onda cade in quell'anno, mentre year tiene anche le serie più vecchie andate in onda in quell'anno. Una ricerca di the con year=2010 restituisce The Simpsons, andata in onda per la prima volta nel 1989, mentre la stessa ricerca con first_air_date_year=2010 no. Se invii entrambi, devono corrispondere entrambi. Le voci delle persone portano fino a 3 titoli known_for, ciascuno con media_type. /search/multi ignora year.

Le entità trovate qui proseguono nelle pagine serie TV, persone, collezioni, società ed emittenti e parole chiave.

Ricerca multi

media_type è movie, tv o person, e ti dice quali campi aspettarti. Le voci dei film portano title e quelle di serie TV e persone portano name.

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

Errori

/search/tv e /search/person rispondono a una query senza corrispondenze con HTTP 200, un array results vuoto e total_results pari a 0. Al momento /search/movie, /search/multi, /search/keyword, /search/company e /search/collection rispondono allo stesso caso con HTTP 500 e status_code 11. Tratta un 500 su quei percorsi come «nessun risultato», a meno che non si ripeta per query che sai corrispondere.

Vedi errori per l'elenco completo e limiti di richieste per le finestre.

Note pratiche

• L'edge mette in cache una ricerca per 10 minuti e condivide la copia tra le chiavi. Ogni chiamata conta comunque nelle tue 20, 40 o 120 richieste al minuto, perché il limite viene prima della cache.
• Per una casella di ricerca, aspetta 300 ms dopo l'ultima battuta e annulla la richiesta in corso. Una casella che invia a ogni tasto può consumare in pochi secondi un piano da 20 richieste al minuto.
• Metti in minuscolo e togli gli spazi ai bordi della query prima di usarla come chiave di cache dalla tua parte.
• Per cercare un titolo per ID IMDb, salta la ricerca e usa la ricerca per ID esterno.
• Un ID di parola chiave da /search/keyword alimenta il filtro with_keywords di discover, e un ID di società alimenta with_companies.