# API wyszukiwania > Endpointy wyszukiwania zamieniają zapytanie tekstowe na ID. GET /3/search/movie znajduje filmy, a pokrewne ścieżki znajdują seriale, osoby, kolekcje, firmy i słowa kluczowe albo wszystkie media naraz przez multi. JSON odpowiada TMDB v3, wyniki mają paginację po 20, a edge trzyma zapytanie w cache przez 10 minut. ## Endpoint `GET /3/search/movie` ```bash curl "https://api.amodb.dev/3/search/movie?query=inception&year=2010" \ -H "Authorization: Bearer $AMODB_KEY" ``` Odpowiedź: ```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 } ``` ## Wyszukiwanie filmów `GET /3/search/movie` przyjmuje zapytanie tekstowe i zwraca listę pasujących filmów z paginacją, najlepsze dopasowanie pierwsze. Użyj go, by zamienić to, co wpisał użytkownik, na ID filmu, a potem wywołaj [szczegóły filmu](https://amodb.dev/pl/movies/) z tym ID. Przykład szuka Inception, ograniczonego do 2010, i wypisuje ID, tytuł i datę premiery. ```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) } } ``` ### Parametry | Parametr | Gdzie | Wymagany | Opis | | ---------------------- | ----- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `query` | query | tak | Tekst do wyszukania. Zakoduj go w URL: spacje zmieniają się w `%20` lub `+`. | | `api_key` | query | jeden z dwóch | Twój klucz. Użyj go albo nagłówka `Authorization: Bearer`. | | `year` | query | nie | Czterocyfrowy rok. Zostawia filmy z dowolną datą premiery w tym roku, w dowolnym kraju. | | `primary_release_year` | query | nie | Czterocyfrowy rok. Pasuje tylko do głównej daty premiery, więc może zwrócić mniej tytułów niż `year`. | | `region` | query | nie | Dwuliterowy kod kraju wielkimi literami, na przykład `US`. Zastępuje `release_date` datą w tym kraju, gdy jest znana. Nie usuwa tytułów. | | `include_adult` | query | nie | Przyjmowany i ignorowany. Tytuły dla dorosłych nigdy nie są zwracane. | | `language` | query | nie | Tag TMDB, na przykład `en-US` lub `it-IT`. Obsługiwanych jest 14 języków bazowych, wszystko inne wraca do angielskiego. Domyślnie `en-US`. | | `page` | query | nie | Numer strony od 1 do 500. Domyślnie 1. | ### Pola odpowiedzi | Pole | Typ | Uwagi | | ------------------------------------------ | ----------------- | ------------------------------------------------------------------------------------------------- | | `page` | integer | Strona, o którą prosisz. | | `results` | array | Do 20 pozycji, najlepsze dopasowanie pierwsze. | | `total_pages`, `total_results` | integer | Rozmiar zbioru wyników dla tego zapytania. Ograniczony do 500 stron i 10000 wyników. | | `id` | integer | ID filmu dla endpointu szczegółów. | | `title`, `original_title` | string | Tytuł zlokalizowany i oryginalny. | | `original_language` | string | Dwuliterowy kod języka, w którym nakręcono film. | | `overview` | string | Tekst zlokalizowany, pusty, gdy tłumaczenie nie istnieje. | | `release_date` | string | `YYYY-MM-DD`, puste dla tytułów bez daty. | | `genre_ids` | array of integers | ID gatunków, a nie nazwy. Zamień je przez [gatunki](https://amodb.dev/pl/genres/). | | `poster_path`, `backdrop_path` | string lub null | Dołącz do `https://img.amodb.dev/t/p/{size}`. | | `popularity`, `vote_average`, `vote_count` | number | Wartości rankingu i oceny. | | `adult`, `video` | boolean | `adult` jest zawsze `false`. `video` ma wartość `true` dla pozycji oznaczonych jako treści wideo. | ### Przykładowa odpowiedź ```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 } ``` Odpowiedź zawiera wszystkie trzy dopasowania. Pobrano ją z działającego API, a skrócono tylko długie ciągi `overview`. ## Inne endpointy wyszukiwania Wszystkie poniższe ścieżki mają wspólną bazę `https://api.amodb.dev/3`, wymagają `query` i zwracają tę samą kopertę `page`, `results`, `total_pages` i `total_results`. Każda przyjmuje też `page` od 1 do 500. `include_adult` jest przyjmowane we wszystkich i ignorowane. | Metoda i ścieżka | Znajduje | Dodatkowe parametry | Pola pozycji | | ------------------------ | ---------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------- | | `GET /search/tv` | Seriale | `first_air_date_year`, `year`, `language` | `name`, `original_name`, `first_air_date`, `origin_country` | | `GET /search/person` | Osoby | `language` | `name`, `original_name`, `known_for_department`, `gender`, `profile_path`, `known_for` | | `GET /search/multi` | Filmy, seriale i osoby razem | `language` | `media_type` plus pola danego typu | | `GET /search/collection` | Kolekcje filmów | `language` | `name`, `original_name`, `overview`, `poster_path`, `backdrop_path` | | `GET /search/company` | Firmy produkcyjne | brak | `name`, `logo_path`, `origin_country` | | `GET /search/keyword` | Słowa kluczowe | brak | `id`, `name` | W przypadku seriali `first_air_date_year` zostawia seriale, których pierwsza emisja przypada na ten rok, a `year` zostawia też starsze seriale emitowane w tym roku. Wyszukanie `the` z `year=2010` zwraca The Simpsons, które po raz pierwszy emitowano w 1989, a to samo wyszukiwanie z `first_air_date_year=2010` nie. Jeśli wyślesz oba, oba muszą pasować. Pozycje osób niosą do 3 tytułów `known_for`, każdy z `media_type`. `/search/multi` ignoruje `year`. Znalezione encje mają dalszy ciąg na stronach [seriale](https://amodb.dev/pl/tv-series/), [osoby](https://amodb.dev/pl/people/), [kolekcje](https://amodb.dev/pl/collections/), [firmy i sieci telewizyjne](https://amodb.dev/pl/companies-networks/) i [słowa kluczowe](https://amodb.dev/pl/keywords/). ### Wyszukiwanie multi `media_type` to `movie`, `tv` lub `person` i mówi, jakich pól się spodziewać. Pozycje filmów niosą `title`, a pozycje seriali i osób niosą `name`. ```js const byType = { movie: [], tv: [], person: [] }; for (const r of results) byType[r.media_type]?.push(r.title || r.name); console.log(byType); ``` ## Błędy `/search/tv` i `/search/person` odpowiadają na zapytanie bez dopasowania HTTP 200, pustą tablicą `results` i `total_results` równym 0. Obecnie `/search/movie`, `/search/multi`, `/search/keyword`, `/search/company` i `/search/collection` odpowiadają na ten sam przypadek HTTP 500 i `status_code` 11. Traktuj 500 na tych ścieżkach jako „brak wyników”, chyba że powtarza się dla zapytań, o których wiesz, że pasują. | HTTP | status_code | Kiedy | | ---- | ----------- | --------------------------------------------------------------------------------------------------------------------------- | | 401 | 7 | Brakuje klucza lub jest błędny. | | 402 | 36 | Okres planu dobiegł końca. | | 405 | 37 | Wywołano metodę zapisu. | | 429 | 25 | Przekroczono limit żądań na minutę. Poczekaj tyle sekund, ile podaje `Retry-After`. | | 500 | 11 | Zapytanie o film, multi, słowo kluczowe, firmę lub kolekcję, które nic nie znajduje, albo `page` spoza zakresu od 1 do 500. | | 504 | 24 | Backend nie odpowiedział na czas. Spróbuj jeszcze raz. | Pełną listę zobacz w [błędy](https://amodb.dev/pl/errors/), a okna w [limity żądań](https://amodb.dev/pl/rate-limits/). ## Praktyczne uwagi - Edge trzyma wyszukiwanie w cache przez 10 minut i współdzieli kopię między kluczami. Każde wywołanie nadal liczy się do twoich 20, 40 lub 120 żądań na minutę, bo limit działa przed cache. - W polu wyszukiwania poczekaj 300 ms po ostatnim naciśnięciu klawisza i anuluj żądanie w toku. Pole, które wysyła zapytanie przy każdym klawiszu, może w kilka sekund zużyć plan z 20 żądaniami na minutę. - Zamień zapytanie na małe litery i przytnij je, zanim użyjesz go jako klucza cache u siebie. - Aby znaleźć tytuł po ID z IMDb, pomiń wyszukiwanie i użyj [wyszukiwania po zewnętrznym ID](https://amodb.dev/pl/find-by-external-id/). - ID słowa kluczowego z `/search/keyword` zasila filtr `with_keywords` w [discover](https://amodb.dev/pl/discover/), a ID firmy filtr `with_companies`. ## Pytania i odpowiedzi ### Ile wyników zwraca jedna strona wyszukiwania? Każda strona zawiera 20 wyników, a parametr page biegnie od 1 do 500. Odczytaj total_pages i total_results z odpowiedzi, a niejasne zapytania zawężaj przez year lub primary_release_year. ### Czy wyszukiwania z cache nadal liczą się do limitu żądań? Tak. Edge trzyma wyszukiwanie w cache przez 10 minut i współdzieli kopię między kluczami, ale sprawdzenie klucza i limitu działa przed wyszukaniem w cache, więc każde wywołanie liczy się raz. ### Czy mogę szukać po ID z IMDb tymi endpointami? Nie. Użyj zamiast tego GET /3/find/{external_id} z external_source=imdb_id. Zwraca movie_results, tv_results i person_results dla tego ID i jest opisany na stronie wyszukiwania po zewnętrznym ID. ### W jakim języku są wyniki? Parametr language ustawia tytuły i opisy, domyślnie en-US. Tagi spoza 14 języków bazowych wracają do angielskiego. Tytuły oryginalne pozostają dostępne w original_title i original_name. ## Powiązane strony - [API szczegółów filmu](https://amodb.dev/pl/movies/): API szczegółów filmu z tymi samymi ścieżkami i JSON co TMDB v3. Pobierz film po ID, dołącz obsadę, oceny i nastroje przez append_to_response, 14 języków. - [API szczegółów serialu](https://amodb.dev/pl/tv-series/): API szczegółów serialu z tymi samymi ścieżkami i JSON co TMDB v3. Serial po ID z sezonami, sieciami, klasyfikacją wiekową i dostawcami streamingu. - [API szczegółów osoby](https://amodb.dev/pl/people/): API szczegółów osoby z tymi samymi ścieżkami i JSON co TMDB v3. Aktor lub ekipa po ID z biografią, filmografią, zewnętrznymi ID i listą popularnych osób. - [Discover API](https://amodb.dev/pl/discover/): Discover API z tymi samymi filtrami co TMDB v3. Wypisuj filmy i seriale według gatunku, obsady, firmy, słowa kluczowego, roku, oceny, czasu trwania i dostawcy. - [Wyszukiwanie po zewnętrznym ID](https://amodb.dev/pl/find-by-external-id/): Znajdź film, serial lub osobę po ID z IMDb, TVDB, Wikidata lub Kinopoisk przez endpoint find z TMDB oraz odczytaj zewnętrzne ID i fakty z Wikidata o tytule. - [Limity żądań](https://amodb.dev/pl/rate-limits/): amodb limituje klucz liczbą żądań na minutę w przesuwanym oknie 60 sekund: 20, 40 lub 120 zależnie od planu. Czytaj nagłówki limitu i obsłuż 429 z Retry-After. Zaktualizowano: 2026-10-18. Source: https://amodb.dev/pl/search/