Most Popular API
Get lists of NYT Articles based on shares, emails, and views
COMMUNITYAPI KEY0 INSTALLS
OpenAPI Specificationv3.0
{
"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\n`all-sections` or one or more section names seperated by semicolons. See `viewed/sections.json` call to get a list of sections. \n",
"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"
}
}
}
}