API пошуку

Пошук фільмів

GET /3/search/movie приймає текстовий запит і повертає посторінковий список відповідних фільмів, найкращий збіг першим. Використовуйте його, щоб перетворити введене користувачем на id фільму, а потім викличіть деталі фільму з цим id.

Приклад шукає Inception із обмеженням 2010 роком і виводить id, назву та дату виходу.

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

Параметри

• queryрядок запитуобов'язковий
  Текст для пошуку. Закодуйте його для URL: пробіли стають %20 або +.
• api_keyрядок запитуодин із двох
  Ваш ключ. Використовуйте його або заголовок Authorization: Bearer.
• yearрядок запиту
  Чотирицифровий рік. Залишає фільми з будь-якою датою виходу в цьому році, в будь-якій країні.
• primary_release_yearрядок запиту
  Чотирицифровий рік. Збігається лише з основною датою виходу, тому може повернути менше фільмів, ніж year.
• regionрядок запиту
  Код країни з 2 літер великими літерами, наприклад US. Замінює release_date датою в цій країні, якщо вона відома. Фільми не прибирає.
• include_adultрядок запиту
  Приймається й ігнорується. Фільми для дорослих ніколи не повертаються.
• languageрядок запиту
  Тег TMDB, наприклад en-US або it-IT. Обслуговується 14 базових мов, усе інше переходить на англійську. За замовчуванням en-US.
• pageрядок запиту
  Номер сторінки від 1 до 500. За замовчуванням 1.

Поля відповіді

Приклад відповіді

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

Відповідь містить усі три збіги. Її отримано з живого API, скорочено лише довгі рядки overview.

Інші ендпоінти пошуку

Кожен шлях нижче має спільну базу https://api.amodb.dev/3, потребує query і повертає той самий конверт із page, results, total_pages і total_results. Кожен також приймає page від 1 до 500. include_adult приймається на всіх і ігнорується.

Для серіалів first_air_date_year залишає серіали, перший ефір яких припав на цей рік, а year залишає також старіші серіали, що виходили в ефір цього року. Пошук the з year=2010 повертає The Simpsons, який уперше вийшов в ефір у 1989 році, а той самий пошук із first_air_date_year=2010 його не повертає. Якщо надіслати обидва, мають збігатися обидва. Записи персон містять до 3 назв known_for, кожна з media_type. /search/multi ігнорує year.

Знайдені тут сутності продовжуються на сторінках: серіали, персони, колекції, компанії та телемережі і ключові слова.

Мультипошук

media_type має значення movie, tv або person і вказує, які поля очікувати. Записи фільмів містять title, а записи серіалів і персон містять name.

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

Помилки

/search/tv і /search/person відповідають на запит без збігів HTTP 200, порожнім масивом results і total_results рівним 0. Наразі /search/movie, /search/multi, /search/keyword, /search/company і /search/collection відповідають на той самий випадок HTTP 500 і status_code 11. Вважайте 500 на цих шляхах за «немає результатів», якщо він не повторюється для запитів, про які ви знаєте, що вони мають збіги.

Усі коди дивіться на сторінці помилки, а вікна на сторінці ліміти запитів.

Практичні поради

• Кеш на периферії зберігає пошук 10 хвилин і ділить копію між ключами. Кожен виклик усе одно враховується у ваших 20, 40 або 120 запитах на хвилину, бо ліміт запитів виконується до кешу.
• Для поля пошуку зачекайте 300 мс після останнього натискання клавіші й скасуйте запит, що вже виконується. Поле, яке надсилає запит на кожну клавішу, може вичерпати тариф на 20 запитів на хвилину за лічені секунди.
• Переведіть запит у нижній регістр і обріжте пробіли, перш ніж використовувати його як ключ кешу на своєму боці.
• Щоб знайти фільм за IMDb id, пропустіть пошук і використайте пошук за зовнішнім ID.
• Id ключового слова з /search/keyword підходить до фільтра with_keywords у discover, а id компанії до with_companies.