# Recherche par identifiant externe

> GET /3/find/{external_id} transforme un id IMDb, TVDB, Wikidata, Kinopoisk, Facebook, Twitter ou Instagram en résultats de style TMDB, et les points de terminaison external_ids font le chemin inverse. Un point de terminaison Wikidata ajoute budget, recettes, récompenses et titres liés pour un film ou une série. Tout utilise votre clé habituelle.

## Point de terminaison

`GET /3/find/{external_id}`

```bash
curl "https://api.amodb.dev/3/find/tt0137523?external_source=imdb_id" \
  -H "Authorization: Bearer $AMODB_KEY"
```

Réponse:

```json
{
  "movie_results": [
    {
      "adult": false,
      "backdrop_path": "/c6OLXfKAk5BKeR6broC8pYiCquX.jpg",
      "genre_ids": [
        18,
        53
      ],
      "id": 550,
      "original_language": "en",
      "original_title": "Fight Club",
      "overview": "A ticking-time-bomb insomniac and a slippery soap salesman channel primal male aggression into a shocking new form of therapy. Their concept catches on, with underground \"fight clubs\" forming in every town, until an eccentric gets in the wa...",
      "popularity": 39.0054,
      "poster_path": "/jSziioSwPVrOy9Yow3XhWIBDjq1.jpg",
      "release_date": "1999-10-15",
      "title": "Fight Club",
      "video": false,
      "vote_average": 8.437,
      "vote_count": 33042,
      "media_type": "movie"
    }
  ],
  "person_results": [],
  "tv_results": [],
  "tv_episode_results": [],
  "tv_season_results": []
}
```

## Trouver un titre par identifiant externe

`GET /3/find/{external_id}` prend un identifiant d'un autre système et renvoie les fiches correspondantes. Le chemin contient l'identifiant, et le paramètre de requête `external_source` indique de quel système il vient. amodb accepte douze sources, dont sept donnent des fiches : `imdb_id`, `tvdb_id`, `wikidata_id`, `kinopoisk_id`, `facebook_id`, `twitter_id` et `instagram_id`.

L'exemple associe l'identifiant IMDb `tt0137523` à un identifiant TMDB.

```bash
curl -sf "https://api.amodb.dev/3/find/tt0137523?external_source=imdb_id" \
  -H "Authorization: Bearer $AMODB_KEY"
```

```js
const url = 'https://api.amodb.dev/3/find/tt0137523?external_source=imdb_id';
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` } });
if (!res.ok) throw new Error(`amodb returned ${res.status}`);
const found = await res.json();
const movie = found.movie_results[0];
console.log(movie ? `${movie.id} ${movie.title}` : 'no match');
```

```python
import os
import requests

r = requests.get(
    "https://api.amodb.dev/3/find/tt0137523",
    params={"external_source": "imdb_id"},
    headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
    timeout=10,
)
r.raise_for_status()
results = r.json()["movie_results"]
print(f"{results[0]['id']} {results[0]['title']}" if results else "no match")
```

```php
<?php
$url = 'https://api.amodb.dev/3/find/tt0137523?external_source=imdb_id';
$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");
}
$movies = json_decode($body, true)['movie_results'];
echo $movies ? $movies[0]['id'] . ' ' . $movies[0]['title'] : 'no match', PHP_EOL;
```

```go
package main

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

type Found struct {
	MovieResults []struct {
		ID    int    `json:"id"`
		Title string `json:"title"`
	} `json:"movie_results"`
}

