נקודת קצה תואמת OMDb

חיפוש כותר לפי מזהה IMDb או לפי כותרת

GET https://api.amodb.dev/omdb/ מחזיר כותר אחד כ-JSON שטוח עם שמות שדות של OMDb. העבירו i למזהה IMDb כמו tt0137523, או t לכותרת. האימות הוא פרמטר השאילתה apikey. בתגובה Response הוא True בהצלחה ו-False בכשל.

הדוגמה טוענת את Fight Club לפי מזהה IMDb ונעצרת עם טקסט השגיאה של OMDb כש-Response הוא False.

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 של הכותר: 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 מה-API המקורי של OMDb אינם נתמכים ומתעלמים מהם.

שדות התגובה

השדות עוקבים אחרי OMDb, ולכן מפענח OMDb קיים לא צריך שום שינוי מלבד כתובת הבסיס.

תגובה לדוגמה

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

המעבר הוא שני שינויים: כתובת הבסיס והמפתח. שום דבר אחר בבקשה לא משתנה.

// 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 ממזהה IMDb, קראו לנקודת הקצה חיפוש לפי מזהה חיצוני.
• פוסטרים הם ב-w300. לגדלים אחרים בנו את הכתובת מ-poster_path בסגנון TMDB ומרשימת הגדלים בעמוד תמונות.
• שמרו את המפתח בשרת. apikey בכתובת עמוד גלוי לכל מבקר.