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запыт
  Двухлітарны код краіны вялікімі літарамі, напрыклад 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.

Знойдзеныя тут сутнасці апісаны далей на старонках серыялы, персоны, калекцыі, кампаніі і тэлеканалы і ключавыя словы.

Сумесны пошук multi

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 на гэтых шляхах адсутнасцю вынікаў, калі толькі ён не паўтараецца для запытаў, пра якія вы ведаеце, што яны павінны даваць вынікі.

Поўны спіс гл. на старонцы памылкі, а акны лімітаў на старонцы ліміты запытаў.

Практычныя заўвагі

• Edge кэшуе пошук на 10 хвілін і падзяляе копію паміж ключамі. Кожны выклік усё роўна ўлічваецца ў вашых 20, 40 або 120 запытах у хвіліну, бо ліміт запытаў правяраецца да кэшу.
• Для поля пошуку пачакайце 300 мс пасля апошняга націску клавішы і скасуйце запыт, які ўжо ляціць. Поле, якое адпраўляе запыт на кожны сімвал, можа за секунды вычарпаць план на 20 запытаў у хвіліну.
• Прывядзіце запыт да малых літар і абрэжце прабелы, перш чым выкарыстоўваць яго як ключ кэшу на вашым баку.
• Каб знайсці назву па IMDb id, прапусціце пошук і выкарыстоўвайце пошук па вонкавым ідэнтыфікатары.
• Id ключавога слова з /search/keyword падаецца ў фільтр with_keywords на старонцы пошук па фільтрах, а id кампаніі ў with_companies.