func main() {
	url := "https://api.amodb.dev/3/find/tt0137523?external_source=imdb_id"
	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 f Found
	if err := json.NewDecoder(res.Body).Decode(&f); err != nil {
		panic(err)
	}
	if len(f.MovieResults) == 0 {
		fmt.Println("no match")
		return
	}
	fmt.Println(f.MovieResults[0].ID, f.MovieResults[0].Title)
}
```

### Paramètres

| Paramètre         | Dans    | Requis        | Description                                                                                                                                                                                                                                  |
| ----------------- | ------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `external_id`     | chemin  | oui           | L'identifiant dans l'autre système, par exemple `tt0137523`.                                                                                                                                                                                 |
| `external_source` | requête | oui           | L'une des valeurs `imdb_id`, `tvdb_id`, `wikidata_id`, `kinopoisk_id`, `facebook_id`, `twitter_id`, `instagram_id`. Cinq autres sont acceptées et ne renvoient rien : `freebase_mid`, `freebase_id`, `tvrage_id`, `tiktok_id`, `youtube_id`. |
| `language`        | requête | non           | L'une des 14 langues comme `en` ou `ru-RU`. Les autres valeurs se replient sur `en`.                                                                                                                                                         |
| `api_key`         | requête | l'un des deux | Votre clé. Utilisez-la ou l'en-tête `Authorization: Bearer`.                                                                                                                                                                                 |

Un `external_source` absent, ou qui ne figure pas dans la liste, répond 400 avec `status_code` 22. La valeur doit être en minuscules.

### Champs de la réponse

| Champ                | Type    | Remarques                                                                                                             |
| -------------------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
| `movie_results`      | tableau | Fiches de films avec les mêmes champs qu'un résultat de recherche, plus `media_type` réglé sur `movie`.               |
| `person_results`     | tableau | Personnes correspondant à l'identifiant. Chacune a `known_for` comme tableau vide et `media_type` réglé sur `person`. |
| `tv_results`         | tableau | Fiches de séries avec `media_type` réglé sur `tv`.                                                                    |
| `tv_episode_results` | tableau | Toujours vide.                                                                                                        |
| `tv_season_results`  | tableau | Toujours vide.                                                                                                        |

### Exemple de réponse

```json
{
  "movie_results": [
    {
      "adult": false,
      "backdrop_path": "/c6OLXfKAk5BKeR6broC8pYiCquX.jpg",
      "genre_ids": [18, 53],
      "id": 550,
      "original_language": "en",
      "original_title": "Fight Club",
      "overview": "A ticking-time-bomb insomniac and a slippery soap salesman channel primal male aggression into a shocking n...",
      "popularity": 39.0054,
      "poster_path": "/jSziioSwPVrOy9Yow3XhWIBDjq1.jpg",
      "release_date": "1999-10-15",
      "title": "Fight Club",
      "video": false,
      "vote_average": 8.437,
      "vote_count": 33039,
      "media_type": "movie"
    }
  ],
  "person_results": [],
  "tv_results": [],
  "tv_episode_results": [],
  "tv_season_results": []
}
```

Le résumé est coupé.

### Quelle source trouve quoi

| `external_source`                           | Forme de l'identifiant                                                            | Exemple                                                              | Tableau de résultats habituel                     |
| ------------------------------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------- |
| `imdb_id`                                   | `tt` plus des chiffres pour les titres, `nm` plus des chiffres pour les personnes | `tt0137523`, `nm0000093` (Brad Pitt)                                 | `movie_results`, `tv_results` ou `person_results` |
| `tvdb_id`                                   | Nombre                                                                            | `81189` (Breaking Bad)                                               | `tv_results`                                      |
| `wikidata_id`                               | `Q` plus des chiffres                                                             | `Q190050` (Fight Club), `Q1079` (Breaking Bad), `Q35332` (Brad Pitt) | `movie_results`, `tv_results` ou `person_results` |
| `kinopoisk_id`                              | Nombre                                                                            | `361` (Fight Club), `404900` (Breaking Bad)                          | `movie_results` ou `tv_results`                   |
| `facebook_id`, `twitter_id`, `instagram_id` | Nom de compte                                                                     | `FightClub`                                                          | Selon le compte                                   |

Un même nom de compte peut correspondre à plusieurs titres. Par exemple, `instagram_id=breakingbad` renvoie la série et le film El Camino : lisez donc tous les tableaux.

```bash
curl -sf "https://api.amodb.dev/3/find/361?external_source=kinopoisk_id" \
  -H "Authorization: Bearer $AMODB_KEY"
