# API de busca > Os endpoints de busca transformam um texto em ids. GET /3/search/movie encontra filmes, e caminhos irmãos encontram séries, pessoas, coleções, produtoras e palavras-chave, ou todas as mídias de uma vez com multi. O JSON segue o TMDB v3, os resultados vêm 20 por página e o cache de borda guarda uma consulta por 10 minutos. ## Endpoint `GET /3/search/movie` ```bash curl "https://api.amodb.dev/3/search/movie?query=inception&year=2010" \ -H "Authorization: Bearer $AMODB_KEY" ``` Resposta: ```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": 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 } ``` ## Buscar filmes `GET /3/search/movie` recebe um texto de consulta e retorna uma lista paginada de filmes correspondentes, com a melhor correspondência primeiro. Use-o para transformar o que o usuário digitou em um id de filme e depois chame os [detalhes de filmes](https://amodb.dev/pt/movies/) com esse id. O exemplo procura Inception, restrito a 2010, e exibe id, título e data de lançamento. ```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) } } ``` ### Parâmetros | Parâmetro | Em | Obrigatório | Descrição | | ---------------------- | -------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `query` | consulta | sim | Texto a buscar. Codifique-o na URL: espaços viram `%20` ou `+`. | | `api_key` | consulta | um dos dois | Sua chave. Use este parâmetro ou o header `Authorization: Bearer`. | | `year` | consulta | não | Ano de quatro dígitos. Mantém filmes com qualquer data de lançamento nesse ano, em qualquer país. | | `primary_release_year` | consulta | não | Ano de quatro dígitos. Corresponde só à data de lançamento principal, então pode retornar menos títulos que `year`. | | `region` | consulta | não | Código de país de 2 letras maiúsculas, como `US`. Substitui `release_date` pela data nesse país quando ela é conhecida. Não remove títulos. | | `include_adult` | consulta | não | Aceito e ignorado. Títulos adultos nunca são retornados. | | `language` | consulta | não | Tag do TMDB como `en-US` ou `it-IT`. 14 idiomas base são atendidos, qualquer outro volta para o inglês. Padrão `en-US`. | | `page` | consulta | não | Número da página, de 1 a 500. Padrão 1. | ### Campos da resposta | Campo | Tipo | Observações | | ------------------------------------------ | ----------------- | -------------------------------------------------------------------------------------------- | | `page` | inteiro | A página que você pediu. | | `results` | array | Até 20 entradas, a melhor correspondência primeiro. | | `total_pages`, `total_results` | inteiro | Tamanho do conjunto de resultados desta consulta. Limitado a 500 páginas e 10000 resultados. | | `id` | inteiro | Id do filme para o endpoint de detalhes. | | `title`, `original_title` | string | Título localizado e título original. | | `original_language` | string | Código de duas letras do idioma em que o filme foi feito. | | `overview` | string | Texto localizado, vazio quando não existe tradução. | | `release_date` | string | `YYYY-MM-DD`, vazio para títulos sem data. | | `genre_ids` | array de inteiros | Ids de gênero, não nomes. Converta-os com [gêneros](https://amodb.dev/pt/genres/). | | `poster_path`, `backdrop_path` | string ou null | Acrescente a `https://img.amodb.dev/t/p/{size}`. | | `popularity`, `vote_average`, `vote_count` | número | Valores de ranking e de nota. | | `adult`, `video` | booleano | `adult` é sempre `false`. `video` é `true` para entradas marcadas como conteúdo de vídeo. | ### Exemplo de resposta ```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 } ``` A resposta tem as três correspondências. Foi obtida da API real e só as strings longas de `overview` foram abreviadas. ## Outros endpoints de busca Todos os caminhos abaixo compartilham a base `https://api.amodb.dev/3`, exigem `query` e retornam o mesmo envelope com `page`, `results`, `total_pages` e `total_results`. Cada um também aceita `page` de 1 a 500. `include_adult` é aceito em todos e ignorado. | Método e caminho | Encontra | Parâmetros extras | Campos da entrada | | ------------------------ | ------------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------- | | `GET /search/tv` | Séries de TV | `first_air_date_year`, `year`, `language` | `name`, `original_name`, `first_air_date`, `origin_country` | | `GET /search/person` | Pessoas | `language` | `name`, `original_name`, `known_for_department`, `gender`, `profile_path`, `known_for` | | `GET /search/multi` | Filmes, séries e pessoas juntos | `language` | `media_type` mais os campos desse tipo | | `GET /search/collection` | Coleções de filmes | `language` | `name`, `original_name`, `overview`, `poster_path`, `backdrop_path` | | `GET /search/company` | Produtoras | nenhum | `name`, `logo_path`, `origin_country` | | `GET /search/keyword` | Palavras-chave | nenhum | `id`, `name` | Para TV, `first_air_date_year` mantém as séries cuja primeira exibição foi nesse ano, enquanto `year` também mantém séries mais antigas que foram ao ar nesse ano. Uma busca por `the` com `year=2010` retorna The Simpsons, que estreou em 1989, e a mesma busca com `first_air_date_year=2010` não retorna. Se você enviar os dois, os dois precisam corresponder. As entradas de pessoas trazem até 3 títulos em `known_for`, cada um com `media_type`. `/search/multi` ignora `year`. O que você encontra aqui continua em [séries de TV](https://amodb.dev/pt/tv-series/), [pessoas](https://amodb.dev/pt/people/), [coleções](https://amodb.dev/pt/collections/), [produtoras e emissoras](https://amodb.dev/pt/companies-networks/) e [palavras-chave](https://amodb.dev/pt/keywords/). ### Busca multi `media_type` é `movie`, `tv` ou `person` e indica quais campos esperar. As entradas de filmes trazem `title`, e as de séries e de pessoas trazem `name`. ```js const byType = { movie: [], tv: [], person: [] }; for (const r of results) byType[r.media_type]?.push(r.title || r.name); console.log(byType); ``` ## Erros `/search/tv` e `/search/person` respondem a uma consulta sem correspondência com HTTP 200, um array `results` vazio e `total_results` igual a 0. No momento, `/search/movie`, `/search/multi`, `/search/keyword`, `/search/company` e `/search/collection` respondem ao mesmo caso com HTTP 500 e `status_code` 11. Trate um 500 nesses caminhos como “sem resultados”, a menos que ele se repita para consultas que você sabe que têm correspondência. | HTTP | status_code | Quando | | ---- | ----------- | ---------------------------------------------------------------------------------------------------------------------------- | | 401 | 7 | A chave está ausente ou incorreta. | | 402 | 36 | O período do plano terminou. | | 405 | 37 | Você chamou um método de escrita. | | 429 | 25 | Acima do seu limite de requisições por minuto. Espere os segundos indicados em `Retry-After`. | | 500 | 11 | Uma consulta de filme, multi, palavra-chave, produtora ou coleção sem nenhuma correspondência, ou um `page` fora de 1 a 500. | | 504 | 24 | O backend não respondeu a tempo. Tente de novo uma vez. | Veja [erros](https://amodb.dev/pt/errors/) para a lista completa e [limites de requisições](https://amodb.dev/pt/rate-limits/) para as janelas. ## Notas práticas - O cache de borda guarda uma busca por 10 minutos e compartilha a cópia entre chaves. Cada chamada ainda conta nas suas 20, 40 ou 120 requisições por minuto, porque o limite roda antes do cache. - Em uma caixa de busca, espere 300 ms depois da última tecla e cancele a requisição em andamento. Uma caixa que dispara a cada tecla pode esgotar um plano de 20 requisições por minuto em segundos. - Converta a consulta para minúsculas e remova os espaços das pontas antes de usá-la como chave de cache do seu lado. - Para buscar um título por id do IMDb, pule a busca e use [buscar por ID externo](https://amodb.dev/pt/find-by-external-id/). - Um id de palavra-chave de `/search/keyword` alimenta o filtro `with_keywords` do [discover](https://amodb.dev/pt/discover/), e um id de produtora alimenta `with_companies`. ## Perguntas e respostas ### Quantos resultados uma página de busca retorna? Cada página tem 20 resultados, e o parâmetro page vai de 1 a 500. Leia total_pages e total_results na resposta e restrinja consultas vagas com year ou primary_release_year. ### Buscas em cache ainda contam no meu limite de requisições? Sim. O cache de borda guarda uma busca por 10 minutos e compartilha essa cópia entre chaves, mas a checagem da chave e o limite de requisições rodam antes da consulta ao cache, então toda chamada conta uma vez. ### Posso buscar por id do IMDb com esses endpoints? Não. Use GET /3/find/{external_id} com external_source=imdb_id. Ele retorna movie_results, tv_results e person_results para esse id, e está descrito na página de busca por ID externo. ### Em que idioma vêm os resultados? O parâmetro language define títulos e sinopses, com padrão en-US. Tags fora dos 14 idiomas base voltam para o inglês. Os títulos originais continuam disponíveis em original_title e original_name. ## Páginas relacionadas - [API de detalhes de filmes](https://amodb.dev/pt/movies/): API de detalhes de filmes com caminhos e JSON do TMDB v3. Busque um filme por id e junte créditos, avaliações e moods com append_to_response, em 14 idiomas. - [API de séries de TV](https://amodb.dev/pt/tv-series/): API de séries de TV com os mesmos caminhos e JSON do TMDB v3. Busque uma série por id com temporadas, emissoras, próximo episódio e classificações. - [API de detalhes de pessoas](https://amodb.dev/pt/people/): API de detalhes de pessoas com os caminhos e o JSON do TMDB v3. Busque um ator ou membro da equipe por id, com biografia, filmografia e ids externos. - [API Discover](https://amodb.dev/pt/discover/): API Discover com os mesmos filtros do TMDB v3. Liste filmes e séries por gênero, elenco, produtora, palavra-chave, ano, nota, duração e provedor, com ordenação. - [Buscar por ID externo](https://amodb.dev/pt/find-by-external-id/): Busque um filme, série ou pessoa por id do IMDb, TVDB, Wikidata ou Kinopoisk com o endpoint find do TMDB e leia ids externos e dados do Wikidata de um título. - [Limites de requisições](https://amodb.dev/pt/rate-limits/): O amodb limita cada chave por requisições por minuto em uma janela de 60 segundos: 20, 40 ou 120 por plano. Leia os cabeçalhos e trate o 429 com Retry-After. Atualizado: 2026-10-18. Source: https://amodb.dev/pt/search/