חלופה ל-Kinopoisk API

מה חלופה יכולה לתת ומה לא

Kinopoisk הוא אתר סרטים ברוסית, והוא לא מפרסם API פתוח כללי. מפתחים משתמשים לעיתים קרובות בשירותי צד שלישי במקום, ולכל אחד תנאים משלו, ולכן ראו במסמכים שלהם. amodb הוא API עצמאי ולא שירות של Kinopoisk. הוא עונה על שלושה צרכים שיש לעיתים קרובות בפרויקטים ברוסית: כותרים ותקצירים ברוסית, חיפוש לפי מזהה Kinopoisk, והציון של Kinopoisk לצד ציונים אחרים כשהוא ידוע.

אבני בניין

הבלוק הבא מציג תגובת פרטים אחת ברוסית עם append_to_response=ratings. זו תגובה אמיתית עבור Fight Club (מזהה 550), מצומצמת לשדות שבשימוש כאן ועם תקציר מקוצר.

{
  "id": 550,
  "original_title": "Fight Club",
  "overview": "Сотрудник страховой компании страдает хронической бессонницей и отчаянно пытается вырваться из му...",
  "release_date": "1999-10-15",
  "tagline": "«Интриги. Хаос. Мыло»",
  "title": "Бойцовский клуб",
  "ratings": {
    "imdb": {
      "value": 8.8,
      "votes": 2669989
    },
    "kinopoisk": {
      "value": 8.7,
      "votes": null
    },
    "metacritic": {
      "value": 67,
      "votes": null
    },
    "rotten_tomatoes": {
      "value": 81,
      "votes": null
    },
    "tmdb": {
      "value": 8.437,
      "votes": 33039
    }
  }
}

האובייקט ratings מציג תמיד את אותם חמישה מפתחות. כאן הציון של Kinopoisk הוא 8.7 וה-votes שלו הוא null, כך שאי אפשר להניח שיש מספר הצבעות של Kinopoisk. פרטים בעמוד דירוגים.

השוואת תכונות

במה amodb שונה

• חוזה מתועד. נתיבים, פרמטרים, גופי שגיאה ומגבלות כתובים, ומפתח אחד משרת כל נקודת קצה.
• רוסית לצד שפות אחרות. אותה קריאה עם ערך language אחר מחזירה את אותם שדות בשפה אחרת. זה עוזר כשהקהל שלכם קורא רוסית, אוקראינית ואנגלית.
• כמה ציונים באובייקט אחד. אפשר להציג את הציון של Kinopoisk לצד IMDb, Metacritic ו-Rotten Tomatoes, וכל אחד מהם null כשהוא לא ידוע.
• כותרות מקוריות נשמרות. original_title ו-original_name מחזיקים את הכותרת בשפת המקור, כולל יפנית וקוריאנית, למרות שאלה אינן שפות ממשק.

מתי Kinopoisk מתאים יותר

• הקהילה עצמה. ביקורות, רשימות, דפי משתמשים ודיונים מקומיים נמצאים באתר. amodb לא מציע אף אחד מהם, רק את הציון כשהוא ידוע.
• כל מה שמעבר למטא-נתונים. עבור תוכן שאינו שדה מטא-נתונים, השתמשו באתר עצמו. API למטא-נתונים לא נושא אותו.
• ציון הקהל שלו. הערך נוצר שם קודם. ב-amodb הוא יכול להיות null עבור כותר חדש או לא מוכר, ומספר ההצבעות יכול להיות null גם כשהציון מוגדר.

מעבר ל-amodb

אספו את מזהי Kinopoisk ששמרתם, מפו אותם פעם אחת באמצעות /3/find, ושמרו לצדם את מזהה amodb המספרי. אחר כך בקשו פרטים ברוסית וקראו את הציון מאותה תגובה.

import os
import requests

KEY = os.environ["AMODB_KEY"]
BASE = "https://api.amodb.dev/3"
HEADERS = {"Authorization": f"Bearer {KEY}"}


def get(path, **params):
    r = requests.get(BASE + path, params=params, headers=HEADERS, timeout=10)
    r.raise_for_status()
    return r.json()


found = get("/find/361", external_source="kinopoisk_id")
movie_id = found["movie_results"][0]["id"]
movie = get(f"/movie/{movie_id}", language="ru-RU", append_to_response="ratings")
kp = movie["ratings"]["kinopoisk"]
print(movie["title"], "/", movie["original_title"])
print("Kinopoisk:", kp["value"] if kp else "not known")

מערך movie_results ריק אומר שאין התאמה למזהה הזה. מזהה Kinopoisk של סדרה ממלא את tv_results במקום, ולכן קראו את שני המערכים כשאתם לא יודעים מה הסוג. טפלו ב-429 בהמתנה של Retry-After שניות. רשימת השפות נמצאת בעמוד שפות, וכללי החיפוש בעמוד חיפוש לפי מזהה חיצוני.

טיפול בפערים בטקסט הרוסי

שדה טקסט יכול להיות ריק כשאין תרגום לרוסית לכותר. בדקו אם יש מחרוזת ריקה ובקשו את אותו כותר שוב עם language=en-US. לפוסטרים עם כיתוב ברוסית קראו ל-/3/movie/550/images?include_image_language=ru,null ובחרו מתוך posters. הערך null משאיר ברשימה גם יצירות ללא טקסט. גדלים מופיעים בעמוד תמונות.

תמחור

ל-amodb אין מסלול חינמי. משלמים מראש על 1, 3, 6, 12 או 24 חודשים באחד משלושה מסלולים, ותקופה ארוכה יותר זולה ב-10, 20, 30 או 40 אחוז. המסלולים מאפשרים 20, 40 או 120 בקשות לדקה, מחזירים את אותם נתונים ואינם מתחדשים אוטומטית. הסכומים מופיעים בעמוד תמחור.