The New York Times Most Popular API
The Most Popular API provides services for getting the most popular articles on NYTimes.com based on emails, shares, or views. Retrieve the most emailed, shared, and viewed articles by section and time period.
OpenAPI Specification
openapi: 3.0.0
servers:
- url: http://api.nytimes.com/svc/mostpopular/v2
- url: https://api.nytimes.com/svc/mostpopular/v2
info:
description: Get lists of NYT Articles based on shares, emails, and views.
termsOfService: http://developer.nytimes.com/tou
title: Most Popular API
version: 2.0.0
x-apiClientRegistration:
url: http://developer.nytimes.com/signup
x-apisguru-categories:
- media
- open_data
x-logo:
url: https://api.apis.guru/v2/cache/logo/https_static01.nyt.com_images_icons_t_logo_291_black.png
x-origin:
- format: openapi
url: https://raw.githubusercontent.com/nytimes/public_api_specs/master/most_popular_api/most_popular_api_v2.json
version: "3.0"
x-providerName: nytimes.com
x-serviceName: most_popular_api
externalDocs:
url: http://developer.nytimes.com/
paths:
"/mostemailed/{section}/{time-period}.json":
get:
description: ""
operationId: GET_mostemailed-section-time-period-json
responses:
"200":
content:
application/json:
schema:
properties:
copyright:
type: string
num_results:
type: integer
results:
items:
$ref: "#/components/schemas/ArticleWithCountType"
type: array
status:
type: string
type: object
application/xml:
schema:
properties:
copyright:
type: string
num_results:
type: integer
results:
items:
$ref: "#/components/schemas/ArticleWithCountType"
type: array
status:
type: string
type: object
description: An array of Articles
"400":
content:
application/json:
examples:
response:
value:
copyright: Copyright (c) 2016 The New York Times Company. All Rights Reserved.
errors:
- Param 'period' is invalid.
results: []
status: ERROR
schema:
properties:
copyright:
type: string
errors:
items:
type: string
type: array
results:
items: {}
type: array
status:
type: string
type: object
application/xml:
schema:
properties:
copyright:
type: string
errors:
items:
type: string
type: array
results:
items: {}
type: array
status:
type: string
type: object
description: ""
"403":
content:
application/json:
schema:
type: object
application/xml:
examples:
response:
value: <h1>Developer Over Qps</h1>
schema:
type: object
description: ""
security:
- api-key: []
summary: Most Emailed by Section & Time Period
parameters:
- $ref: "#/components/parameters/Section"
- $ref: "#/components/parameters/TimePeriod"
"/mostshared/{section}/{time-period}.json":
get:
description: ""
operationId: GET_mostshared-section-time-period-json
responses:
"200":
content:
application/json:
examples:
response:
value:
copyright: Copyright (c) 2016 The New York Times Company. All Rights Reserved.
num_results: 24
results:
- abstract: Timothy D. Cook, Apple’s chief, said the government’s request to bypass security on the phone used by Syed Rizwan Farook had “chilling†implications.
asset_id: 100000004214575
byline: By ERIC LICHTBLAU and KATIE BENNER
column: ""
des_facet:
- IPHONE
geo_facet: ""
media:
- caption: Timothy D. Cook, the chief executive of Apple, released a letter to customers several hours after a California judge ordered the company to unlock an iPhone used by one of the shooters in a recent attack that killed 14 people in San Bernardino.
copyright: Jeff Chiu/Associated Press
media-metadata:
- format: Standard Thumbnail
height: 75
url: http://static01.nyt.com/images/2016/02/18/world/18Appleletter-web/18Appleletter-web-thumbStandard.jpg
width: 75
subtype: photo
type: image
org_facet:
- APPLE INC
per_facet:
- COOK, TIMOTHY D
published_date: 2016-02-18
section: Technology
source: The New York Times
title: Apple Fights Order to Unlock San Bernardino Gunman’s iPhone
total_shares: 1
url: http://www.nytimes.com/2016/02/18/technology/apple-timothy-cook-fbi-san-bernardino.html
status: OK
schema:
properties:
copyright:
type: string
num_results:
type: integer
results:
items:
$ref: "#/components/schemas/Article"
type: array
status:
type: string
type: object
description: An array of Articles
"400":
content:
application/json:
examples:
response:
value:
copyright: Copyright (c) 2016 The New York Times Company. All Rights Reserved.
errors:
- "Please specify a supported period, options are: 1,7,30"
results: []
status: ERROR
schema:
properties:
copyright:
type: string
errors:
items:
type: string
type: array
results:
items: {}
type: array
status:
type: string
type: object
description: ""
security:
- api-key: []
summary: Most Shared by Section & Time Period
parameters:
- $ref: "#/components/parameters/Section"
- $ref: "#/components/parameters/TimePeriod"
"/mostviewed/{section}/{time-period}.json":
get:
description: ""
operationId: GET_mostviewed-section-time-period-json
responses:
"200":
content:
application/json:
examples:
response:
value:
copyright: Copyright (c) 2016 The New York Times Company. All Rights Reserved.
num_results: 121
results:
- abstract: Republicans have parked themselves so far to the right for so many years that it’s not clear if they can hear how deranged they sound.
adx_keywords: Supreme Court (US);McConnell, Mitch;Scalia, Antonin;Obama, Barack;Kirk, Mark Steven;Republican Party;Senate;Cornyn, John;Collins, Susan M
asset_id: 100000004229487
byline: By THE EDITORIAL BOARD
column: Editorial
des_facet: ""
geo_facet: ""
id: 100000004229487
media: ""
org_facet:
- SUPREME COURT (US)
per_facet:
- MCCONNELL, MITCH
published_date: 2016-02-25
section: Opinion
source: The New York Times
title: Senate Republicans Lose Their Minds on a Supreme Court Seat
type: Article
url: http://www.nytimes.com/2016/02/25/opinion/senate-republicans-lose-their-minds-on-a-supreme-court-seat.html
views: 1
status: OK
schema:
properties:
copyright:
type: string
num_results:
type: integer
results:
items:
$ref: "#/components/schemas/Article"
type: array
status:
type: string
type: object
description: An array of Articles
security:
- api-key: []
summary: Most Viewed by Section & Time Period
parameters:
- $ref: "#/components/parameters/Section"
- $ref: "#/components/parameters/TimePeriod"
components:
parameters:
OffSet:
description: Positive integer in a multiple of 20
in: query
name: offset
schema:
default: 20
type: integer
Section:
description: |
Limits the results by one or more sections. You can use
`all-sections` or one or more section names seperated by semicolons. See `viewed/sections.json` call to get a list of sections.
in: path
name: section
required: true
schema:
enum:
- Arts
- Automobiles
- Blogs
- Books
- Business Day
- Education
- Fashion & Style
- Food
- Health
- Job Market
- Magazine
- membercenter
- Movies
- Multimedia
- N.Y.%20%2F%20Region
- NYT Now
- Obituaries
- Open
- Opinion
- Public Editor
- Real Estate
- Science
- Sports
- Style
- Sunday Review
- T Magazine
- Technology
- The Upshot
- Theater
- Times Insider
- Today’s Paper
- Travel
- U.S.
- World
- Your Money
- all-sections
type: string
SharedTypes:
description: Limits the results by the method used to share the items only works on mostshared requests.
in: query
name: shared-types
schema:
enum:
- digg
- email
- facebook
- mixx
- myspace
- permalink
- timespeople
- twitter
- yahoobuzz
type: string
TimePeriod:
description: Number of days `1 | 7 | 30 ` corresponds to a day, a week, or a month of content.
in: path
name: time-period
required: true
schema:
enum:
- "1"
- "7"
- "30"
type: string
schemas:
Article:
properties:
abstract:
type: string
byline:
type: string
column:
type: string
des_facet:
$ref: "#/components/schemas/DesFacet"
geo_facet:
$ref: "#/components/schemas/GeoFacet"
media:
items: {}
oneOf:
- items: {}
type: array
- type: string
org_facet:
$ref: "#/components/schemas/OrgFacet"
per_facet:
$ref: "#/components/schemas/PerFacet"
published_date:
type: string
section:
type: string
source:
type: string
title:
type: string
url:
type: string
type: object
ArticleWithCountType:
properties:
abstract:
type: string
byline:
type: string
column:
type: string
count_type:
type: string
des_facet:
$ref: "#/components/schemas/DesFacet"
geo_facet:
$ref: "#/components/schemas/GeoFacet"
media:
items:
properties:
caption:
type: string
copyright:
type: string
media-metadata:
properties:
format:
type: string
height:
type: integer
url:
type: string
width:
type: integer
type: object
subtype:
type: string
type:
type: string
type: object
type: array
x-runscope/nullable: true
x-runscope/nullable/value: "''"
org_facet:
$ref: "#/components/schemas/OrgFacet"
per_facet:
$ref: "#/components/schemas/PerFacet"
published_date:
type: string
section:
type: string
source:
type: string
title:
type: string
url:
type: string
type: object
DesFacet:
items: {}
oneOf:
- items: {}
type: array
- type: string
GeoFacet:
enum:
- ""
items: {}
nullable: true
oneOf:
- items: {}
type: array
- type: string
OrgFacet:
items: {}
nullable: true
type: array
PerFacet:
items: {}
nullable: true
type: array
securitySchemes:
api-key:
in: query
name: api-key
type: apiKey