# API de recherche > Les points de terminaison de recherche transforment une requête texte en ids. GET /3/search/movie trouve des films, et des chemins voisins trouvent séries, personnes, collections, sociétés et mots-clés, ou tous les médias à la fois avec multi. Le JSON suit TMDB v3, les résultats sont paginés par 20, et la périphérie met une requête en cache 10 minutes. ## Point de terminaison `GET /3/search/movie` ```bash curl "https://api.amodb.dev/3/search/movie?query=inception&year=2010" \ -H "Authorization: Bearer $AMODB_KEY" ``` Réponse: ```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 } ``` ## Rechercher des films `GET /3/search/movie` prend une requête texte et renvoie une liste paginée de films correspondants, la meilleure correspondance en premier. Utilisez-le pour transformer ce qu'un utilisateur a saisi en identifiant de film, puis appelez les [détails du film](https://amodb.dev/fr/movies/) avec cet identifiant. L'exemple cherche Inception, restreint à 2010, et affiche l'id, le titre et la date de sortie. ```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) } } ``` ### Paramètres | Paramètre | Dans | Requis | Description | | ---------------------- | ------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `query` | requête | oui | Texte à chercher. Encodez-le pour l'URL : les espaces deviennent `%20` ou `+`. | | `api_key` | requête | l'un des deux | Votre clé. Utilisez-la ou l'en-tête `Authorization: Bearer`. | | `year` | requête | non | Année à quatre chiffres. Garde les films dont une date de sortie, dans n'importe quel pays, tombe cette année-là. | | `primary_release_year` | requête | non | Année à quatre chiffres. Correspond uniquement à la date de sortie principale : il peut donc renvoyer moins de titres que `year`. | | `region` | requête | non | Code pays à 2 lettres en majuscules comme `US`. Remplace `release_date` par la date dans ce pays quand elle est connue. Ne retire aucun titre. | | `include_adult` | requête | non | Accepté et ignoré. Les titres pour adultes ne sont jamais renvoyés. | | `language` | requête | non | Balise TMDB comme `en-US` ou `it-IT`. 14 langues de base sont servies, tout le reste se replie sur l'anglais. Par défaut `en-US`. | | `page` | requête | non | Numéro de page de 1 à 500. Par défaut 1. | ### Champs de la réponse | Champ | Type | Remarques | | ------------------------------------------ | ----------------- | -------------------------------------------------------------------------------------------------- | | `page` | entier | La page demandée. | | `results` | tableau | Jusqu'à 20 entrées, la meilleure correspondance en premier. | | `total_pages`, `total_results` | entier | Taille de l'ensemble de résultats pour cette requête. Plafonnée à 500 pages et 10000 résultats. | | `id` | entier | Identifiant du film pour le point de terminaison de détails. | | `title`, `original_title` | chaîne | Titre localisé et titre original. | | `original_language` | chaîne | Code à deux lettres de la langue dans laquelle le film a été tourné. | | `overview` | chaîne | Texte localisé, vide quand il n'existe pas de traduction. | | `release_date` | chaîne | `YYYY-MM-DD`, vide pour les titres sans date. | | `genre_ids` | tableau d'entiers | Identifiants de genres, pas des noms. Associez-les avec [genres](https://amodb.dev/fr/genres/). | | `poster_path`, `backdrop_path` | chaîne ou null | À ajouter à `https://img.amodb.dev/t/p/{size}`. | | `popularity`, `vote_average`, `vote_count` | nombre | Valeurs de classement et de note. | | `adult`, `video` | booléen | `adult` vaut toujours `false`. `video` vaut `true` pour les entrées signalées comme contenu vidéo. | ### Exemple de réponse ```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 } ``` La réponse contient les trois correspondances. Elle a été récupérée depuis l'API réelle et seules les longues chaînes `overview` ont été raccourcies. ## Autres points de terminaison de recherche Tous les chemins ci-dessous partagent la base `https://api.amodb.dev/3`, demandent `query` et renvoient la même enveloppe `page`, `results`, `total_pages` et `total_results`. Chacun accepte aussi `page` de 1 à 500. `include_adult` est accepté partout et ignoré. | Méthode et chemin | Trouve | Paramètres supplémentaires | Champs des entrées | | ------------------------ | ----------------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------- | | `GET /search/tv` | Séries | `first_air_date_year`, `year`, `language` | `name`, `original_name`, `first_air_date`, `origin_country` | | `GET /search/person` | Personnes | `language` | `name`, `original_name`, `known_for_department`, `gender`, `profile_path`, `known_for` | | `GET /search/multi` | Films, séries et personnes ensemble | `language` | `media_type` plus les champs de ce type | | `GET /search/collection` | Collections de films | `language` | `name`, `original_name`, `overview`, `poster_path`, `backdrop_path` | | `GET /search/company` | Sociétés de production | aucun | `name`, `logo_path`, `origin_country` | | `GET /search/keyword` | Mots-clés | aucun | `id`, `name` | Pour les séries, `first_air_date_year` garde les séries dont la première diffusion tombe cette année-là, alors que `year` garde aussi les séries plus anciennes diffusées cette année-là. Une recherche de `the` avec `year=2010` renvoie The Simpsons, dont la première diffusion date de 1989, alors que la même recherche avec `first_air_date_year=2010` ne la renvoie pas. Si vous envoyez les deux, les deux doivent correspondre. Les entrées de personnes portent jusqu'à 3 titres `known_for`, chacun avec `media_type`. `/search/multi` ignore `year`. Les entités trouvées ici se poursuivent sur [séries TV](https://amodb.dev/fr/tv-series/), [personnes](https://amodb.dev/fr/people/), [collections](https://amodb.dev/fr/collections/), [sociétés et chaînes](https://amodb.dev/fr/companies-networks/) et [mots-clés](https://amodb.dev/fr/keywords/). ### Recherche multi `media_type` vaut `movie`, `tv` ou `person`, et il indique quels champs attendre. Les entrées de films portent `title`, et celles de séries et de personnes portent `name`. ```js const byType = { movie: [], tv: [], person: [] }; for (const r of results) byType[r.media_type]?.push(r.title || r.name); console.log(byType); ``` ## Erreurs `/search/tv` et `/search/person` répondent à une requête sans correspondance par HTTP 200, un tableau `results` vide et `total_results` à 0. Pour le moment, `/search/movie`, `/search/multi`, `/search/keyword`, `/search/company` et `/search/collection` répondent au même cas par HTTP 500 et `status_code` 11. Considérez un 500 sur ces chemins comme « aucun résultat », sauf s'il se répète pour des requêtes dont vous savez qu'elles correspondent. | HTTP | status_code | Quand | | ---- | ----------- | ------------------------------------------------------------------------------------------------------------------------ | | 401 | 7 | La clé est absente ou fausse. | | 402 | 36 | La période de l'offre est terminée. | | 405 | 37 | Vous avez appelé une méthode d'écriture. | | 429 | 25 | Au-dessus de vos requêtes par minute. Attendez les secondes de `Retry-After`. | | 500 | 11 | Une requête de films, multi, mots-clés, sociétés ou collections sans correspondance, ou une `page` en dehors de 1 à 500. | | 504 | 24 | Le backend n'a pas répondu à temps. Réessayez une fois. | Voir [erreurs](https://amodb.dev/fr/errors/) pour la liste complète et [limites de débit](https://amodb.dev/fr/rate-limits/) pour les fenêtres. ## Remarques pratiques - La périphérie met une recherche en cache 10 minutes et partage la copie entre les clés. Chaque appel compte quand même dans vos 20, 40 ou 120 requêtes par minute, car la limite de débit passe avant le cache. - Pour une zone de recherche, attendez 300 ms après la dernière frappe et annulez la requête en cours. Une zone qui déclenche une requête à chaque touche peut épuiser une offre à 20 requêtes par minute en quelques secondes. - Passez la requête en minuscules et supprimez les espaces en bordure avant de l'utiliser comme clé de cache de votre côté. - Pour chercher un titre par id IMDb, laissez la recherche de côté et utilisez la [recherche par identifiant externe](https://amodb.dev/fr/find-by-external-id/). - Un id de mot-clé issu de `/search/keyword` alimente le filtre `with_keywords` de [découverte](https://amodb.dev/fr/discover/), et un id de société alimente `with_companies`. ## Questions et réponses ### Combien de résultats renvoie une page de recherche ? Chaque page contient 20 résultats, et le paramètre page va de 1 à 500. Lisez total_pages et total_results dans la réponse, et affinez les requêtes vagues avec year ou primary_release_year. ### Les recherches en cache comptent-elles quand même dans ma limite de débit ? Oui. La périphérie met une recherche en cache 10 minutes et partage cette copie entre les clés, mais la vérification de la clé et la limite de débit passent avant la consultation du cache : chaque appel compte donc une fois. ### Puis-je chercher par id IMDb avec ces points de terminaison ? Non. Utilisez plutôt GET /3/find/{external_id} avec external_source=imdb_id. Il renvoie movie_results, tv_results et person_results pour cet id, et il est décrit sur la page de recherche par identifiant externe. ### Dans quelle langue sont les résultats ? Le paramètre language fixe les titres et les résumés, par défaut en-US. Les balises en dehors des 14 langues de base se replient sur l'anglais. Les titres originaux restent disponibles dans original_title et original_name. ## Pages liées - [API de détails de film](https://amodb.dev/fr/movies/): API de détails de film aux chemins et au JSON de TMDB v3. Obtenez un film par id, ajoutez crédits, notes et ambiances avec append_to_response, en 14 langues. - [API des séries TV](https://amodb.dev/fr/tv-series/): API de séries TV aux chemins et au JSON de TMDB v3 : une série par id avec saisons, chaînes et prochain épisode, plus classifications et plateformes. - [API de détails de personne](https://amodb.dev/fr/people/): API de détails de personne aux chemins et au JSON de TMDB v3 : biographie, filmographie, ids externes et liste populaire d'un acteur ou d'un membre de l'équipe. - [API Discover](https://amodb.dev/fr/discover/): API Discover avec les mêmes filtres que TMDB v3. Listez films et séries par genre, distribution, société, mot-clé, année, note, durée et plateforme. - [Recherche par identifiant externe](https://amodb.dev/fr/find-by-external-id/): Retrouvez un film, une série ou une personne par id IMDb, TVDB, Wikidata ou Kinopoisk avec find de TMDB, puis lisez ids externes et faits Wikidata. - [Limites de débit](https://amodb.dev/fr/rate-limits/): amodb limite chaque clé en requêtes par minute sur une fenêtre glissante de 60 secondes : 20, 40 ou 120 selon l'offre. Lisez les en-têtes et gérez le 429. Mis à jour: 2026-10-18. Source: https://amodb.dev/fr/search/