Эндпоінт, сумяшчальны з OMDb

Пошук назвы па IMDb id або назве

GET https://api.amodb.dev/omdb/ вяртае адну назву ў выглядзе плоскага JSON з назвамі палёў OMDb. Перадайце i для IMDb id, напрыклад tt0137523, або t для назвы. Аўтэнтыфікацыя адбываецца праз параметр запыту apikey. У адказе Response роўны True пры поспеху і False пры збоі.

У прыкладзе Fight Club загружаецца па IMDb id, а калі Response роўны False, выконванне спыняецца з тэкстам памылкі OMDb.

curl -sf "https://api.amodb.dev/omdb/?i=tt0137523&plot=short&apikey=$AMODB_KEY"

const params = new URLSearchParams({ i: 'tt0137523', plot: 'short', apikey: process.env.AMODB_KEY });
const res = await fetch(`https://api.amodb.dev/omdb/?${params}`);
if (!res.ok) throw new Error(`amodb returned ${res.status}`);
const data = await res.json();
if (data.Response === 'False') throw new Error(data.Error);
console.log(data.Title, data.Year, data.imdbRating);

import os
import requests

r = requests.get(
    "https://api.amodb.dev/omdb/",
    params={"i": "tt0137523", "plot": "short", "apikey": os.environ["AMODB_KEY"]},
    timeout=10,
)
r.raise_for_status()
data = r.json()
if data["Response"] == "False":
    raise SystemExit(data["Error"])
print(data["Title"], data["Year"], data["imdbRating"])

<?php
$query = http_build_query(['i' => 'tt0137523', 'plot' => 'short', 'apikey' => getenv('AMODB_KEY')]);
$ch = curl_init('https://api.amodb.dev/omdb/?' . $query);
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 10]);
$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);
if ($data['Response'] === 'False') {
    throw new RuntimeException($data['Error']);
}
echo $data['Title'], ' ', $data['Year'], ' ', $data['imdbRating'], PHP_EOL;

package main

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

type Title struct {
	Title      string `json:"Title"`
	Year       string `json:"Year"`
	ImdbRating string `json:"imdbRating"`
	Response   string `json:"Response"`
	Error      string `json:"Error"`
}

func main() {
	q := url.Values{"i": {"tt0137523"}, "plot": {"short"}, "apikey": {os.Getenv("AMODB_KEY")}}
	client := &http.Client{Timeout: 10 * time.Second}
	res, err := client.Get("https://api.amodb.dev/omdb/?" + q.Encode())
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK {
		panic(res.Status)
	}
	var t Title
	if err := json.NewDecoder(res.Body).Decode(&t); err != nil {
		panic(err)
	}
	if t.Response == "False" {
		panic(t.Error)
	}
	fmt.Println(t.Title, t.Year, t.ImdbRating)
}

Параметры

• apikeyзапытабавязковы
  Ваш ключ amodb.
• iзапытадзін з i, t, s
  IMDb id назвы: tt плюс ад 7 да 9 лічбаў, напрыклад tt0137523.
• tзапытадзін з i, t, s
  Назва для пошуку, вяртае найлепшае супадзенне.
• sзапытадзін з i, t, s
  Тэкст пошуку не менш чым з 3 літар, вяртае спіс.
• typeзапыт
  movie або series. episode нічога не знаходзіць.
• yзапыт
  Год выхаду.
• plotзапыт
  short або full. Па змаўчанні short.
• pageзапыт
  Старонка вынікаў пошуку, ад 1 да 100. Выкарыстоўваецца з s.
• rзапыт
  Толькі json. Любое іншае значэнне вяртае HTTP 400.

Параметры Season, Episode, callback і v з арыгінальнага OMDb API не падтрымліваюцца і ігнаруюцца.

Палі адказу

Палі адпавядаюць OMDb, таму існуючы парсер OMDb не патрабуе змен, акрамя базавага URL.

Прыклад адказу

