פסקולים

GET /3/movie/{movie_id}/soundtracks ו-GET /3/tv/{tv_id}/soundtracks מחזירים את אלבום הפסקול של כותר אחד ברשימת results. לכל אלבום יש מקור, שם, אמן, תאריך יציאה, קישור ורשימת tracks עם דיסק, מספר, שם, אמן ומשך. הוסיפו append_to_response=soundtracks כדי למזג אותו לפרטי הכותר. כך הפסקול מגיע יחד עם הפרטים בבקשה אחת.

עודכן צפייה כ-Markdown

קבלת הפסקול של סרט

GET /3/movie/{movie_id}/soundtracks מחזיר את אלבום הפסקול של סרט אחד. התגובה נושאת את ה-id של הסרט ומערך results. כל פריט הוא אלבום עם הפרטים שלו ורשימת tracks.

הדוגמה טוענת את The Dark Knight (מזהה 155) ומדפיסה את האלבום ושורה אחת לכל רצועה.

bashjspyphpgo
curl -sf "https://api.amodb.dev/3/movie/155/soundtracks" \
  -H "Authorization: Bearer $AMODB_KEY"
const res = await fetch('https://api.amodb.dev/3/movie/155/soundtracks', {
  headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` },
});
if (!res.ok) throw new Error(`amodb returned ${res.status}`);
const { results } = await res.json();
if (results.length === 0) console.log('no soundtrack album known');
for (const album of results) {
  console.log(`${album.album} by ${album.artist} (${album.track_count} tracks)`);
  for (const t of album.tracks) {
    console.log(`${t.number}. ${t.title} by ${t.artist}`);
  }
}
import os
import requests

r = requests.get(
    "https://api.amodb.dev/3/movie/155/soundtracks",
    headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
    timeout=10,
)
r.raise_for_status()
results = r.json()["results"]
if not results:
    print("no soundtrack album known")
for album in results:
    print(f"{album['album']} by {album['artist']} ({album['track_count']} tracks)")
    for t in album["tracks"]:
        print(f"{t['number']}. {t['title']} by {t['artist']}")
<?php
$ch = curl_init('https://api.amodb.dev/3/movie/155/soundtracks');
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");
}
$results = json_decode($body, true)['results'];
if (!$results) {
    echo 'no soundtrack album known', PHP_EOL;
}
foreach ($results as $album) {
    echo $album['album'], ' by ', $album['artist'] ?? 'unknown', ' (', $album['track_count'], ' tracks)', PHP_EOL;
    foreach ($album['tracks'] as $t) {
        echo $t['number'], '. ', $t['title'], ' by ', $t['artist'], PHP_EOL;
    }
}
package main

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

type Track struct {
	Disc       int    `json:"disc"`
	Number     int    `json:"number"`
	Title      string `json:"title"`
	Artist     string `json:"artist"`
	DurationMs int    `json:"duration_ms"`
}

type Album struct {
	Source     string  `json:"source"`
	Album      string  `json:"album"`
	Artist     string  `json:"artist"`
	Released   string  `json:"released"`
	URL        string  `json:"url"`
	TrackCount int     `json:"track_count"`
	Tracks     []Track `json:"tracks"`
}

func main() {
	req, _ := http.NewRequest("GET", "https://api.amodb.dev/3/movie/155/soundtracks", 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 body struct {
		Results []Album `json:"results"`
	}
	if err := json.NewDecoder(res.Body).Decode(&body); err != nil {
		panic(err)
	}
	if len(body.Results) == 0 {
		fmt.Println("no soundtrack album known")
	}
	for _, a := range body.Results {
		fmt.Printf("%s by %s (%d tracks)\n", a.Album, a.Artist, a.TrackCount)
		for _, t := range a.Tracks {
			fmt.Printf("%d. %s by %s\n", t.Number, t.Title, t.Artist)
		}
	}
}

פרמטרים

  • movie_idנתיבחובה
    מזהה סרט מספרי, למשל 155.
  • api_keyשאילתהאחד משניים
    המפתח שלכם. השתמשו בו או בכותרת Authorization: Bearer.

שדות התגובה

שדהסוגהערות
idintegerמזהה הסרט. לא קיים כשמשתמשים ב-append_to_response.
resultsarrayאלבומים. ריק כשלא ידוע אלבום. כיום יש בו לכל היותר אחד.
results[].sourcestringמאיפה האלבום מגיע: musicbrainz או deezer.
results[].albumstringכותרת האלבום.
results[].artiststring או nullאמן האלבום, למשל Hans Zimmer & James Newton Howard.
results[].releasedstring או nullתאריך יציאה בצורה YYYY-MM-DD.
results[].urlstring או nullקישור לעמוד האלבום במקור.
results[].track_countintegerמספר הרצועות באלבום.
results[].tracksarrayרצועות לפי סדר האלבום.
results[].tracks[].discintegerמספר הדיסק, מתחיל ב-1.
results[].tracks[].numberintegerמספר הרצועה בדיסק.
results[].tracks[].titlestringכותרת הרצועה.
results[].tracks[].artiststringאמן הרצועה.
results[].tracks[].duration_msintegerהאורך באלפיות שנייה.

קראו את המפתחות שאתם משתמשים בהם לפי שם ודלגו על מפתחות אחרים.

תגובה לדוגמה

JSON
{
  "id": 155,
  "results": [
    {
      "source": "musicbrainz",
      "album": "The Dark Knight",
      "artist": "Hans Zimmer & James Newton Howard",
      "released": "2008-07-15",
      "url": "https://musicbrainz.org/release/814b2f7b-c27c-451e-abac-a316d2e6cea9",
      "track_count": 14,
      "tracks": [
        { "disc": 1, "number": 1, "title": "Why So Serious?", "artist": "Hans Zimmer", "duration_ms": 554000 },
        { "disc": 1, "number": 2, "title": "I'm Not a Hero", "artist": "Hans Zimmer", "duration_ms": 395000 },
        { "disc": 1, "number": 3, "title": "Harvey Two-Face", "artist": "James Newton Howard", "duration_ms": 377000 }
      ]
    }
  ]
}

רשימת הרצועות קוצרה ל-3 מתוך 14. כותר בלי אלבום ידוע, כמו Fight Club (מזהה 550), מחזיר רשימה ריקה:

JSON
{
  "id": 550,
  "results": []
}

קבלת הפסקול של סדרה

GET /3/tv/{tv_id}/soundtracks מחזיר את אותו מבנה לסדרה. העבירו את מזהה הסדרה, למשל 1396. ל-Breaking Bad אין אלבום ידוע, ולכן מערך results שלה ריק.

שיטה ונתיבמה מוחזרפרמטרים
GET /movie/{movie_id}/soundtracksid ו-resultsmovie_id
GET /tv/{tv_id}/soundtracksid ו-resultstv_id
append_to_response=soundtracksאותו results תחת soundtracksנוסף לפרטי סרט או סדרה

כדי לקבל את האלבום בזמן טעינת עמוד סרט, צרפו אותו לפרטים:

curl
curl -sf "https://api.amodb.dev/3/movie/155?append_to_response=credits,soundtracks" \
  -H "Authorization: Bearer $AMODB_KEY"

הבלוק המצורף יושב תחת המפתח soundtracks ברשומה. הוא מחזיק results ואין לו id משלו. הוא נספר כבקשה אחת.

בניית רשימת המוזיקה בסרט

מיינו לפי disc ו-number, הציגו את הכותרת ואת האמן, והסתירו את הבלוק כש-results ריק. הפונקציות שלמטה מחזירות שורות טקסט פשוט שאפשר לשים באלמנט רשימה.

JavaScript
function clock(ms) {
  const s = Math.round(ms / 1000);
  return `${Math.floor(s / 60)}:${String(s % 60).padStart(2, '0')}`;
}

function musicLines(results) {
  const album = results[0];
  if (!album) return [];
  return [...album.tracks]
    .sort((a, b) => a.disc - b.disc || a.number - b.number)
    .map((t) => `${t.title} by ${t.artist} (${clock(t.duration_ms)})`);
}

כמה רעיונות לממשק שלא צריכים נתונים נוספים:

רעיוןאיך
רשימה ממוספרתהשתמשו ב-number כמספר הפריט ברשימה, וקבצו לפי disc כשיש כמה דיסקים.
קישור לאלבוםקשרו את שם האלבום ל-url כשהוא לא null.
אורך כוללחברו את duration_ms של כל הרצועות.
שילוב עם מצב רוחהציגו את הרשימה ליד מדדי מצב רוח של אותו כותר.

שגיאות

כל כשל מחזיר success שהוא false ו-status_code מספרי, כמו ב-TMDB.

HTTPstatus_codeמתי
4017המפתח חסר או שגוי.
40236תקופת המסלול הסתיימה.
42925מעל הבקשות שלכם לדקה. המתינו Retry-After שניות.

נקודת הקצה של הפסקולים לא עונה 404 למזהה לא מוכר. היא עונה 200 עם מערך results ריק. כשמצרפים לפרטים, מזהה לא מוכר הוא 404 מקריאת הפרטים. כל הקודים בעמוד שגיאות, והכותרות בעמוד מגבלות קצב.

הערות מעשיות

  • כמו נתוני פרטים אחרים, פסקולים נשמרים בקצה במטמון 6 שעות. מטמון קצר יותר בצד הלקוח לא מועיל.
  • השתמשו ב-append_to_response=soundtracks בעמוד פרטים שאתם כבר טוענים. זה חוסך בקשה אחת מתוך 20, 40 או 120 הבקשות שלכם לדקה.
  • אל תדרשו שאלבום יהיה קיים. הסתירו את בלוק המוזיקה כש-results ריק.
  • חלק מהאלבומים מגיעים מ-MusicBrainz ואחרים מ-Deezer. לסרט 27205 (Inception) יש אלבום ב-Deezer. המבנה זהה, ולכן בדקו את source רק אם אתם מציגים אותו.
  • שמות רצועות ואמנים הם מחרוזות רגילות ויכולים להכיל כל תו. שמרו אותם כ-UTF-8 ובצעו להם escape כשאתם מציבים אותם ב-HTML.
  • לטריילר של אותו כותר ראו סרטונים וטריילרים.