Person details API
The person endpoint returns one actor, director or crew member by id at GET /3/person/{person_id}. The JSON matches TMDB v3: biography, birthday, place of birth, profile image and department. Companion endpoints return movie, TV and combined credits, external ids, profile images and the popular list.
Get person details
GET /3/person/{person_id} returns the core record for one person: name, biography, birthday, place of birth, department, profile image and IMDb id. The id is the numeric TMDB person id, so Tom Hanks stays 31 and Leonardo DiCaprio stays 6193. People who work in front of and behind the camera share one id space.
The example reads Tom Hanks and appends his combined credits, then prints the name, birthday, main department and how many acting credits he has.
curl -sSf "https://api.amodb.dev/3/person/31?language=en-US&append_to_response=combined_credits" \
-H "Authorization: Bearer $AMODB_KEY"const url = 'https://api.amodb.dev/3/person/31?language=en-US&append_to_response=combined_credits';
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` } });
if (!res.ok) throw new Error(`amodb returned ${res.status}`);
const person = await res.json();
console.log(person.name, person.birthday, person.known_for_department, person.combined_credits.cast.length);import os
import requests
r = requests.get(
"https://api.amodb.dev/3/person/31",
params={"language": "en-US", "append_to_response": "combined_credits"},
headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
timeout=10,
)
r.raise_for_status()
person = r.json()
print(person["name"], person["birthday"], person["known_for_department"], len(person["combined_credits"]["cast"]))<?php
$url = 'https://api.amodb.dev/3/person/31?language=en-US&append_to_response=combined_credits';
$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");
}
$person = json_decode($body, true);
echo $person['name'], ' ', $person['birthday'], ' ', count($person['combined_credits']['cast']), PHP_EOL;package main
import (
"encoding/json"
"fmt"
"net/http"
"os"
"time"
)
type Person struct {
Name string `json:"name"`
Birthday string `json:"birthday"`
Department string `json:"known_for_department"`
PlaceOfBirth string `json:"place_of_birth"`
}
func main() {
req, _ := http.NewRequest("GET", "https://api.amodb.dev/3/person/31?language=en-US", 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 Person
if err := json.NewDecoder(res.Body).Decode(&p); err != nil {
panic(err)
}
fmt.Println(p.Name, p.Birthday, p.Department, p.PlaceOfBirth)
}Parameters
| Parameter | In | Required | Description |
|---|---|---|---|
person_id | path | yes | Numeric person id, for example 31. |
api_key | query | one of two | Your key. Use this or the Authorization: Bearer header. |
language | query | no | TMDB tag such as en-US or ru-RU. The biography is returned in that language when a translation exists. |
append_to_response | query | no | Comma separated list: movie_credits, tv_credits, combined_credits, external_ids, images. Unknown names are ignored. |
Response fields
| Field | Type | Notes |
|---|---|---|
id | integer | Person id. |
name | string | Display name, in the requested language when a translation exists. |
also_known_as | array | Alternative names and spellings. |
biography | string | Localized text, empty when no translation exists. |
birthday, deathday | string or null | YYYY-MM-DD. deathday is null for living people. |
place_of_birth | string or null | Free text. |
gender | integer | 0 not specified, 1 female, 2 male, 3 non-binary. |
known_for_department | string | Main job, for example Acting or Directing. |
imdb_id | string or null | IMDb person id such as nm0000158. |
homepage | string or null | Official site. |
profile_path | string or null | Append to https://img.amodb.dev/t/p/{size}. See images. |
popularity | number | Relative score used by the popular list. |
adult | boolean | Always false. Adult people are never served. |
Example response
GET /3/person/31?language=en-US, with the biography shortened:
{
"adult": false,
"also_known_as": [
"Thomas Jeffrey Hanks"
],
"biography": "Thomas Jeffrey Hanks (born July 9, 1956) is an American actor and filmmaker. Known for both his comedic and dramatic roles, Hanks is one of the most popular...",
"birthday": "1956-07-09",
"deathday": null,
"gender": 2,
"homepage": null,
"id": 31,
"imdb_id": "nm0000158",
"known_for_department": "Acting",
"name": "Tom Hanks",
"place_of_birth": "Concord, California, USA",
"popularity": 12.98,
"profile_path": "/oFvZoKI6lvU03n4YoNGAll9rkas.jpg"
}Filmography endpoints
Three endpoints list what a person worked on. All take language and return the keys id, cast and crew. When you append them with append_to_response, the id key is left out.
| Method and path | Returns | Extra parameters |
|---|---|---|
GET /person/{person_id}/movie_credits | Movies, with character and order in cast and department and job in crew | none |
GET /person/{person_id}/tv_credits | Shows, with character in cast and department and job in crew | none |
GET /person/{person_id}/combined_credits | Movies and shows together, each with media_type set to movie or tv | none |
Movie entries carry title and release_date. TV entries carry name and first_air_date, and TV cast entries also hold an episode_count key that is 0 in current data. Entries also carry credit_id, genre_ids, poster_path, vote_average and the other list fields. The snippet below sorts combined credits by date and prints the five newest.
const credits = person.combined_credits;
const date = (c) => c.release_date || c.first_air_date || '';
const latest = credits.cast.filter((c) => date(c)).sort((a, b) => date(b).localeCompare(date(a))).slice(0, 5);
for (const c of latest) console.log(date(c), c.media_type, c.title || c.name, 'as', c.character);Lists and images
| Method and path | Returns | Extra parameters |
|---|---|---|
GET /person/popular | Paged list of popular people with known_for titles | language, page |
GET /person/{person_id}/images | Profile photos in a profiles array | none |
GET /person/{person_id}/external_ids | imdb_id, wikidata_id, facebook_id, instagram_id, tiktok_id, twitter_id, youtube_id | none |
Popular entries hold id, name, original_name, known_for_department, gender, profile_path, popularity and a known_for array. Pages run from 1 to 500. Profile photos are covered on images, and external ids are on find by external id.
amodb does not offer person translations, the newest person record, tagged images or changes. Ask for the biography in the language you need with the language parameter instead.
Errors
| HTTP | status_code | When |
|---|---|---|
| 401 | 7 | The key is missing or wrong. |
| 402 | 36 | The plan period has ended. |
| 404 | 34 | No person with that id, an adult person, or a path that is not offered. |
| 405 | 37 | You called a write method. |
| 429 | 25 | Over your requests per minute. Wait for the Retry-After seconds. |
The full list is on errors, and the windows per plan are on rate limits.
Practical notes
- Person details and credit lists are cached for 6 hours. The popular list is cached for 30 minutes and pages run from 1 to 500.
- Add
combined_creditsthroughappend_to_responseinstead of making a second call. Both ways return the same data. - In
movie_credits, eachcastentry has anordervalue, the person's billing position in that movie. TV entries have noorder, so sort them byfirst_air_date. - Use
known_for_departmentto decide which list to show first:castfor actors,crewfor directors and writers. - Look up a person by name on search, then use the id here.