The data model
Three nested things: a ceremony holds categories, a category holds nominations. Everything the API returns is some slice of that.
Ceremony
Keyed by the year the ceremony was held, not the year the films came out. The 1929 ceremony honours films from 1927 and 1928. A ceremony is an array of categories, in programme order.
Category
A category has a category name and a nominations array. Category names are recorded as they were used at the time, which means they change across the archive. The leading acting award appears as “Best Actor in a Leading Role” in the early years and “Best Performance by an Actor in a Leading Role” more recently.
It is the reason the category endpoints match on a substring rather than the whole name. Searching for Actor in a Leading Role finds both spellings; searching for the full modern name finds only the recent ones.
Nomination
A nomination has four fields, two of which are arrays. This is the part worth reading carefully.
| Field | Type | Meaning |
|---|---|---|
primary | string[] | Who or what the nomination is for. |
secondary | string[] | The context: the film, or the people who share the award. |
won | boolean | Whether this nomination won the category. |
notes | string | Optional. Historical footnotes — irregular ceremonies, shared awards, withdrawn nominations. Present on roughly 1,200 nominations. |
primary and secondary swap roles
There is no single rule like “primary is always the person”. The two fields describe the shape of the award, and that shape differs by category.
For Best Picture, the film is the nominee and the producers share it:
{
"category": "Best Picture",
"nominations": [
{
"primary": ["One Battle after Another"],
"secondary": ["Adam Somner", "Sara Murphy", "Paul Thomas Anderson"],
"won": true
}
]
}For acting and directing, the person is the nominee and the film is context:
{
"category": "Best Performance by an Actor in a Leading Role",
"nominations": [
{
"primary": ["Michael B. Jordan"],
"secondary": ["Sinners"],
"won": true
}
]
}Both fields are arrays because either side can hold several values — a producing team, or a performer nominated for two films in the same year.
Notes
The early ceremonies were not run the way they are now, and the archive records that.
{
"primary": ["Emil Jannings"],
"secondary": ["The Last Command", "The Way of All Flesh"],
"won": true,
"notes": "Emil Jannings received his award early due to the fact that he was going home to Europe before the ceremony."
}What this means for searching
The person and film endpoints both match against primary and secondary, exactly. A useful consequence: searching a film title through the person endpoint finds every category it was nominated in across every year, because the title appears in one field or the other either way.