Search Queries

Fresh

The IMDb API supports two search modes: mainSearch for simple text matching and advancedTitleSearch for filtered searches with constraints on genre, awards, release date, and more.

---

1. Top 5 Movie Titles Matching "Goodfellas"

Use mainSearch with titleSearchOptions to search for movie titles by text.

{
  mainSearch(
    first: 5,
    options: {
      searchTerm: "Goodfellas",
      type: TITLE,
      titleSearchOptions: {
        type: MOVIE
      }
    }
  ) {
    edges {
      node {
        entity {
          ... on Title {
            id
            titleText { text }
            releaseYear { year }
            ratingsSummary {
              aggregateRating
              voteCount
            }
          }
        }
      }
    }
  }
}

Response:

{
  "data": {
    "mainSearch": {
      "edges": [
        {
          "node": {
            "entity": {
              "id": "tt0099685",
              "titleText": { "text": "Goodfellas" },
              "releaseYear": { "year": 1990 },
              "ratingsSummary": {
                "aggregateRating": 8.7,
                "voteCount": 1200000
              }
            }
          }
        }
      ]
    }
  }
}

Title Type Options

The type argument in titleSearchOptions accepts:

• MOVIE
• TV_SERIES
• TV_MINI_SERIES
• TV_MOVIE
• VIDEO_GAME
• SHORT

---

2. Top 10 Names Matching "Jennifer"

Use mainSearch with type: NAME to search for people by name.

{
  mainSearch(
    first: 10,
    options: {
      searchTerm: "Jennifer",
      type: NAME
    }
  ) {
    edges {
      node {
        entity {
          ... on Name {
            id
            nameText { text }
            primaryProfessions {
              category {
                text
              }
            }
            knownFor(first: 1) {
              edges {
                node {
                  title {
                    titleText { text }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

This returns the top 10 people whose names match "Jennifer", including their primary profession and most notable title.

---

3. Advanced Search — Action Movies with Academy Awards After 2010

Use advancedTitleSearch to combine multiple constraints in a single filtered query.

{
  advancedTitleSearch(
    first: 10,
    constraints: {
      titleTypeConstraint: {
        anyTitleTypeIds: ["movie"]
      },
      genreConstraint: {
        allGenreIds: ["Action"]
      },
      awardConstraint: {
        allEventIds: ["ev0000003"],
        wins: true
      },
      releaseDateConstraint: {
        releaseDateRange: {
          start: "2010-01-01",
          end: "2026-12-31"
        }
      }
    },
    sort: {
      sortBy: POPULARITY,
      sortOrder: ASC
    }
  ) {
    edges {
      node {
        title {
          id
          titleText { text }
          releaseYear { year }
          ratingsSummary {
            aggregateRating
          }
          genres {
            genres {
              text
            }
          }
        }
      }
    }
    total
  }
}

Constraint Reference

Constraint	Description	Example Value
titleTypeConstraint	Filter by title type	anyTitleTypeIds: ["movie"]
genreConstraint	Filter by genre	allGenreIds: ["Action", "Drama"]
awardConstraint	Filter by award event and win status	allEventIds: ["ev0000003"], wins: true
releaseDateConstraint	Filter by release date range	releaseDateRange: { start: "2010-01-01" }
ratingConstraint	Filter by minimum rating	aggregateRatingRange: { min: 7.0 }
voteCountConstraint	Filter by minimum votes	aggregateVoteCountRange: { min: 10000 }
languageConstraint	Filter by primary language	anyPrimaryLanguages: ["en"]
originCountryConstraint	Filter by country of origin	anyCountries: ["US"]

Common Award Event IDs

Event ID	Award Name
ev0000003	Academy Awards (Oscars)
ev0000292	Golden Globe Awards
ev0000292	BAFTA Awards
ev0000003	Academy Awards

Sort Options

Sort By	Description
POPULARITY	Sort by current popularity rank
RANKING	Sort by user rating
RELEASE_DATE	Sort by release date
TITLE_REGIONAL	Sort alphabetically by title
BOX_OFFICE_GROSS_DOMESTIC	Sort by domestic box office