# API căutare > Endpoint-urile de căutare transformă o interogare text în ID-uri. GET /3/search/movie găsește filme, iar căile surori găsesc seriale TV, persoane, colecții, companii și cuvinte-cheie, sau toate tipurile de media deodată cu multi. JSON-ul se potrivește cu TMDB v3, rezultatele sunt paginate câte 20 pe pagină, iar marginea ține o interogare în cache 10 minute. ## Endpoint `GET /3/search/movie` ```bash curl "https://api.amodb.dev/3/search/movie?query=inception&year=2010" \ -H "Authorization: Bearer $AMODB_KEY" ``` Răspuns: ```json { "page": 1, "results": [ { "adult": false, "backdrop_path": "/zSBVQIvx4UIHoFf1oDvixHyIQrz.jpg", "genre_ids": [ 28, 878, 80 ], "id": 27205, "original_language": "en", "original_title": "Inception", "overview": "Cobb, a skilled thief who commits corporate espionage by infiltrating the subconscious of his targets is offered a chance to regain his old life as payment for a task considered to be impossible: \"inception\", the implantation of another per...", "popularity": 60.9811, "poster_path": "/xlaY2zyzMfkhk0HSC5VUwzoZPU1.jpg", "release_date": "2010-07-15", "title": "Inception", "video": false, "vote_average": 8.373, "vote_count": 40461 }, { "adult": false, "backdrop_path": "/p8K8Z4yjaslJx5mTsIC5L6LJxQB.jpg", "genre_ids": [ 16, 28, 53 ], "id": 64956, "original_language": "en", "original_title": "Inception: The Cobol Job", "overview": "Cobb, Arthur and Nash are enlisted by Cobol Engineering.", "popularity": 1.9401, "poster_path": "/sNxqwtyHMNQwKWoFYDqcYTui5Ok.jpg", "release_date": "2010-12-07", "title": "Inception: The Cobol Job", "video": false, "vote_average": 7.2, "vote_count": 320 }, { "adult": false, "backdrop_path": null, "genre_ids": [ 10402 ], "id": 973484, "original_language": "en", "original_title": "Inception: Music from the Motion Picture", "overview": "The Special Features Blu-ray disc contains a lossless DTS-HD MA 5.1 surround mix of the Inception soundtrack.", "popularity": 0.4911, "poster_path": "/7uM4DyRVAcgagvhZoWrkrqMPbqV.jpg", "release_date": "2010-12-07", "title": "Inception: Music from the Motion Picture", "video": true, "vote_average": 7, "vote_count": 3 } ], "total_pages": 1, "total_results": 3 } ``` ## Caută filme `GET /3/search/movie` primește o interogare text și întoarce o listă paginată de filme potrivite, cea mai bună potrivire prima. Folosește-l ca să transformi ce a tastat un utilizator într-un ID de film, apoi apelează [detalii film](https://amodb.dev/ro/movies/) cu acel ID. Exemplul caută Inception, restrâns la 2010, și afișează ID-ul, titlul și data lansării. ```bash curl -sSf --get "https://api.amodb.dev/3/search/movie" \ --data-urlencode "query=inception" \ --data-urlencode "year=2010" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js const params = new URLSearchParams({ query: 'inception', year: '2010', language: 'en-US' }); const res = await fetch(`https://api.amodb.dev/3/search/movie?${params}`, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` }, }); if (!res.ok) throw new Error(`amodb returned ${res.status}`); const { results, total_results } = await res.json(); console.log(`${total_results} matches`); for (const m of results.slice(0, 5)) console.log(m.id, m.title, m.release_date); ``` ```python import os import requests r = requests.get( "https://api.amodb.dev/3/search/movie", params={"query": "inception", "year": 2010, "language": "en-US"}, headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"}, timeout=10, ) r.raise_for_status() data = r.json() print(data["total_results"], "matches") for m in data["results"][:5]: print(m["id"], m["title"], m["release_date"]) ``` ```php 'inception', 'year' => 2010, '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"); } $data = json_decode($body, true); foreach (array_slice($data['results'], 0, 5) as $m) { echo $m['id'], ' ', $m['title'], ' ', $m['release_date'], PHP_EOL; } ``` ```go package main import ( "encoding/json" "fmt" "net/http" "net/url" "os" "time" ) type SearchPage struct { TotalResults int `json:"total_results"` Results []struct { ID int `json:"id"` Title string `json:"title"` ReleaseDate string `json:"release_date"` } `json:"results"` } func main() { q := url.Values{"query": {"inception"}, "year": {"2010"}, "language": {"en-US"}} req, _ := http.NewRequest("GET", "https://api.amodb.dev/3/search/movie?"+q.Encode(), 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 p SearchPage if err := json.NewDecoder(res.Body).Decode(&p); err != nil { panic(err) } fmt.Println(p.TotalResults, "matches") for _, m := range p.Results { fmt.Println(m.ID, m.Title, m.ReleaseDate) } } ``` ### Parametri | Parametru | Loc | Obligatoriu | Descriere | | ---------------------- | ---------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `query` | interogare | da | Textul de căutat. Codifică-l ca URL: spațiile devin `%20` sau `+`. | | `api_key` | interogare | una dintre cele două | Cheia ta. Folosește-o pe aceasta sau antetul `Authorization: Bearer`. | | `year` | interogare | nu | An din patru cifre. Păstrează filmele cu orice dată de lansare din acel an, în orice țară. | | `primary_release_year` | interogare | nu | An din patru cifre. Se potrivește doar cu data principală de lansare, deci poate întoarce mai puține titluri decât `year`. | | `region` | interogare | nu | Cod de țară din 2 litere majuscule, precum `US`. Înlocuiește `release_date` cu data din acea țară când se cunoaște. Nu elimină titluri. | | `include_adult` | interogare | nu | Acceptat și ignorat. Titlurile pentru adulți nu sunt întoarse niciodată. | | `language` | interogare | nu | Etichetă TMDB precum `en-US` sau `it-IT`. Sunt servite 14 limbi de bază, orice altceva revine la engleză. Implicit `en-US`. | | `page` | interogare | nu | Numărul paginii de la 1 la 500. Implicit 1. | ### Câmpurile răspunsului | Câmp | Tip | Observații | | ------------------------------------------ | ----------------------- | ------------------------------------------------------------------------------------------------------------ | | `page` | număr întreg | Pagina pe care ai cerut-o. | | `results` | array | Până la 20 de intrări, cea mai bună potrivire prima. | | `total_pages`, `total_results` | număr întreg | Dimensiunea setului de rezultate pentru această interogare. Plafonat la 500 de pagini și 10000 de rezultate. | | `id` | număr întreg | ID-ul filmului pentru endpoint-ul de detalii. | | `title`, `original_title` | șir | Titlul localizat și cel original. | | `original_language` | șir | Codul din două litere al limbii în care a fost făcut filmul. | | `overview` | șir | Text localizat, gol când nu există traducere. | | `release_date` | șir | `YYYY-MM-DD`, gol pentru titlurile fără dată. | | `genre_ids` | array de numere întregi | ID-uri de gen, nu nume. Mapează-le cu [genuri](https://amodb.dev/ro/genres/). | | `poster_path`, `backdrop_path` | șir sau null | Se adaugă la `https://img.amodb.dev/t/p/{size}`. | | `popularity`, `vote_average`, `vote_count` | număr | Valori de clasament și de scor. | | `adult`, `video` | boolean | `adult` este mereu `false`. `video` este `true` pentru intrările marcate ca conținut video. | ### Exemplu de răspuns ```json { "page": 1, "results": [ { "adult": false, "backdrop_path": "/zSBVQIvx4UIHoFf1oDvixHyIQrz.jpg", "genre_ids": [28, 878, 80], "id": 27205, "original_language": "en", "original_title": "Inception", "overview": "Cobb, a skilled thief who commits corporate espionage by infiltrating the subconscious of his targets is of...", "popularity": 60.9811, "poster_path": "/xlaY2zyzMfkhk0HSC5VUwzoZPU1.jpg", "release_date": "2010-07-15", "title": "Inception", "video": false, "vote_average": 8.373, "vote_count": 40459 }, { "adult": false, "backdrop_path": "/p8K8Z4yjaslJx5mTsIC5L6LJxQB.jpg", "genre_ids": [16, 28, 53], "id": 64956, "original_language": "en", "original_title": "Inception: The Cobol Job", "overview": "Cobb, Arthur and Nash are enlisted by Cobol Engineering.", "popularity": 1.9401, "poster_path": "/sNxqwtyHMNQwKWoFYDqcYTui5Ok.jpg", "release_date": "2010-12-07", "title": "Inception: The Cobol Job", "video": false, "vote_average": 7.2, "vote_count": 320 }, { "adult": false, "backdrop_path": null, "genre_ids": [10402], "id": 973484, "original_language": "en", "original_title": "Inception: Music from the Motion Picture", "overview": "The Special Features Blu-ray disc contains a lossless DTS-HD MA 5.1 surround mix of the Inception soundtrack.", "popularity": 0.4911, "poster_path": "/7uM4DyRVAcgagvhZoWrkrqMPbqV.jpg", "release_date": "2010-12-07", "title": "Inception: Music from the Motion Picture", "video": true, "vote_average": 7, "vote_count": 3 } ], "total_pages": 1, "total_results": 3 } ``` Răspunsul conține toate cele trei potriviri. A fost preluat de la API-ul live și doar șirurile `overview` lungi au fost scurtate. ## Alte endpoint-uri de căutare Fiecare cale de mai jos are baza `https://api.amodb.dev/3`, cere `query` și întoarce același plic `page`, `results`, `total_pages` și `total_results`. Fiecare primește și `page` de la 1 la 500. `include_adult` este acceptat la toate și ignorat. | Metodă și cale | Găsește | Parametri suplimentari | Câmpurile intrării | | ------------------------ | ----------------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------- | | `GET /search/tv` | Seriale TV | `first_air_date_year`, `year`, `language` | `name`, `original_name`, `first_air_date`, `origin_country` | | `GET /search/person` | Persoane | `language` | `name`, `original_name`, `known_for_department`, `gender`, `profile_path`, `known_for` | | `GET /search/multi` | Filme, seriale și persoane împreună | `language` | `media_type` plus câmpurile acelui tip | | `GET /search/collection` | Colecții de filme | `language` | `name`, `original_name`, `overview`, `poster_path`, `backdrop_path` | | `GET /search/company` | Companii de producție | niciunul | `name`, `logo_path`, `origin_country` | | `GET /search/keyword` | Cuvinte-cheie | niciunul | `id`, `name` | La TV, `first_air_date_year` păstrează serialele a căror primă dată de difuzare este în acel an, în timp ce `year` păstrează și seriale mai vechi care au difuzat în acel an. O căutare pentru `the` cu `year=2010` întoarce The Simpsons, care a fost difuzat prima dată în 1989, iar aceeași căutare cu `first_air_date_year=2010` nu îl întoarce. Dacă le trimiți pe amândouă, trebuie să se potrivească ambele. Intrările de persoane poartă până la 3 titluri `known_for`, fiecare cu `media_type`. `/search/multi` ignoră `year`. Entitățile găsite aici continuă la [seriale TV](https://amodb.dev/ro/tv-series/), [persoane](https://amodb.dev/ro/people/), [colecții](https://amodb.dev/ro/collections/), [companii și rețele](https://amodb.dev/ro/companies-networks/) și [cuvinte-cheie](https://amodb.dev/ro/keywords/). ### Căutare multiplă `media_type` este `movie`, `tv` sau `person` și îți spune ce câmpuri să te aștepți. Intrările de film poartă `title`, iar cele de TV și de persoane poartă `name`. ```js const byType = { movie: [], tv: [], person: [] }; for (const r of results) byType[r.media_type]?.push(r.title || r.name); console.log(byType); ``` ## Erori `/search/tv` și `/search/person` răspund la o interogare fără potrivire cu HTTP 200, un array `results` gol și `total_results` 0. În prezent `/search/movie`, `/search/multi`, `/search/keyword`, `/search/company` și `/search/collection` răspund în același caz cu HTTP 500 și `status_code` 11. Tratează un 500 pe acele căi ca „fără rezultate”, dacă nu se repetă pentru interogări despre care știi că se potrivesc. | HTTP | status_code | Când | | ---- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | 401 | 7 | Cheia lipsește sau este greșită. | | 402 | 36 | Perioada planului s-a încheiat. | | 405 | 37 | Ai apelat o metodă de scriere. | | 429 | 25 | Ai depășit cererile pe minut. Așteaptă numărul de secunde din `Retry-After`. | | 500 | 11 | O interogare pentru film, multi, cuvânt-cheie, companie sau colecție care nu se potrivește cu nimic, sau un `page` în afara intervalului 1 până la 500. | | 504 | 24 | Backend-ul nu a răspuns la timp. Reîncearcă o dată. | Vezi [erori](https://amodb.dev/ro/errors/) pentru lista completă și [limite de cereri](https://amodb.dev/ro/rate-limits/) pentru ferestre. ## Note practice - Marginea ține o căutare în cache 10 minute și partajează copia între chei. Fiecare apel se numără totuși la cele 20, 40 sau 120 de cereri pe minut, pentru că limita de cereri rulează înaintea cache-ului. - Pentru o casetă de căutare, așteaptă 300 ms după ultima apăsare de tastă și anulează cererea în curs. O casetă care trimite la fiecare tastă poate consuma un plan de 20 de cereri pe minut în câteva secunde. - Transformă interogarea în litere mici și taie spațiile înainte să o folosești drept cheie de cache la tine. - Ca să cauți un titlu după ID IMDb, sari peste căutare și folosește [căutare după ID extern](https://amodb.dev/ro/find-by-external-id/). - Un ID de cuvânt-cheie din `/search/keyword` alimentează filtrul `with_keywords` din [descoperire](https://amodb.dev/ro/discover/), iar un ID de companie alimentează `with_companies`. ## Întrebări și răspunsuri ### Câte rezultate întoarce o pagină de căutare? Fiecare pagină are 20 de rezultate, iar parametrul page merge de la 1 la 500. Citește total_pages și total_results din răspuns și restrânge interogările vagi cu year sau primary_release_year. ### Se numără căutările din cache la limita mea de cereri? Da. Marginea ține o căutare în cache 10 minute și partajează acea copie între chei, dar verificarea cheii și limita de cereri rulează înaintea căutării în cache, deci fiecare apel se numără o dată. ### Pot căuta după ID IMDb cu aceste endpoint-uri? Nu. Folosește în schimb GET /3/find/{external_id} cu external_source=imdb_id. Întoarce movie_results, tv_results și person_results pentru acel ID și este descris pe pagina de căutare după ID extern. ### În ce limbă sunt rezultatele? Parametrul language stabilește titlurile și descrierile, implicit en-US. Etichetele din afara celor 14 limbi de bază revin la engleză. Titlurile originale rămân disponibile în original_title și original_name. ## Pagini conexe - [API detalii film](https://amodb.dev/ro/movies/): API detalii film cu aceleași căi și același JSON ca TMDB v3. Preia un film după ID, adaugă credite, evaluări și atmosferă cu append_to_response, în 14 limbi. - [API seriale TV](https://amodb.dev/ro/tv-series/): API seriale TV cu căile și JSON-ul TMDB v3. Preia un serial după ID cu sezoane, rețele și următorul episod, plus clasificări de conținut și furnizori. - [API detalii persoană](https://amodb.dev/ro/people/): API detalii persoană cu căile și JSON-ul TMDB v3. Preia un actor sau membru al echipei după ID, cu biografie, filmografie, ID-uri externe și lista populară. - [API discover](https://amodb.dev/ro/discover/): API discover cu filtrele TMDB v3. Listează filme și seriale după gen, distribuție, companie, cuvânt-cheie, an, evaluare, durată și furnizor, cu sortare. - [Căutare după ID extern](https://amodb.dev/ro/find-by-external-id/): Caută un film, serial sau o persoană după ID IMDb, TVDB, Wikidata sau Kinopoisk cu endpoint-ul find și citește ID-urile externe și faptele Wikidata. - [Limite de cereri](https://amodb.dev/ro/rate-limits/): amodb limitează fiecare cheie în cereri pe minut, în fereastră glisantă de 60 de secunde: 20, 40 sau 120. Citește antetele și tratează 429 cu Retry-After. Actualizat: 2026-10-18. Source: https://amodb.dev/ro/search/