API delle traduzioni

Ottenere le traduzioni di un film

GET /3/movie/{movie_id}/translations restituisce una riga per ogni lingua che ha testo per il film. Ogni riga contiene un oggetto data con i campi tradotti. La chiamata non accetta alcun parametro di lingua, perché lo scopo è proprio vedere tutte le lingue insieme.

L'esempio trova la riga in russo e ne stampa il titolo e l'inizio della trama.

curl -s "https://api.amodb.dev/3/movie/550/translations" \
  -H "Authorization: Bearer $AMODB_KEY"

const url = 'https://api.amodb.dev/3/movie/550/translations';
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` } });
if (!res.ok) throw new Error(`amodb returned ${res.status}`);
const { translations } = await res.json();
const ru = translations.find((t) => t.iso_639_1 === 'ru');
console.log(ru ? `${ru.data.title}: ${ru.data.overview.slice(0, 80)}` : 'no Russian row');

import os
import requests

r = requests.get(
    "https://api.amodb.dev/3/movie/550/translations",
    headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
    timeout=10,
)
r.raise_for_status()
ru = next((t for t in r.json()["translations"] if t["iso_639_1"] == "ru"), None)
print(f"{ru['data']['title']}: {ru['data']['overview'][:80]}" if ru else "no Russian row")

<?php
$ch = curl_init('https://api.amodb.dev/3/movie/550/translations');
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");
}
foreach (json_decode($body, true)['translations'] as $t) {
    if ($t['iso_639_1'] === 'ru') {
        echo $t['data']['title'], ': ', mb_substr($t['data']['overview'], 0, 80), PHP_EOL;
        exit;
    }
}
echo 'no Russian row', PHP_EOL;

package main

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

type Translations struct {
	Translations []struct {
		ISO6391 string `json:"iso_639_1"`
		Data    struct {
			Title    string `json:"title"`
			Overview string `json:"overview"`
		} `json:"data"`
	} `json:"translations"`
}

func main() {
	req, _ := http.NewRequest("GET", "https://api.amodb.dev/3/movie/550/translations", 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 t Translations
	if err := json.NewDecoder(res.Body).Decode(&t); err != nil {
		panic(err)
	}
	for _, row := range t.Translations {
		if row.ISO6391 == "ru" {
			text := []rune(row.Data.Overview)
			if len(text) > 80 {
				text = text[:80]
			}
			fmt.Printf("%s: %s\n", row.Data.Title, string(text))
			return
		}
	}
	fmt.Println("no Russian row")
}

Parametri

• movie_idpercorsoobbligatorio
  ID numerico del film, per esempio 550.
• api_keyqueryuno dei due
  La tua chiave. Usa questa o l'header Authorization: Bearer.

Campi della risposta

Risposta di esempio

Sono mostrate due delle 50 righe, e le trame sono tagliate.

{
  "id": 550,
  "translations": [
    {
      "iso_3166_1": "US",
      "iso_639_1": "en",
      "name": "English",
      "english_name": "English",
      "data": {
        "title": "Fight Club",
        "overview": "A ticking-time-bomb insomniac and a slippery soap salesman channel primal male aggression into a shocking new form of therapy....",
        "homepage": "https://www.20thcenturystudios.com/movies/fight-club",
        "tagline": "Mischief. Mayhem. Soap.",
        "runtime": 0
      }
    },
    {
      "iso_3166_1": "RU",
      "iso_639_1": "ru",
      "name": "Русский",
      "english_name": "Russian",
      "data": {
        "title": "Бойцовский клуб",
        "overview": "Сотрудник страховой компании страдает хронической бессонницей и отчаянно пытается вырваться из мучительно скучной жизни. Однажд...",
        "homepage": "https://www.20thcenturystudios.com/movies/fight-club",
        "tagline": "«Интриги. Хаос. Мыло»",
        "runtime": 0
      }
    }
  ]
}

In amodb runtime vale sempre 0 in una riga di traduzione. Leggi la durata dalla scheda dei dettagli del film.

Endpoint delle traduzioni e le loro chiavi di dati

Tutti i percorsi condividono la base https://api.amodb.dev/3. Ognuno restituisce id e un array translations con la forma di riga qui sopra. Cambiano solo le chiavi dentro data.

I record delle serie elencano più o meno tante lingue quante i film. Le righe degli episodi coprono solo le lingue servite che hanno testo per quell'episodio, da 2 a 14 nei campioni controllati. Tratta una chiave mancante come un valore vuoto, e ignora le chiavi che non conosci. Vedi serie TV per i record padre.

amodb non offre traduzioni per persone o collezioni. La biografia di una persona segue il parametro language della chiamata dei dettagli della persona, e la trama di una collezione arriva come salvata.

Ripiegare quando il testo manca

Un titolo può esistere in 14 lingue e avere comunque una trama vuota in quella scelta dal tuo utente. Scorri una catena di lingue, prendi il primo valore non vuoto e ricorda da quale lingua viene.

function pickText(translations, wanted, field) {
  for (const code of [...wanted, 'en']) {
    const row = translations.find((t) => t.iso_639_1 === code);
    const value = row?.data?.[field];
    if (value) return { code, value };
  }
  return null;
}

// Prefer Ukrainian, then Russian, then English.
// const hit = pickText(translations, ['uk', 'ru'], 'overview');

Per una serie, passa 'name' come campo invece di 'title'. Segnala nella tua interfaccia il testo preso da una lingua di ripiego, così l'utente capisce perché una pagina in ucraino mostra una sinossi in inglese.

Translations o parametro language

Per i tag che language accetta, vedi lingue. Qualsiasi altro tag ripiega sull'inglese in una chiamata di dettagli.

Errori

Un ID di film o serie che non esiste non è un errore su questo percorso: risponde 200 con "translations": [], mentre il percorso dei dettagli risponde 404. Altro nelle pagine errori e limiti di richieste.

Note pratiche

• Una chiamata sostituisce fino a 14 chiamate di dettagli. Usala quando ti servono più di due lingue dello stesso titolo.
• Le righe sono ordinate per codice lingua, che non è un ordine di priorità. Scegli le righe per iso_639_1, mai per posizione nell'array.
• Le chiamate di tipo dettagli restano in cache sull'edge per 6 ore, quindi una cache client della stessa durata non costa nulla in freschezza.
• I titoli originali in altre scritture, come giapponese o coreano, sono sempre disponibili in original_title e original_name nella scheda dei dettagli.
• Per aggiungere le traduzioni a una chiamata di dettagli, passa append_to_response=translations e leggi lo stesso array dalla risposta. Funziona per film, serie ed episodi. Il blocco aggiunto non ha un id.