# ז'אנרים ורשימות חיפוש

> נקודות הקצה של ז'אנרים ורשימות חיפוש מחזירות רשימות עזר קטנות שטוענים פעם אחת: מזהי ז'אנרים של סרטים וסדרות עם שמות ב-14 שפות, ובנוסף מדינות, שפות, תפקידי צוות, דירוגי גיל וספקי סטרימינג. הן משתמשות בנתיבים ובמבנים של TMDB v3, לא צריכות דפדוף ומשתנות לעיתים רחוקות, ולכן שמרו אותן במטמון ליום.

## נקודת קצה

`GET /3/genre/movie/list`

```bash
curl "https://api.amodb.dev/3/genre/movie/list?language=en-US" \
  -H "Authorization: Bearer $AMODB_KEY"
```

תגובה:

```json
{
  "genres": [
    {
      "id": 28,
      "name": "Action"
    },
    {
      "id": 12,
      "name": "Adventure"
    },
    {
      "id": 16,
      "name": "Animation"
    }
  ]
}
```

## קבלת רשימת ז'אנרים של סרטים

`GET /3/genre/movie/list` מחזיר כל ז'אנר של סרטים כ-`id` וכ-`name`. המזהים הם המספרים ש-`genre_ids` נושא בפריטי רשימה ושאותם `with_genres` מצפה לקבל בעמוד [גילוי](https://amodb.dev/he/discover/). השמות עוקבים אחרי הפרמטר `language`.

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

```bash
curl -s "https://api.amodb.dev/3/genre/movie/list?language=en-US" \
  -H "Authorization: Bearer $AMODB_KEY"
```

```js
const url = 'https://api.amodb.dev/3/genre/movie/list?language=en-US';
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` } });
if (!res.ok) throw new Error(`amodb returned ${res.status}`);
const { genres } = await res.json();
const names = new Map(genres.map((g) => [g.id, g.name]));
console.log(names.get(878), names.size);
```

```python
import os
import requests

r = requests.get(
    "https://api.amodb.dev/3/genre/movie/list",
    params={"language": "en-US"},
    headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
    timeout=10,
)
r.raise_for_status()
names = {g["id"]: g["name"] for g in r.json()["genres"]}
print(names[878], len(names))
```

```php
<?php
$url = 'https://api.amodb.dev/3/genre/movie/list?language=en-US';
$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");
}
$names = [];
foreach (json_decode($body, true)['genres'] as $g) {
    $names[$g['id']] = $g['name'];
}
echo $names[878], ' ', count($names), PHP_EOL;
```

```go
package main

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

type Genres struct {
	Genres []struct {
		ID   int    `json:"id"`
		Name string `json:"name"`
	} `json:"genres"`
}

