The New York Times Movie Reviews API
Search for NYT movie reviews by keyword and get lists of NYT Critics' Picks. As an alternative, use the Article Search API with appropriate filter queries to access movie review content.
OpenAPI Specification
openapi: 3.0.1
info:
title: The New York Times Movie Reviews API
description: |
**NOTE: The Movie Reviews API has been shutdown.**
As an alternative, use the [Article Search API](https://developer.nytimes.com/docs/articlesearch-product/1/overview) to get New York Times movie reviews using the following filter query:
```
section_name:"Movies" AND type_of_material:"Review"
```
<https://api.nytimes.com/svc/search/v2/articlesearch.json?fq=section_name%3A"Movies"%20AND%20type_of_material%3A"Review"&sort=newest&page=0&api-key{your-key}>
## Movie Reviews API (DEPRECATED)
Search New York Times movie reviews by keyword and opening date and filter by Critics' Picks.
Get movie reviews that are critics' picks:
```
/reviews/picks.json
```
Get movie reviews with "lebowski" in the title:
```
/reviews/search.json?query=lebowski
```
Get movie reviews with "big" in the title that opened in the U.S. between 1980 and 1990:
```
/reviews/search.json?query=big&opening-date=1980-01-01:1990-01-01
```
Get all movie reviews by A. O. Scott:
```
/critics/A.%20O.%20Scott.json
```
Get movie critic names:
```
/critics/all.json
```
## Example Call
```
https://api.nytimes.com/svc/movies/v2/reviews/search.json?query=godfather&api-key=yourkey
```
version: 2.0.0
servers:
- url: https://api.nytimes.com/svc/movies/v2
security:
- apikey: []
paths:
/critics/{reviewer}.json:
get:
tags:
- Movies
summary: Get Movie Critics Name, Bio And Image
description: |
Get movie critics. You can either specify the reviewer name or use "all", "full-time", or "part-time".
parameters:
- name: reviewer
in: path
description: "Reviewer name or \"all\" for all reviewers, \"full-time\" for full-time reviewers, or \"part-time\" for part-time reviewers."
required: true
schema:
type: string
responses:
"200":
description: Array of movie critics.
content:
application/json:
schema:
type: object
properties:
status:
type: string
copyright:
type: string
num_results:
type: integer
results:
type: array
items:
$ref: '#/components/schemas/Critic'
"401":
description: Unauthorized request. Make sure api-key is set.
content: {}
"429":
description: Too many requests. You reached your per minute or per day rate limit.
content: {}
/reviews/{type}.json:
get:
tags:
- Movies
summary: Get Movie Reviews
description: |
Get movie reviews. Can filter to only return Critics' Picks.
Supports ordering results by-publication-date or by-opening-date.
Use offset to paginate thru results, 20 at a time.
parameters:
- name: type
in: path
description: Filter by critics' pick or not.
required: true
schema:
type: string
enum:
- all
- picks
- name: offset
in: query
description: Sets the starting point of the result set. Needs to be multiple of 20.
schema:
type: integer
default: 0
- name: order
in: query
description: How to order the results.
schema:
type: string
enum:
- by-opening-date
- by-publication-date
responses:
"200":
description: Array of movie reviews.
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: "Status of call, should be OK."
copyright:
type: string
description: Copyright text.
has_more:
type: boolean
description: Whether there are more results to paginate thru.
num_results:
type: integer
description: Number of movies returned in the API response results array.
results:
type: array
items:
$ref: '#/components/schemas/Review'
"401":
description: Unauthorized request. Make sure api-key is set.
content: {}
"429":
description: Too many requests. You reached your per minute or per day rate limit.
content: {}
/reviews/search.json:
get:
tags:
- Movies
summary: Search Movie Reviews
description: |
Search for movie reviews. Supports filtering by Critics' Pick.
parameters:
- name: critics-pick
in: query
description: Set to Y to only show critics' picks. Otherwise shows both.
schema:
type: string
enum:
- "Y"
- name: offset
in: query
description: "Sets the starting point of the result set (0, 20, ...). Used to paginate thru results. Defaults to 0. The has_more field indicates the response has more results."
schema:
multipleOf: 20.0
type: integer
- name: opening-date
in: query
description: U.S. opening date range. Start and end dates separated by colon (e.g. 1930-01-01:1940-01-01).
schema:
type: string
- name: order
in: query
description: Field to order results by (e.g. by-publication-date).
schema:
type: string
enum:
- by-opening-date
- by-publication-date
- name: publication-date
in: query
description: Review publication date range. Start and end dates separated by colon (e.g. 1930-01-01:1940-01-01).
schema:
type: string
- name: reviewer
in: query
description: Filter by reviewer byline (e.g. Stephen Holden).
schema:
type: string
- name: query
in: query
description: Search keyword (e.g. lebowski).
schema:
type: string
responses:
"200":
description: Array of movie reviews.
content:
application/json:
schema:
type: object
properties:
status:
type: string
copyright:
type: string
has_more:
type: boolean
num_results:
type: integer
results:
type: array
items:
$ref: '#/components/schemas/Review'
"401":
description: Unauthorized request. Make sure api-key is set.
content: {}
"429":
description: Too many requests. You reached your per minute or per day rate limit.
content: {}
components:
schemas:
Critic:
type: object
properties:
display_name:
type: string
description: Critic's name (e.g. A. O. Scott).
sort_name:
type: string
description: Field used when sorting.
status:
type: string
description: "Status of the critic (full-time, part-time, or null)."
bio:
type: string
description: Short bio of critic.
seo-name:
type: string
description: Critic name for URL (spaces are replaced with hyphens and periods removed).
multimedia:
type: object
properties:
resource:
type: object
properties:
type:
type: string
description: Type of resource (always set to image).
src:
type: string
description: URL of image.
height:
type: integer
description: Image height.
width:
type: integer
description: Image width.
credit:
type: string
description: Image photo credit.
description: Image of critic.
Link:
type: object
properties:
type:
type: string
description: Type of asset linked to. Always article.
url:
type: string
description: Review URL.
suggested_link_text:
type: string
description: Suggested text for link.
MultiMedia:
type: object
properties:
type:
type: string
description: Image crop name.
src:
type: string
description: Image URL.
width:
type: integer
description: Image width.
height:
type: integer
description: Image height.
Review:
type: object
properties:
display_title:
type: string
description: Movie title.
mpaa_rating:
type: string
description: Movie MPAA rating (e.g. PG-13).
critics_pick:
type: integer
description: Set to 1 if a critics' pick and 0 if not.
byline:
type: string
description: Author of the review (e.g. Manohla Dargis).
headline:
type: string
description: Headline of the review.
summary_short:
type: string
description: Short summary about the review.
publication_date:
type: string
description: Review publication date.
opening_date:
type: string
description: Movie U.S. opening date.
date_updated:
type: string
description: Last modified date of the review.
link:
$ref: '#/components/schemas/Link'
multimedia:
$ref: '#/components/schemas/MultiMedia'
securitySchemes:
apikey:
type: apiKey
name: api-key
in: query
tags:
- name: Movies