API перакладаў
Эндпоінты перакладаў вяртаюць усе моўныя версіі запісу ў адным адказе: title або name, overview, tagline і homepage для фільмаў і серыялаў, name і overview для эпізодаў. Кожны радок нясе iso_639_1, iso_3166_1 і english_name. Выкарыстоўвайце яго, каб чытаць мовы, якіх не аддае параметр language, або каб будаваць ланцужок запасных моў.
Атрыманне перакладаў фільма
GET / вяртае адзін радок на кожную мову, у якой ёсць тэкст для фільма. Кожны радок змяшчае аб’ект data з перакладзенымі палямі. Выклік не прымае параметр мовы, бо сэнс якраз у тым, каб убачыць усе мовы адразу.
У прыкладзе знаходзіцца руская радок і друкуюцца яго назва і пачатак апісання.
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")
}Параметры
movie_idшляхабавязковыЛікавы id фільма, напрыклад550.api_keyзапытадзін з двухВаш ключ. Выкарыстоўвайце яго або загаловакAuthorization: Bearer.
Палі адказу
| Поле | Тып | Заўвагі |
|---|---|---|
id | цэлы лік | Id фільма. |
translations | масіў | Адзін радок на кожную мову з тэкстам, адсартаваныя па коду мовы. Для фільма 550 вяртаецца 50 радкоў. |
translations[].iso_ | радок | Код краіны, што ідзе з мовай, напрыклад US для en або BR для pt. Для моў па-за 14 падтрымліванымі паўтарае код мовы вялікімі літарамі. |
translations[].iso_ | радок | Код мовы, напрыклад ru або pt. Унікальны ў масіве. |
translations[].name | радок | Назва мовы, напісаная на гэтай мове. |
translations[].english_ | радок | Назва мовы па-англійску. |
translations[].data | аб’ект | Перакладзеныя палі. Ключы залежаць ад рэсурсу, гл. табліцу ніжэй. |
Прыклад адказу
Паказаны два з 50 радкоў, апісанні скарочаны.
{
"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
}
}
]
}У amodb runtime у радку перакладу заўсёды роўны 0. Працягласць чытайце з запісу дэталяў фільма.
Эндпоінты перакладаў і іх ключы data
Усе шляхі маюць агульную аснову https:/. Кожны вяртае id і масіў translations з формай радка вышэй. Змяняюцца толькі ключы ўнутры data.
| Метад і шлях | Ключы data |
|---|---|
GET / | title, overview, homepage, tagline, runtime (заўсёды 0) |
GET / | name, overview, homepage, tagline |
GET / | няма, масіў заўсёды пусты |
GET / | name, overview |
Запісы серыялаў пералічваюць прыкладна столькі ж моў, што і фільмы. Радкі эпізодаў ахопліваюць толькі падтрымліваныя мовы, у якіх ёсць тэкст для гэтага эпізода, ад 2 да 14 у праверанай выбарцы. Лічыце адсутны ключ пустым значэннем і ігнаруйце ключы, якіх не ведаеце. Бацькоўскія запісы гл. на старонцы серыялы.
amodb не прапануе пераклады для персон і калекцый. Біяграфія персоны залежыць ад параметра language у выкліку дэталяў персоны, а апісанне калекцыі прыходзіць у тым выглядзе, як захавана.
Запасны варыянт, калі тэксту няма
Назва можа быць на 14 мовах і ўсё роўна мець пустое апісанне на той, што абраў карыстальнік. Прайдзіце па ланцужку моў, вазьміце першае непустое значэнне і запомніце, з якой мовы яно ўзята.
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');Для серыяла перадайце 'name' як поле замест 'title'. Пазначайце ў інтэрфейсе тэкст з запасной мовы, каб карыстальнік разумеў, чаму ўкраінская старонка паказвае англійскі сюжэт.
Translations ці параметр language
| Патрэба | Што выкарыстаць |
|---|---|
| Паказаць адну мову аднаму карыстальніку | language у выкліку дэталяў |
| Пералічыць усе мовы назвы ў рэдактары | Гэты эндпоінт |
Прачытаць мову, якой language не аддае, напрыклад ja | Гэты эндпоінт, абярыце радок па iso_639_1 |
| Праверыць, у якіх з 14 падтрымліваных моў ёсць тэкст | Гэты эндпоінт, параўнайце iso_639_1 |
| Пабудаваць спасылкі на старонкі на іншых мовах | Гэты эндпоінт, чытайце наяўныя коды |
Тэгі, якія прымае language, гл. на старонцы мовы. Любы іншы тэг у выкліку дэталяў замяняецца англійскай.
Памылкі
| HTTP | status_code | Калі |
|---|---|---|
| 401 | 7 | Ключ адсутнічае або няправільны. |
| 402 | 36 | Тэрмін дзеяння плана скончыўся. |
| 404 | 34 | Няма сезона або эпізода з гэтым id, або id не з’яўляецца лікам. |
| 405 | 37 | Вы выкарысталі метад запісу на шляху перакладаў. |
| 429 | 25 | Вы перавысілі ліміт запытаў у хвіліну. Пачакайце Retry-After секунд. |
Id фільма або серыяла, якога не існуе, на гэтым шляху не памылка: ён адказвае 200 з "translations": [], а шлях дэталяў адказвае 404. Больш на старонках памылкі і ліміты запытаў.
Практычныя заўвагі
- Адзін выклік замяняе да 14 выклікаў дэталяў. Выкарыстоўвайце яго, калі патрэбна больш за дзве мовы адной назвы.
- Радкі адсартаваныя па коду мовы, а гэта не парадак прыярытэту. Абірайце радкі па
iso_639_1, ніколі па месцы ў масіве. - Выклікі тыпу дэталяў кэшуюцца на edge на 6 гадзін, таму кліенцкі кэш такой жа даўжыні нічога не каштуе ў свежасці.
- Арыгінальныя назвы на іншых пісьмах, такіх як японскае або карэйскае, заўсёды даступныя ў
original_titleіoriginal_nameзапісу дэталяў. - Каб дадаць пераклады да выкліку дэталяў, перадайце
append_і чытайце той жа масіў з адказу. Гэта працуе для фільмаў, серыялаў і эпізодаў. Далучаны блок не маеto_ response= translations id.