API căutare

Caută filme

GET /3/search/movie primește o interogare text și întoarce o listă paginată de filme potrivite, cea mai bună potrivire prima. Folosește-l ca să transformi ce a tastat un utilizator într-un ID de film, apoi apelează detalii film cu acel ID.

Exemplul caută Inception, restrâns la 2010, și afișează ID-ul, titlul și data lansării.

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

• queryinterogareobligatoriu
  Textul de căutat. Codifică-l ca URL: spațiile devin %20 sau +.
• api_keyinterogareuna dintre cele două
  Cheia ta. Folosește-o pe aceasta sau antetul Authorization: Bearer.
• yearinterogare
  An din patru cifre. Păstrează filmele cu orice dată de lansare din acel an, în orice țară.
• primary_release_yearinterogare
  An din patru cifre. Se potrivește doar cu data principală de lansare, deci poate întoarce mai puține titluri decât year.
• regioninterogare
  Cod de țară din 2 litere majuscule, precum US. Înlocuiește release_date cu data din acea țară când se cunoaște. Nu elimină titluri.
• include_adultinterogare
  Acceptat și ignorat. Titlurile pentru adulți nu sunt întoarse niciodată.
• languageinterogare
  Etichetă TMDB precum en-US sau it-IT. Sunt servite 14 limbi de bază, orice altceva revine la engleză. Implicit en-US.
• pageinterogare
  Numărul paginii de la 1 la 500. Implicit 1.

Câmpurile răspunsului

Exemplu de răspuns

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

Răspunsul conține toate cele trei potriviri. A fost preluat de la API-ul live și doar șirurile overview lungi au fost scurtate.

Alte endpoint-uri de căutare

Fiecare cale de mai jos are baza https://api.amodb.dev/3, cere query și întoarce același plic page, results, total_pages și total_results. Fiecare primește și page de la 1 la 500. include_adult este acceptat la toate și ignorat.

La TV, first_air_date_year păstrează serialele a căror primă dată de difuzare este în acel an, în timp ce year păstrează și seriale mai vechi care au difuzat în acel an. O căutare pentru the cu year=2010 întoarce The Simpsons, care a fost difuzat prima dată în 1989, iar aceeași căutare cu first_air_date_year=2010 nu îl întoarce. Dacă le trimiți pe amândouă, trebuie să se potrivească ambele. Intrările de persoane poartă până la 3 titluri known_for, fiecare cu media_type. /search/multi ignoră year.

Entitățile găsite aici continuă la seriale TV, persoane, colecții, companii și rețele și cuvinte-cheie.

Căutare multiplă

media_type este movie, tv sau person și îți spune ce câmpuri să te aștepți. Intrările de film poartă title, iar cele de TV și de persoane poartă name.

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

Erori

/search/tv și /search/person răspund la o interogare fără potrivire cu HTTP 200, un array results gol și total_results 0. În prezent /search/movie, /search/multi, /search/keyword, /search/company și /search/collection răspund în același caz cu HTTP 500 și status_code 11. Tratează un 500 pe acele căi ca „fără rezultate”, dacă nu se repetă pentru interogări despre care știi că se potrivesc.

Vezi erori pentru lista completă și limite de cereri pentru ferestre.

Note practice

• Marginea ține o căutare în cache 10 minute și partajează copia între chei. Fiecare apel se numără totuși la cele 20, 40 sau 120 de cereri pe minut, pentru că limita de cereri rulează înaintea cache-ului.
• Pentru o casetă de căutare, așteaptă 300 ms după ultima apăsare de tastă și anulează cererea în curs. O casetă care trimite la fiecare tastă poate consuma un plan de 20 de cereri pe minut în câteva secunde.
• Transformă interogarea în litere mici și taie spațiile înainte să o folosești drept cheie de cache la tine.
• Ca să cauți un titlu după ID IMDb, sari peste căutare și folosește căutare după ID extern.
• Un ID de cuvânt-cheie din /search/keyword alimentează filtrul with_keywords din descoperire, iar un ID de companie alimentează with_companies.