{
  "Title": "Fight Club",
  "Year": "1999",
  "Rated": "R",
  "Released": "15 Oct 1999",
  "Runtime": "139 min",
  "Genre": "Crime, Drama, Thriller",
  "Director": "David Fincher",
  "Writer": "Chuck Palahniuk, Jim Uhls",
  "Actors": "Brad Pitt, Edward Norton, Meat Loaf",
  "Plot": "A nameless first-person narrator attends support groups in an attempt to subdue his emotional state and relieve his insomniac state.",
  "Language": "English",
  "Country": "United States, Germany",
  "Awards": "Nominated for 1 Oscar. 12 wins & 38 nominations total",
  "Poster": "https://img.amodb.dev/t/p/w300/qkrH7rjYKU4KOwwIl6wF6H3ISvm.jpg",
  "Ratings": [
    { "Source": "Internet Movie Database", "Value": "8.8/10" },
    { "Source": "Rotten Tomatoes", "Value": "81%" },
    { "Source": "Metacritic", "Value": "67/100" }
  ],
  "Metascore": "67",
  "imdbRating": "8.8",
  "imdbVotes": "2,669,989",
  "imdbID": "tt0137523",
  "Type": "movie",
  "DVD": "N/A",
  "BoxOffice": "$38,003,039",
  "Production": "N/A",
  "Website": "N/A",
  "Response": "True"
}

Для серыяла, напрыклад The Wire (i=tt0306414), адказ заканчваецца на "Type": "series", "totalSeasons": "5" і "Response": "True".

Пошук праз s

Адпраўце s, каб атрымаць спіс замест адной назвы. На старонцы 10 элементаў, а totalResults дае поўную колькасць у выглядзе радка. Запытайце page=2 для элементаў з 11 па 20 і працягвайце, пакуль не прачытаеце totalResults элементаў. Старонка пасля апошняй адказвае Movie not found!.

curl -sf "https://api.amodb.dev/omdb/?s=Matrix&type=movie&page=1&apikey=$AMODB_KEY"

{
  "Search": [
    {
      "Title": "The Matrix",
      "Year": "1999",
      "imdbID": "tt0133093",
      "Type": "movie",
      "Poster": "https://img.amodb.dev/t/p/w300/kEDbym5htJgDQNenjUtSJxAHysB.jpg"
    },
    {
      "Title": "The Matrix Reloaded",
      "Year": "2003",
      "imdbID": "tt0234215",
      "Type": "movie",
      "Poster": "https://img.amodb.dev/t/p/w300/d0xVNNxIYxId2qHkqpgE39soOvD.jpg"
    }
  ],
  "totalResults": "20",
  "Response": "True"
}

Спіс скарочаны да 2 з 10 элементаў.

Як чытаць масіў Ratings

Ratings змяшчае па адным аб’екце на крыніцу, у кожным ёсць Source і Value, а Value ёсць тэкстам, напрыклад 8.8/10. Крыніцы: Internet Movie Database, Rotten Tomatoes і Metacritic, і пералічаны толькі тыя, што вядомыя для назвы. Плоскія палі imdbRating, imdbVotes і Metascore паўтараюць частку тых жа даных. Калі патрэбны лік, раздзяліце Value па рыссе дробу. Для тыпізаваных лікаў і рэйтынгаў Kinopoisk і TMDB выкарыстоўвайце замест гэтага эндпоінт рэйтынгі.

Памылкі

Збоі пошуку вяртаюць {"Response":"False","Error":"..."}. Большасць з іх прыходзіць з HTTP 200, таму чытайце Error і вызначайце далейшыя дзеянні па тэксце, а не толькі па HTTP-статусе.

Скончаны план адказвае HTTP 402. Гл. памылкі і ліміты запытаў.

Міграцыя кліента OMDb

Міграцыя складаецца з дзвюх змен: базавы URL і ключ. Больш у запыце нічога не змяняецца.

// Before: the base URL and key of your current OMDb setup.
// After:
const OMDB_BASE = 'https://api.amodb.dev/omdb/';
const OMDB_KEY = process.env.AMODB_KEY;

Прыберыце r=xml, калі яго адпраўляеце. Кліенту, які чытае эпізоды, Season або callback, патрэбна іншая крыніца для гэтых частак. Ліміт запытаў дзейнічае на ключ, таму выклікі ў стылі OMDb і выклікі ў стылі TMDB падзяляюць адзін бюджэт з 20, 40 або 120 запытаў у хвіліну.

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

• Лічыце кожнае значэнне тэкстам. Пераўтварайце Year, imdbRating і totalResults самастойна, а N/A лічыце адсутнасцю даных.
• Выкарыстоўвайце plot=full, толькі калі паказваеце доўгае апісанне сюжэта. short робіць адказы меншымі.
• Пошукі па i або t кэшуюцца даўжэй, чым пошукі праз s, таму паўторны запыт вяртае захаваны адказ.
• Каб атрымаць TMDB id па IMDb id, выклічце пошук па вонкавым ідэнтыфікатары.
• Постэры маюць памер w300. Для іншых памераў будуйце адрас па poster_path у стылі TMDB і спісе памераў са старонкі выявы.
• Трымайце ключ на серверы. apikey у URL старонкі бачыць кожны наведвальнік.