- Documentation
- Key Concepts
- Release Notes
Sample queries: Title/Name
Queries to help you get started with essential IMDb data: title ratings, title metadata, top cast and more.
Average Rating for Suicide Squad
Supported on the Ratings, IMDb Title and Name Essentials, and Box Office API.
To query the current IMDb star rating for Suicide Squad (2021) along with the total number of user ratings for that title, the query would include the following:
- QUERY
- RESULT
1
2
3
4
5
6
7
8
query {
title(id: "tt6334354") {
ratingsSummary {
aggregateRating
voteCount
}
}
}Result size: 71 bytes
The response returns (at the time of the data pull) Suicide Squad with an aggregateRating of 7.2 based on 384,799 unique user ratings.
Get Plot Texts and Genres
Supported on the IMDb Title and Name Essentials, and Box Office API products.
To query a request for the first two plot texts, genre, and ratings certificate details for It (2017):
- QUERY
- RESULT
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
query {
title(id: "tt1396484") {
titleGenres {
genres {
genre {
text
}
}
}
plots(first: 2) {
edges {
node {
plotText {
plainText
}
}
}
}
certificate {
rating
ratingReason
}
}
}Result size: 693 bytes
The response returns the plotText in the "plainText" node fields followed by the "R" rating and the ratingReason provided by the MPA."
Runtime, Release Date, Coloration
Supported on the IMDb Title and Name Essentials, and Box Office API products.
To query runtime, release date, and color info for Wall-E:
- QUERY
- RESULT
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
query {
title(id: "tt0910970") {
runtime {
seconds
}
releaseDate {
day
month
year
}
technicalSpecifications {
colorations {
items {
text
}
}
}
}
}Result size: 156 bytes
The response returns runtime in seconds (5,880), release date broken down by day/month/year (6/27/2008), and that the film was in "Color.
Credits
Supported on the IMDb Title and Name Essentials, and Box Office API products.
To query WALL-E credits:
- QUERY
- RESULT
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
query {
# Get WALL·E
title(id: "tt0910970") {
# Get the first two credits for WALL·E
credits(first: 2) {
edges {
node {
# Get the name associated with that credit
name {
nameText {
text
}
}
# Get the category for that credit (e.g Actor, Director)
category {
text
}
}
}
}
}
}Result size: 199 bytes
The response returns the first two credits listed along with the name text (Ben Burtt and Elissa Knight) and the job category (Actor and Actress).
Querying multiple categories of credits
Supported on the IMDb Title and Name Essentials, and Box Office API products.
To query directors, writers and cast for Joker:
- QUERY
- RESULT
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
query {
#Get Joker
title(id: "tt7286456") {
# Get first five directors
DIRECTORS: credits(first: 5, filter: { categories: ["director"] }) {
edges {
node {
name {
nameText {
text
}
}
}
}
}
# Get first five writers
WRITERS: credits(first: 5, filter: { categories: ["writer"] }) {
edges {
node {
name {
nameText {
text
}
}
}
}
}
# Get first five cast
CAST: credits(first: 5, filter: { categories: ["actor", "actress"] }) {
edges {
node {
name {
nameText {
text
}
}
}
}
}
}
}Result size: 686 bytes
You can't directly query for the same field with different arguments. That's why you need aliases - they let you rename the result of a field to anything you want.
Known For Titles from Credits
Supported on the IMDb Title and Name Essentials, and Box Office API products.
This sample query highlights the power of GraphQL. The query returns cast credits on Inception and dives a layer deeper to query the "known for" titles for each actor alongside their character name and the movie's IMDb Star Rating:
- QUERY
- RESULT
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
query {
# Get the movie Inception
title(id: "tt1375666") {
# Get the first two credits on Inception
credits(first: 2) {
edges {
node {
# Get the name associated with a given credit
name {
nameText {
text
}
# Get the first two titles that name is known for
knownFor(first: 2) {
edges {
node {
title {
#Get the title text for the title that the name is known for
titleText {
text
}
# Get the rating for that title that the name is known for
ratingsSummary {
aggregateRating
}
}
summary {
# Get the name of the charachter that they played in the title they are known for
principalCharacters {
name
}
}
}
}
}
}
}
}
}
}Result size: 793 bytes
The response returns that Leonardo DiCaprio is known for both Inception (IMDb Rating of 8.8) - where he played Cobb - and Titanic (7.9) - where he played Jack and that Joseph Gordon-Levitt is known for both Inception (8.8) - where he played Arthur - and Looper (7.4) - where he played Joe.
Title Keywords
Supported on the IMDb Title and Name Essentials, and Box Office API products.
IMDb provides keywords associated with each title in the dataset alongside user votes of how "relevant" that keyword is for the movie. To include keywords from Inception and The Dark Knight in this query:
- QUERY
- RESULT
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
# Get Inception and The Dark Knight
titles(ids: ["tt1375666", "tt0468569"]) {
# Get the first keyword for each title
keywords(first: 1) {
edges {
node {
# Get the keyword text
keyword {
text {
text
}
}
# Get the number of interesting votes for this keyword
interestScore {
usersInterested
usersVoted
}
}
}
}
}
}Result size: 270 bytes
The response returns IMDb users sentiment reflecting "dream" as the most relevant keyword for Inception while "dc comics" is most relevant for The Dark Knight.
Name Awards
Supported on the IMDb Title and Name Essentials, and Box Office API products.
IMDb provides information on the cast and crew involved in movies and TV series. To query the first three awards won by three different actors - Jennifer Lawrence, Morgan Freeman, and Patrick Swayzee:
- QUERY
- RESULT
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
query {
# Get Jennifer Lawrence, Morgan Freeman and Patrick Swayzee
names(ids: ["nm2225369", "nm0000664", "nm0000151"]) {
nameText {
text
}
# Get the first 3 awards that a given name won
awardNominations(first: 3, filter: { wins: WINS_ONLY }) {
edges {
node {
award {
# Get the award text for a given award
text
# Get the name of the event the award was given
event {
text
}
# Get the year of the award
year
}
}
}
}
}
}Result size: 1,203 bytes
The response returns three awards per person queried. You can also find awards by year, event, and whether a cast or crew member was nominated or won an award.
Episodes
Supported on the IMDb Title and Name Essentials, and Box Office API products.
IMDb provides data for global TV series as well as movies. To query episodes from Futurama:
- QUERY
- RESULT
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
query {
# Get Futurama
title(id: "tt0149460") {
# Get the title type of Futurama (TV Series)
titleType {
text
canHaveEpisodes
}
# Get the first three episodes of Futurama
episodes {
episodes(first: 3) {
edges {
node {
# Get the names of the episodes
titleText {
text
}
}
}
pageInfo{
endCursor
hasNextPage
}
}
}
}
}Result size: 391 bytes
The response returns Futuramas first three episodes: "Space Pilot 3000," "The Series Has Landed," and "I, Roommate."
Episodes - Pagination
Supported on the IMDb Title and Name Essentials, and Box Office API products.
This example demonstrates how to use cursor-based pagination to retrieve next 3 episodes for Futurama.
- QUERY
- RESULT
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
query {
# Get Futurama
title(id: "tt0149460") {
# Get the title type of Futurama (TV Series)
titleType {
text
canHaveEpisodes
}
# Get the next three episodes of Futurama
episodes {
episodes(first: 3, after:"dHQwNzU2ODgy") {
edges {
node {
# Get the names of the episodes
titleText {
text
}
}
}
pageInfo{
endCursor
hasNextPage
}
}
}
}
}Result size: 407 bytes
The response returns a list of 3 episodes starting from the 4th episode. Use the 'endCursor' value as the 'after' parameter in your next query to retrieve more episodes. Note that cursors are temporary and may change, so do not store them for future use.
Get started with our box office data learning about lifetime grosses, regional results, and weekend returns.