```

## Identifiants externes d'un titre connu

Le sens inverse est un ensemble de points de terminaison `external_ids`. Ils renvoient les identifiants qu'utilisent d'autres systèmes pour une fiche que vous avez déjà.

| Méthode et chemin                      | Renvoie                                                                                          | Paramètres  |
| -------------------------------------- | ------------------------------------------------------------------------------------------------ | ----------- |
| `GET /movie/{movie_id}/external_ids`   | `imdb_id`, `wikidata_id`, `facebook_id`, `instagram_id`, `twitter_id`, `kinopoisk_id`            | `movie_id`  |
| `GET /tv/{tv_id}/external_ids`         | Les mêmes plus `freebase_mid`, `freebase_id`, `tvdb_id`, `tvrage_id`                             | `tv_id`     |
| `GET /person/{person_id}/external_ids` | `imdb_id`, `wikidata_id`, `facebook_id`, `instagram_id`, `tiktok_id`, `twitter_id`, `youtube_id` | `person_id` |

Un identifiant qu'un titre n'a pas revient à `null`. `kinopoisk_id` est une chaîne et n'est présent pour un film ou une série que si amodb le connaît. Une vraie réponse pour `/3/movie/550/external_ids` :

```json
{
  "id": 550,
  "imdb_id": "tt0137523",
  "wikidata_id": "Q190050",
  "facebook_id": "FightClub",
  "instagram_id": null,
  "twitter_id": null,
  "kinopoisk_id": "361"
}
```

Une vraie réponse pour `/3/tv/1396/external_ids` :

```json
{
  "id": 1396,
  "imdb_id": "tt0903747",
  "freebase_mid": null,
  "freebase_id": null,
  "tvdb_id": 81189,
  "tvrage_id": null,
  "wikidata_id": "Q1079",
  "facebook_id": "BreakingBad",
  "instagram_id": "breakingbad",
  "twitter_id": "BreakingBad",
  "kinopoisk_id": "404900"
}
```

Les points de terminaison `external_ids` des saisons et des épisodes existent, mais tous leurs identifiants valent `null` aujourd'hui : laissez-les de côté.

## Faits Wikidata

`GET /3/movie/{movie_id}/wikidata` et `GET /3/tv/{tv_id}/wikidata` renvoient l'identifiant Wikidata d'un titre et des faits à son sujet : argent, voisins dans une série, pages Wikipédia, récompenses et lieux. Chaque clé est toujours présente. Un fait inconnu vaut `null` pour une valeur unique et `[]` pour une liste.

| Méthode et chemin                | Renvoie                                     | Paramètres                   |
| -------------------------------- | ------------------------------------------- | ---------------------------- |
| `GET /movie/{movie_id}/wikidata` | Identifiant Wikidata et faits               | `movie_id`, `language`       |
| `GET /tv/{tv_id}/wikidata`       | Identifiant Wikidata et faits               | `tv_id`, `language`          |
| `append_to_response=wikidata`    | Le même bloc sous `wikidata`, avec son `id` | Ajouté à un appel de détails |

Voici la réponse pour Fight Club (film 550), réduite à une taille lisible :

```json
{
  "id": 550,
  "wikidata_id": "Q190050",
  "budget": {
    "value": 63000000,
    "currency": "USD"
  },
  "box_office": {
    "value": 101209702,
    "currency": "USD",
    "worldwide": true
  },
  "follows": null,
  "followed_by": null,
  "sitelinks": {
    "en": "Fight Club",
    "ru": "Бойцовский клуб (фильм)",
    "uk": "Бійцівський клуб (фільм)"
  },
  "awards": [
    {
      "wikidata_id": "Q28044798",
      "label": "Empire Awards, UK for best british actress"
    },
    {
      "wikidata_id": "Q943908",
      "label": "Jupiter Award",
      "year": 2000
    }
  ],
  "nominations": [
    {
      "wikidata_id": "Q488645",
      "label": "Academy Award for Best Sound Editing",
      "year": 2000
    }
  ],
  "based_on": [
    {
      "wikidata_id": "Q837283",
      "label": "Fight Club",
      "author": {
        "wikidata_id": "Q268181",
        "label": "Chuck Palahniuk"
      }
    }
  ],
  "filming_locations": [
    {
      "wikidata_id": "Q65",
      "label": "Los Angeles"
    }
  ],
  "narrative_locations": [
    {
      "wikidata_id": "Q65",
      "label": "Los Angeles"
    }
  ],
  "original_broadcasters": []
}
```

L'objet `sitelinks` a 14 entrées et `awards` en a 5. Les deux sont réduits ici.

| Champ                                                               | Type           | Remarques                                                                                                                     |
| ------------------------------------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `id`                                                                | entier         | Identifiant TMDB du titre. Il reste présent avec `append_to_response`.                                                        |
| `wikidata_id`                                                       | chaîne ou null | Élément Wikidata comme `Q190050`.                                                                                             |
| `budget`                                                            | objet ou null  | `value` est un entier arrondi et `currency` est un code ISO ou `null`.                                                        |
| `box_office`                                                        | objet ou null  | Comme `budget`, plus `worldwide` réglé sur `true` ou `false`.                                                                 |
| `follows`, `followed_by`                                            | objet ou null  | Le titre précédent et le suivant dans une série de films, sous forme de lien.                                                 |
| `sitelinks`                                                         | objet          | Associe un code de langue au titre de la page Wikipédia. Les clés sont les 14 langues servies. `{}` quand il n'y en a aucune. |
| `awards`, `nominations`                                             | tableau        | Liens avec un `year` facultatif.                                                                                              |
| `based_on`                                                          | tableau        | Œuvres sources avec `wikidata_id`, `label` et un objet `author` ou `null`.                                                    |
| `filming_locations`, `narrative_locations`, `original_broadcasters` | tableau        | Liens. Breaking Bad a AMC dans `original_broadcasters`.                                                                       |

Un lien a `wikidata_id`, `label` et, quand l'élément est un titre du catalogue, `tmdb_id` et `media_type`. Pour The Matrix Reloaded (film 604), les voisins sont des liens vers les films 603 et 605 :

```json
{
  "follows": {
    "wikidata_id": "Q83495",
    "label": "The Matrix",
    "tmdb_id": 603,
    "media_type": "movie"
  },
  "followed_by": {
    "wikidata_id": "Q207536",
    "label": "The Matrix Revolutions",
    "tmdb_id": 605,
    "media_type": "movie"
  }
}
```

Chaque `label` vient dans la `language` de la requête et se replie sur l'anglais. Avec `language=ru`, l'auteur ci-dessus s'écrit `Чак Паланик`.

## Erreurs

Les erreurs utilisent le corps TMDB, par exemple `{"success": false, "status_code": 7, "status_message": "Invalid API key: You must be granted a valid key."}`.

| HTTP | status_code | Quand                                                                         |
| ---- | ----------- | ----------------------------------------------------------------------------- |
| 400  | 22          | `external_source` est absent, pas en minuscules ou absent de la liste.        |
| 401  | 7           | La clé est absente ou fausse.                                                 |
| 402  | 36          | La période de l'offre est terminée.                                           |
| 404  | 34          | L'identifiant du titre dans un chemin `wikidata` n'existe pas.                |
| 429  | 25          | Au-dessus de vos requêtes par minute. Attendez les secondes de `Retry-After`. |

Un identifiant externe inconnu sur `find` n'est pas une erreur : attendez-vous à cinq tableaux vides. Les points de terminaison `external_ids` ne répondent pas non plus 404 pour un identifiant inconnu. Ils répondent 200 avec tous les identifiants à `null`. Voir [erreurs](https://amodb.dev/fr/errors/) et [authentification](https://amodb.dev/fr/authentication/).

## Remarques pratiques

- Enregistrez l'identifiant TMDB la première fois que vous résolvez un identifiant externe. Les appels suivants sautent alors `find` et vont directement au chemin de détails, ce qui économise une requête par titre.
- Vérifiez toujours que le tableau voulu contient un élément. `find` peut renvoyer plusieurs tableaux à la fois pour un même identifiant.
- Les détails et les identifiants externes sont mis en cache 6 heures en périphérie. Une recherche répétée dans ce délai renvoie la réponse stockée.
- `wikidata_id` fonctionne dans les deux sens : passez-le à `find` pour obtenir un titre, ou lisez-le dans `external_ids` pour faire un lien sortant.
- Pour reprendre les recherches IMDb de style OMDb, voir le [point de terminaison OMDb](https://amodb.dev/fr/omdb-endpoint/). Pour les notes après avoir résolu un titre, voir [notes](https://amodb.dev/fr/ratings/).

## Questions et réponses

### Quelles sources externes find accepte-t-il ?

Douze valeurs sont acceptées pour external_source. Sept d'entre elles donnent des résultats : imdb_id, tvdb_id, wikidata_id, kinopoisk_id, facebook_id, twitter_id et instagram_id. Les cinq autres renvoient des tableaux vides. La valeur est obligatoire, en minuscules et exacte, par exemple external_source=imdb_id.

### Pourquoi find renvoie-t-il cinq tableaux ?

Un identifiant peut désigner un film, une personne, une série, un épisode ou une saison : la réponse a donc un tableau pour chaque genre. Dans amodb, seuls movie_results, person_results et tv_results contiennent des éléments. tv_episode_results et tv_season_results sont toujours vides.

### Que se passe-t-il quand l'identifiant est inconnu ?

Vous obtenez un statut 200 avec les cinq tableaux vides, comme dans TMDB. Vérifiez qu'au moins un tableau contient un élément avant de le lire. Un external_source absent ou inconnu est différent : il répond 400 avec status_code 22.

### Comment obtenir un identifiant Kinopoisk pour un titre que j'ai déjà ?

Appelez le point de terminaison external_ids du film ou de la série. Il renvoie kinopoisk_id sous forme de chaîne comme 361 pour Fight Club, ou null quand amodb ne le connaît pas. Passez cette chaîne à find avec external_source=kinopoisk_id pour revenir en arrière.

### Puis-je ajouter wikidata à un appel de détails ?

Oui. Ajoutez append_to_response=wikidata à une requête de détails de film ou de série, et le bloc Wikidata arrive sous la clé wikidata, dans la même requête et sans appel supplémentaire.

## 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.
- [Notes des films et séries](https://amodb.dev/fr/ratings/): API de notes de films : scores IMDb, Kinopoisk, Metacritic, Rotten Tomatoes et TMDB d'un titre en un appel, avec null pour toute source inconnue.
- [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.
- [Endpoint compatible OMDb](https://amodb.dev/fr/omdb-endpoint/): Endpoint compatible OMDb sur api.amodb.dev/omdb/. Cherchez par i ou t, recherchez avec s, lisez Ratings et gardez votre client en changeant l'URL de base.
- [Authentification](https://amodb.dev/fr/authentication/): Comment envoyer votre clé amodb : api_key dans la requête, en-tête Authorization Bearer, ou apikey pour OMDb. Format, stockage, rotation et erreurs 401.

Mis à jour: 2026-10-18. Source: https://amodb.dev/fr/find-by-external-id/