func main() {
	url := "https://api.amodb.dev/3/genre/movie/list?language=en-US"
	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 g Genres
	if err := json.NewDecoder(res.Body).Decode(&g); err != nil {
		panic(err)
	}
	names := map[int]string{}
	for _, x := range g.Genres {
		names[x.ID] = x.Name
	}
	fmt.Println(names[878], len(names))
}
```

### פרמטרים

| פרמטר      | מיקום  | חובה       | תיאור                                                                                  |
| ---------- | ------ | ---------- | -------------------------------------------------------------------------------------- |
| `api_key`  | שאילתה | אחד משניים | המפתח שלכם. השתמשו בו או בכותרת `Authorization: Bearer`.                               |
| `language` | שאילתה | לא         | תגית TMDB כמו `en-US`, `ru-RU` או `pt-BR`. השמות מוחזרים בשפה הזו. ברירת מחדל `en-US`. |

### שדות התגובה

| שדה             | סוג     | הערות                            |
| --------------- | ------- | -------------------------------- |
| `genres`        | array   | כל הרשימה בתגובה אחת, בלי דפדוף. |
| `genres[].id`   | integer | מזהה ז'אנר יציב.                 |
| `genres[].name` | string  | שם הז'אנר בשפה המבוקשת.          |

### תגובה לדוגמה

```json
{
  "genres": [
    { "id": 12, "name": "Adventure" },
    { "id": 14, "name": "Fantasy" },
    { "id": 16, "name": "Animation" },
    { "id": 18, "name": "Drama" }
  ]
}
```

התגובה מכילה 27 ז'אנרים ממוינים לפי מזהה. כאן היא קוצרה ל-4 הראשונים.

## מזהי ז'אנרים

שני נתיבי הז'אנרים מחזירים את 27 הז'אנרים האלה, ממוינים לפי מזהה. השמות שלמטה הם באנגלית. שפות אחרות מחזירות את אותם מזהים עם שמות מתורגמים.

| מזהה  | שם                 |
| ----- | ------------------ |
| 12    | Adventure          |
| 14    | Fantasy            |
| 16    | Animation          |
| 18    | Drama              |
| 27    | Horror             |
| 28    | Action             |
| 35    | Comedy             |
| 36    | History            |
| 37    | Western            |
| 53    | Thriller           |
| 80    | Crime              |
| 99    | Documentary        |
| 878   | Science Fiction    |
| 9648  | Mystery            |
| 10402 | Music              |
| 10749 | Romance            |
| 10751 | Family             |
| 10752 | War                |
| 10759 | Action & Adventure |
| 10762 | Kids               |
| 10763 | News               |
| 10764 | Reality            |
| 10765 | Sci-Fi & Fantasy   |
| 10766 | Soap               |
| 10767 | Talk               |
| 10768 | War & Politics     |
| 10770 | TV Movie           |

## רשימת ז'אנרים של סדרות

`GET /3/genre/tv/list` מקבל את אותו פרמטר `language` ומחזיר את אותה רשימה בדיוק, ולכן מפה אחת של מזהה לשם מכסה סרטים וסדרות. בנתוני רשימות, המזהים `10759` ו-`10762` עד `10768` מופיעים רק בפריטי סדרות, ומזהים כמו `28`, `12` ו-`878` מופיעים בפריטי סרטים. כשמסננים סדרות בעמוד [גילוי](https://amodb.dev/he/discover/), השתמשו במזהי הסדרות, למשל `10765` למדע בדיוני ופנטזיה.

## רשימות חיפוש

הנתיבים האלה מחזירים נתוני עזר לטפסים, למסננים ולמסכי הגדרות. כולם מקבלים את המפתח; אף אחד לא מקבל `page`.

| שיטה ונתיב                                | פרמטרים                    | כל פריט או מבנה                                               |
| ----------------------------------------- | -------------------------- | ------------------------------------------------------------- |
| `GET /configuration/countries`            | אין                        | מערך של `{ iso_3166_1, english_name, native_name }`           |
| `GET /configuration/languages`            | אין                        | מערך של `{ iso_639_1, english_name, name }`                   |
| `GET /configuration/primary_translations` | אין                        | מערך של 14 מחרוזות כמו `ru-RU`                                |
| `GET /configuration/jobs`                 | אין                        | מערך של `{ department, jobs }` כאשר `jobs` מפרט שמות תפקידים  |
| `GET /certification/movie/list`           | אין                        | `{ certifications }` לפי קוד מדינה, 10 מדינות                 |
| `GET /certification/tv/list`              | אין                        | `{ certifications }` לפי קוד מדינה, מפתח אחד לכל מדינה בקטלוג |
| `GET /watch/providers/regions`            | `language`                 | `{ results }` של `{ iso_3166_1, english_name, native_name }`  |
| `GET /watch/providers/movie`              | `language`, `watch_region` | `{ results }` של ספקים                                        |
| `GET /watch/providers/tv`                 | `language`, `watch_region` | `{ results }` של ספקים                                        |

`/configuration/countries` ו-`/configuration/languages` מתעלמים מ-`language` ותמיד מחזירים את אותם שמות. ה-`native_name` ברשימת האזורים עוקב אחרי `language`. amodb לא מציע את `/configuration/timezones`.

פריט דירוג גיל מציין את הדירוג, מה הוא אומר ואת סדר המיון שלו. הפריטים מקובצים לפי קוד מדינה, ולכן קריאה אחת מכסה כל שוק. רשימת הסרטים כוללת את טקסטי הדירוג. ברשימת הסדרות `meaning` הוא מחרוזת ריקה.

```json
{
  "certifications": {
    "US": [
      { "certification": "PG", "meaning": "Some material may not be suitable for children under 10.", "order": 3 },
      { "certification": "R", "meaning": "Under 17 requires accompanying parent or adult guardian.", "order": 5 }
    ]
  }
}
```

הדוגמה קוצרה ל-2 מתוך 6 הפריטים של ארצות הברית. רשימת הסרטים מכסה את AU, BR, CA, DE, ES, FR, GB, IT, RU ו-US.

לפריט ספק יש `provider_id`, `provider_name`, `logo_path`, `display_priority` ו-`display_priorities`, מפה מקוד מדינה לעדיפות. בלי `watch_region` מקבלים את כל הספקים. עם `watch_region=US` נשארים רק ספקים שמשרתים את המדינה הזו. אזור לא מוכר מחזיר מערך `results` ריק. העבירו קוד מ-`/watch/providers/regions`. לוגואים של ספקים נטענים ממארח התמונות, ראו [תמונות](https://amodb.dev/he/images-api/).

```json
{
  "display_priorities": { "AT": 1, "DE": 1, "GB": 1, "JP": 1, "US": 3 },
  "display_priority": 3,
  "logo_path": "/gMZdpavHmxFNnLpMHwVxfqeux2g.png",
  "provider_name": "Amazon Prime Video",
  "provider_id": 9
}
```

זה פריט אחד מ-`/watch/providers/movie?watch_region=US`.

## שגיאות

| HTTP | status_code | מתי                                                  |
| ---- | ----------- | ---------------------------------------------------- |
| 401  | 7           | המפתח חסר או שגוי.                                   |
| 402  | 36          | תקופת המסלול הסתיימה.                                |
| 404  | 34          | הנתיב לא קיים, למשל `/genre/book/list`.              |
| 405  | 37          | השתמשתם בשיטת כתיבה בנתיב חיפוש.                     |
| 429  | 25          | חרגתם מהבקשות שלכם לדקה. המתינו `Retry-After` שניות. |

פרטים על כל קוד בעמוד [שגיאות](https://amodb.dev/he/errors/). מגבלות המסלולים בעמוד [מגבלות קצב](https://amodb.dev/he/rate-limits/).

## הערות מעשיות

- טענו את הרשימות פעם אחת לכל שפה בהפעלה ושמרו אותן בזיכרון או בקובץ. הקצה שומר את נתיבי `/configuration` במטמון 24 שעות, ולכן רענון יומי בצד שלכם מספיק.
- שמרו במסד הנתונים מזהי ז'אנרים, לא שמות. שם משתנה עם השפה, מזהה לא.
- שני נתיבי הז'אנרים מחזירים את אותם 27 פריטים, ולכן מפה אחת מכסה סרטים וסדרות. המזהים 10759 ו-10762 עד 10768 מופיעים רק בפריטי סדרות.
- `with_genres=28,12` בעמוד [גילוי](https://amodb.dev/he/discover/) פירושו אקשן והרפתקאות יחד. `with_genres=28|12` פירושו אחד מהם.
- שמות ז'אנרים עוקבים אחרי הפרמטר `language`. תגית מחוץ ל-14 שפות הבסיס שבעמוד [שפות](https://amodb.dev/he/languages/) חוזרת לאנגלית, וכמה שמות נשארים באנגלית בחלק מהשפות, למשל `10759` באיטלקית.

## שאלות ותשובות

### האם מזהי ז'אנרים משתנים בין שפות?

לא. המזהה נשאר זהה ורק השם מתורגם. בקשו את הרשימה בשפה שאתם מציגים, ואז שמרו באפליקציה מפה אחת של מזהה לשם לכל שפה.

### האם סרטים וסדרות משתמשים במזהי ז'אנרים שונים?

הם חולקים מרחב מזהים אחד. שני נתיבי הז'אנרים מחזירים אותם 27 ז'אנרים. פריטי סרטים משתמשים במזהים כמו 28 ו-12, ופריטי סדרות משתמשים במזהים מאוחדים כמו 10759 לאקשן והרפתקאות. מפה אחת מכסה את שניהם.

### איך מסננים לפי שני ז'אנרים בבת אחת?

העבירו with_genres ל-discover. פסיק בין מזהים פירושו את כולם, ולכן 28,12 הוא אקשן והרפתקאות יחד. קו אנכי פירושו כל אחד מהם. השתמשו ב-without_genres להחרגה.

### האם רשימות החיפוש צריכות דפדוף?

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

## עמודים קשורים

- [API גילוי](https://amodb.dev/he/discover/): Discover API עם אותם מסננים כמו TMDB v3. הציגו סרטים וסדרות לפי ז'אנר, שחקנים, חברה, מילת מפתח, שנה, דירוג, משך וספק סטרימינג, עם מיון ודפדוף בתוצאות.
- [API פרטי סרט](https://amodb.dev/he/movies/): API פרטי סרט עם אותם נתיבים ו-JSON כמו TMDB v3. קבלו סרט לפי מזהה, הוסיפו קרדיטים, דירוגים, מצבי רוח ופסקולים עם append_to_response, ב-14 שפות.
- [API סדרות טלוויזיה](https://amodb.dev/he/tv-series/): API סדרות טלוויזיה עם אותם נתיבים ו-JSON כמו TMDB v3. קבלו סדרה לפי מזהה ב-GET /3/tv/{series_id} עם עונות, רשתות והפרק הבא, וגם סיווגי גיל וספקי צפייה.
- [שפות](https://amodb.dev/he/languages/): amodb מגיש כותרים, תקצירים ושמות ב-14 שפות. העבירו בפרמטר language תגית בסגנון TMDB כמו ru-RU או pt-BR; כל תגית אחרת חוזרת לאנגלית, בלי שגיאה.
- [API תמונות ושרת תמונות](https://amodb.dev/he/images-api/): API תמונות סרטים עם נתיבי TMDB v3: הציגו פוסטרים, תמונות רקע, לוגואים ותמונות סצנה לכל כותר, וטענו אותם מ-img.amodb.dev ב-10 גדלים בלי מפתח.
- [מדריך למתחילים](https://amodb.dev/he/quickstart/): בצעו את הקריאה הראשונה ל-amodb: קבלו מפתח, בקשו פרטי סרט ב-curl, JavaScript, Python, PHP או Go, ואז טענו את הפוסטר מ-img.amodb.dev. פחות מ-2 דקות.

עודכן: 2026-10-18. Source: https://amodb.dev/he/genres/