חיפוש לפי מזהה חיצוני

חיפוש כותר לפי מזהה חיצוני

GET /3/find/{external_id} מקבל מזהה ממערכת אחרת ומחזיר את הרשומות התואמות. הנתיב מחזיק את המזהה, והפרמטר external_source אומר מאיזו מערכת הוא מגיע. amodb מקבל שנים עשר מקורות ושבעה מהם נפתרים לרשומות: imdb_id, tvdb_id, wikidata_id, kinopoisk_id, facebook_id, twitter_id ו-instagram_id.

הדוגמה ממפה את מזהה ה-IMDb בשם tt0137523 למזהה TMDB.

curl -sf "https://api.amodb.dev/3/find/tt0137523?external_source=imdb_id" \
  -H "Authorization: Bearer $AMODB_KEY"

const url = 'https://api.amodb.dev/3/find/tt0137523?external_source=imdb_id';
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` } });
if (!res.ok) throw new Error(`amodb returned ${res.status}`);
const found = await res.json();
const movie = found.movie_results[0];
console.log(movie ? `${movie.id} ${movie.title}` : 'no match');

import os
import requests

r = requests.get(
    "https://api.amodb.dev/3/find/tt0137523",
    params={"external_source": "imdb_id"},
    headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
    timeout=10,
)
r.raise_for_status()
results = r.json()["movie_results"]
print(f"{results[0]['id']} {results[0]['title']}" if results else "no match")

<?php
$url = 'https://api.amodb.dev/3/find/tt0137523?external_source=imdb_id';
$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");
}
$movies = json_decode($body, true)['movie_results'];
echo $movies ? $movies[0]['id'] . ' ' . $movies[0]['title'] : 'no match', PHP_EOL;

package main

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

type Found struct {
	MovieResults []struct {
		ID    int    `json:"id"`
		Title string `json:"title"`
	} `json:"movie_results"`
}

func main() {
	url := "https://api.amodb.dev/3/find/tt0137523?external_source=imdb_id"
	req, _ := http.NewRequest("GET", url, 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 f Found
	if err := json.NewDecoder(res.Body).Decode(&f); err != nil {
		panic(err)
	}
	if len(f.MovieResults) == 0 {
		fmt.Println("no match")
		return
	}
	fmt.Println(f.MovieResults[0].ID, f.MovieResults[0].Title)
}

פרמטרים

• external_idנתיבחובה
  המזהה במערכת האחרת, למשל tt0137523.
• external_sourceשאילתהחובה
  אחד מ-imdb_id, tvdb_id, wikidata_id, kinopoisk_id, facebook_id, twitter_id, instagram_id. עוד חמישה מתקבלים ולא מחזירים דבר: freebase_mid, freebase_id, tvrage_id, tiktok_id, youtube_id.
• languageשאילתה
  אחת מ-14 שפות כמו en או ru-RU. ערכים אחרים חוזרים ל-en.
• api_keyשאילתהאחד משניים
  המפתח שלכם. השתמשו בו או בכותרת Authorization: Bearer.

external_source חסר, או כזה שאינו ברשימה, עונה 400 עם status_code 22. הערך חייב להיות באותיות קטנות.

שדות התגובה

תגובה לדוגמה

{
  "movie_results": [
    {
      "adult": false,
      "backdrop_path": "/c6OLXfKAk5BKeR6broC8pYiCquX.jpg",
      "genre_ids": [18, 53],
      "id": 550,
      "original_language": "en",
      "original_title": "Fight Club",
      "overview": "A ticking-time-bomb insomniac and a slippery soap salesman channel primal male aggression into a shocking n...",
      "popularity": 39.0054,
      "poster_path": "/jSziioSwPVrOy9Yow3XhWIBDjq1.jpg",
      "release_date": "1999-10-15",
      "title": "Fight Club",
      "video": false,
      "vote_average": 8.437,
      "vote_count": 33039,
      "media_type": "movie"
    }
  ],
  "person_results": [],
  "tv_results": [],
  "tv_episode_results": [],
  "tv_season_results": []
}

התקציר קוצר.

איזה מקור מוצא מה

שם חשבון אחד יכול להתאים ליותר מכותר אחד. למשל instagram_id=breakingbad מחזיר את הסדרה ואת הסרט El Camino, ולכן קראו כל מערך.

curl -sf "https://api.amodb.dev/3/find/361?external_source=kinopoisk_id" \
  -H "Authorization: Bearer $AMODB_KEY"

מזהים חיצוניים של כותר מוכר

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

מזהה שאין לכותר חוזר כ-null. המזהה kinopoisk_id הוא מחרוזת ונוכח בסרט או בסדרה רק כש-amodb מכיר אותו. תשובה אמיתית עבור /3/movie/550/external_ids:

{
  "id": 550,
  "imdb_id": "tt0137523",
  "wikidata_id": "Q190050",
  "facebook_id": "FightClub",
  "instagram_id": null,
  "twitter_id": null,
  "kinopoisk_id": "361"
}

תשובה אמיתית עבור /3/tv/1396/external_ids:

{
  "id": 1396,
  "imdb_id": "tt0903747",
  "freebase_mid": null,
  "freebase_id": null,
  "tvdb_id": 81189,
  "tvrage_id": null,
  "wikidata_id": "Q1079",
  "facebook_id": "BreakingBad",
  "instagram_id": "breakingbad",
  "twitter_id": "BreakingBad",
  "kinopoisk_id": "404900"
}

נקודות הקצה external_ids של עונה ופרק קיימות, אבל כל המזהים בהן הם null כיום, ולכן דלגו עליהן.

עובדות Wikidata

GET /3/movie/{movie_id}/wikidata ו-GET /3/tv/{tv_id}/wikidata מחזירים את מזהה ה-Wikidata של כותר ועובדות עליו: כסף, שכנים בסדרת סרטים, עמודי ויקיפדיה, פרסים ומקומות. כל מפתח קיים תמיד. עובדה לא ידועה היא null לערך בודד ו-[] לרשימה.

זו התשובה עבור Fight Club (סרט 550), מקוצרת לגודל קריא:

{
  "id": 550,
  "wikidata_id": "Q190050",
  "budget": {
    "value": 63000000,
    "currency": "USD"
  },
  "box_office": {
    "value": 101209702,
    "currency": "USD",
    "worldwide": true
  },
  "follows": null,
  "followed_by": null,
  "sitelinks": {
    "en": "Fight Club",
    "ru": "Бойцовский клуб (фильм)",
    "uk": "Бійцівський клуб (фільм)"
  },
  "awards": [
    {
      "wikidata_id": "Q28044798",
      "label": "Empire Awards, UK for best british actress"
    },
    {
      "wikidata_id": "Q943908",
      "label": "Jupiter Award",
      "year": 2000
    }
  ],
  "nominations": [
    {
      "wikidata_id": "Q488645",
      "label": "Academy Award for Best Sound Editing",
      "year": 2000
    }
  ],
  "based_on": [
    {
      "wikidata_id": "Q837283",
      "label": "Fight Club",
      "author": {
        "wikidata_id": "Q268181",
        "label": "Chuck Palahniuk"
      }
    }
  ],
  "filming_locations": [
    {
      "wikidata_id": "Q65",
      "label": "Los Angeles"
    }
  ],
  "narrative_locations": [
    {
      "wikidata_id": "Q65",
      "label": "Los Angeles"
    }
  ],
  "original_broadcasters": []
}

באובייקט sitelinks יש 14 פריטים וב-awards יש 5. שניהם קוצרו כאן.

לקישור יש wikidata_id, label וכשהפריט הוא כותר בקטלוג גם tmdb_id ו-media_type. עבור The Matrix Reloaded (סרט 604) השכנים הם קישורים לסרטים 603 ו-605:

{
  "follows": {
    "wikidata_id": "Q83495",
    "label": "The Matrix",
    "tmdb_id": 603,
    "media_type": "movie"
  },
  "followed_by": {
    "wikidata_id": "Q207536",
    "label": "The Matrix Revolutions",
    "tmdb_id": 605,
    "media_type": "movie"
  }
}

כל label מגיע ב-language של הבקשה וחוזר לאנגלית. עם language=ru המחבר שלמעלה מופיע כ-Чак Паланик.

שגיאות

שגיאות משתמשות בגוף של TMDB, למשל {"success": false, "status_code": 7, "status_message": "Invalid API key: You must be granted a valid key."}.

מזהה חיצוני לא מוכר ב-find אינו שגיאה: צפו לחמשת המערכים ריקים. נקודות הקצה external_ids גם הן לא עונות 404 למזהה לא מוכר. הן עונות 200 עם כל מזהה null. ראו שגיאות ואימות.

הערות מעשיות

• שמרו את מזהה ה-TMDB בפעם הראשונה שאתם פותרים מזהה חיצוני. קריאות מאוחרות יותר מדלגות על find ועוברות ישר לנתיב הפרטים, וזה חוסך בקשה אחת לכל כותר.
• תמיד בדקו שהמערך שאתם רוצים מכיל פריט. find יכול להחזיר כמה מערכים בבת אחת למזהה אחד.
• פרטים ומזהים חיצוניים נשמרים בקצה במטמון 6 שעות. חיפוש חוזר בתוך הזמן הזה מחזיר את התשובה השמורה.
• wikidata_id עובד בשני הכיוונים: העבירו אותו ל-find כדי לקבל כותר, או קראו אותו מ-external_ids כדי ליצור קישור החוצה.
• להעברת חיפושי IMDb בסגנון OMDb ראו נקודת הקצה OMDb. לציונים אחרי שפתרתם כותר ראו דירוגים.