TopStories - topStories

Example

example.js

const { TopStories } = require('nytimes-api');
const top = new TopStories('your-super-secret-api-key');

top.topStories('politics', data => console.log(data));

What does it do?

topStories returns the top stories for a section of your choice. You can get the array of sections using sections. The code example above does the same.

Example Response

example-response.json

[ { section: 'U.S.',
    subsection: 'Politics',
    title:
     'Kamala Harris Says She’s Disappointed at Turn in Jussie Smollett Case',
    abstract:
     'Senators Harris and Cory Booker had both called the assault a “modern day lynching,” comments that Republicans are now criticizing them for.',
    url:
     'https://www.nytimes.com/2019/02/22/us/politics/jussie-smollett-kamala-harris.html',
    byline: 'By DANIEL VICTOR',
    item_type: 'Article',
    updated_date: '2019-02-22T00:51:24-05:00',
    created_date: '2019-02-22T00:37:05-05:00',
    published_date: '2019-02-22T00:37:05-05:00',
    material_type_facet: '',
    kicker: '',
    des_facet: [],
    org_facet: [],
    per_facet: [ 'Harris, Kamala D', 'Smollett, Jussie (1983- )' ],
    geo_facet: [],
    multimedia: [ [Object], [Object], [Object], [Object], [Object] ],
    short_url: 'https://nyti.ms/2GElbpd' },
  { section: 'U.S.',
    subsection: 'Politics',
    title:
     'Peace Treaty, and Peace Prize, for North Korea Appear to Tempt Trump',
    abstract:
     'As President Trump meets again with Kim Jong-un, North Korea’s leader, his role as a peacemaker is clearly weighing heavily on his mind.',
    url:
     'https://www.nytimes.com/2019/02/21/us/politics/trump-kim-north-korea.html',
    byline: 'By MARK LANDLER',
    item_type: 'Article',
    updated_date: '2019-02-21T20:07:18-05:00',
    created_date: '2019-02-21T20:07:18-05:00',
    published_date: '2019-02-21T20:07:18-05:00',
    material_type_facet: '',
    kicker: '',
    des_facet:
     [ 'United States International Relations',
       'United States Politics and Government',
       'United States Defense and Military Forces',
       'Nuclear Weapons' ],
    org_facet: [],
    per_facet: [ 'Trump, Donald J', 'Kim Jong-un' ],
    geo_facet: [ 'Vietnam', 'North Korea', 'United States' ],
    multimedia: [ [Object], [Object], [Object], [Object], [Object] ],
    short_url: 'https://nyti.ms/2NjpXJ7' },
  { section: 'U.S.',
    subsection: 'Politics',
    title: 'Roger Stone Placed Under Gag Order Over Instagram Post',
    abstract:
     'Mr. Stone, who had posted a photo of a federal judge that included cross hairs, was ordered by the same judge to stop making public comments about his case.',
    url:
     'https://www.nytimes.com/2019/02/21/us/politics/roger-stone-instagram-judge.html',
    byline: 'By SHARON LaFRANIERE',
    item_type: 'Article',
    updated_date: '2019-02-21T19:49:29-05:00',
    created_date: '2019-02-21T16:28:58-05:00',
    published_date: '2019-02-21T16:28:58-05:00',
    material_type_facet: '',
    kicker: '',
    des_facet:
     [ 'United States Politics and Government',
       'Presidential Election of 2016',
       'Social Media' ],
    org_facet: [ 'Instagram Inc', 'WikiLeaks' ],
    per_facet:
     [ 'Stone, Roger J Jr',
       'Trump, Donald J',
       'Mueller, Robert S III' ],
    geo_facet: [],
    multimedia: [ [Object], [Object], [Object], [Object], [Object] ],
    short_url: 'https://nyti.ms/2NlKfS8' },
  { section: 'U.S.',
    subsection: 'Politics',
    title:
     'Mueller Report Expected to Go to Justice Department Within Weeks',
    abstract:
     'The new attorney general, William Barr, is preparing to receive a report on the special counsel’s investigation. He will then have to decide how much of it to make public.',
    url:
     'https://www.nytimes.com/2019/02/21/us/politics/mueller-report-ending.html',
    byline: 'By KATIE BENNER',
    item_type: 'Article',
    updated_date: '2019-02-21T14:51:09-05:00',
    created_date: '2019-02-21T12:53:32-05:00',
    published_date: '2019-02-21T12:53:32-05:00',
    material_type_facet: '',
    kicker: '',
    des_facet:
     [ 'United States Politics and Government',
       'Russian Interference in 2016 US Elections and Ties to Trump Associates',
       'Presidential Election of 2016' ],
    org_facet: [ 'Justice Department' ],
    per_facet:
     [ 'Mueller, Robert S III', 'Trump, Donald J', 'Barr, William P' ],
    geo_facet: [ 'United States', 'Russia' ],
    multimedia: [ [Object], [Object], [Object], [Object], [Object] ],
    short_url: 'https://nyti.ms/2Nk5oMN' },
  { section: 'U.S.',
    subsection: 'Politics',
    title:
     'On Politics: Trump and Advisers May Have Different Goals for North Korea',
    abstract:
     'President Trump appears more interested, at least for now, in formally ending the Korean War than in hammering out a road map to denuclearization.',
    url:
     'https://www.nytimes.com/2019/02/22/us/politics/trump-north-korea.html',
    byline: '',
    item_type: 'Article',
    updated_date: '2019-02-22T05:43:44-05:00',
    created_date: '2019-02-22T05:43:44-05:00',
    published_date: '2019-02-22T05:43:44-05:00',
    material_type_facet: '',
    kicker: '',
    des_facet: [ 'United States Politics and Government' ],
    org_facet: [],
    per_facet: [],
    geo_facet: [],
    multimedia: [],
    short_url: 'https://nyti.ms/2Nnt1nr' },
  { section: 'World',
    subsection: 'Middle East',
    title:
     'White House Says 200 Troops Will Stay in Syria, Retreating From a Full Withdrawal',
    abstract:
     'The move was a concession to allies and Pentagon officials who have argued that a complete American withdrawal risks returning key areas in Syria to the Islamic State.',
    url:
     'https://www.nytimes.com/2019/02/21/world/middleeast/us-troops-syria-.html',
    byline: 'By ANNIE KARNI and THOMAS GIBBONS-NEFF',
    item_type: 'Article',
    updated_date: '2019-02-21T21:54:27-05:00',
    created_date: '2019-02-21T21:53:05-05:00',
    published_date: '2019-02-21T21:53:05-05:00',
    material_type_facet: '',
    kicker: '',
    des_facet:
     [ 'United States Defense and Military Forces',
       'United States International Relations',
       'United States Politics and Government' ],
    org_facet:
     [ 'Islamic State in Iraq and Syria (ISIS)',
       'Defense Department' ],
    per_facet:
     [ 'Graham, Lindsey',
       'Sanders, Sarah Huckabee',
       'Trump, Donald J' ],
    geo_facet: [ 'Syria' ],
    multimedia: [ [Object], [Object], [Object], [Object], [Object] ],
    short_url: 'https://nyti.ms/2GF472u' },
  { section: 'U.S.',
    subsection: 'Politics',
    title: 'On Politics With Lisa Lerer: A Chat With Dan Crenshaw',
    abstract:
     'Representative Dan Crenshaw, a former Navy SEAL with no prior experience in elected office, has emerged as one of the stars of the new Republican class.',
    url:
     'https://www.nytimes.com/2019/02/21/us/politics/on-politics-dan-crenshaw.html',
    byline: 'By LISA LERER',
    item_type: 'Article',
    updated_date: '2019-02-21T19:12:50-05:00',
    created_date: '2019-02-21T19:12:50-05:00',
    published_date: '2019-02-21T19:12:50-05:00',
    material_type_facet: '',
    kicker: '',
    des_facet:
     [ 'United States Politics and Government',
       'Illegal Immigration',
       'Shutdowns (Institutional)',
       'Presidential Election of 2020',
       'Rumors and Misinformation' ],
    org_facet: [ 'House of Representatives' ],
    per_facet: [ 'Crenshaw, Dan (1984- )', 'Sanders, Bernard' ],
    geo_facet: [],
    multimedia: [ [Object], [Object], [Object], [Object], [Object] ],
    short_url: 'https://nyti.ms/2NjaNUk' },
  { section: 'Climate',
    subsection: '',
    title:
     'Trump Administration, Getting Set for a Major Rollback, Ends Clean Air Talks With California',
    abstract:
     'The administration said it had decided to scrap negotiations over the president’s plan to undo Obama-era fuel efficiency standards.',
    url:
     'https://www.nytimes.com/2019/02/21/climate/california-tailpipe-emissions.html',
    byline: 'By LISA FRIEDMAN and HIROKO TABUCHI',
    item_type: 'Article',
    updated_date: '2019-02-21T18:46:23-05:00',
    created_date: '2019-02-21T18:36:55-05:00',
    published_date: '2019-02-21T18:36:55-05:00',
    material_type_facet: '',
    kicker: '',
    des_facet:
     [ 'Air Pollution',
       'Global Warming',
       'Carbon Dioxide',
       'Fuel Emissions (Transportation)',
       'United States Politics and Government' ],
    org_facet: [],
    per_facet: [ 'Trump, Donald J' ],
    geo_facet: [ 'California' ],
    multimedia: [ [Object], [Object], [Object], [Object], [Object] ],
    short_url: 'https://nyti.ms/2GEzKsD' },
  { section: 'Arts',
    subsection: 'Art & Design',
    title: 'A Victory for the Civil War ‘Cyclorama’',
    abstract:
     'A colossal painting, once claimed to depict a Confederate victory, has carried an evolving meaning. Now, a spectacular restoration at the Atlanta History Center unravels its complex tale.',
    url:
     'https://www.nytimes.com/2019/02/21/arts/design/confederate-monuments-cyclorama-atlanta.html',
    byline: 'By HOLLAND COTTER',
    item_type: 'Article',
    updated_date: '2019-02-21T17:38:51-05:00',
    created_date: '2019-02-21T17:38:51-05:00',
    published_date: '2019-02-21T17:38:51-05:00',
    material_type_facet: '',
    kicker: '',
    des_facet:
     [ 'Art',
       'Monuments and Memorials (Structures)',
       'Restoration and Renovation',
       'Civil War (US) (1861-65)' ],
    org_facet: [ 'Atlanta History Center' ],
    per_facet: [ 'Sheffield Hale' ],
    geo_facet: [ 'Atlanta (Ga)' ],
    multimedia: [ [Object], [Object], [Object], [Object], [Object] ],
    short_url: 'https://nyti.ms/2NjBQ1K' },
  { section: 'New York',
    subsection: '',
    title:
     'A Times Square Billboard Hits Ocasio-Cortez on Amazon. She Hits Back.',
    abstract:
     'A billboard blamed Representative Alexandria Ocasio-Cortez for Amazon’s decision to exit New York; she blamed wealthy right-wing types for the ad.',
    url:
     'https://www.nytimes.com/2019/02/21/nyregion/aoc-billboard-amazon.html',
    byline: 'By SHANE GOLDMACHER',
    item_type: 'Article',
    updated_date: '2019-02-21T23:46:27-05:00',
    created_date: '2019-02-21T16:32:44-05:00',
    published_date: '2019-02-21T16:32:44-05:00',
    material_type_facet: '',
    kicker: '',
    des_facet:
     [ 'United States Politics and Government',
       'Outdoor Advertising' ],
    org_facet: [ 'Job Creators Network' ],
    per_facet: [ 'Ocasio-Cortez, Alexandria' ],
    geo_facet:
     [ 'Times Square and 42nd Street (Manhattan, NY)',
       'New York City' ],
    multimedia: [ [Object], [Object], [Object], [Object], [Object] ],
    short_url: 'https://nyti.ms/2Niw2pn' },
  { section: 'U.S.',
    subsection: 'Politics',
    title:
     '2020 Democrats Embrace Race-Conscious Policies, Including Reparations',
    abstract:
     'The party has seen a shift toward idealistic and morally driven policies, particularly on the subjects of race and inequality.',
    url:
     'https://www.nytimes.com/2019/02/21/us/politics/2020-democrats-race-policy.html',
    byline: 'By ASTEAD W. HERNDON',
    item_type: 'Article',
    updated_date: '2019-02-21T20:23:18-05:00',
    created_date: '2019-02-21T13:43:38-05:00',
    published_date: '2019-02-21T13:43:38-05:00',
    material_type_facet: '',
    kicker: '',
    des_facet:
     [ 'Reparations',
       'Presidential Election of 2020',
       'Race and Ethnicity',
       'United States Politics and Government',
       'Blacks',
       'Income Inequality' ],
    org_facet: [],
    per_facet: [ 'Harris, Kamala D', 'Warren, Elizabeth' ],
    geo_facet: [],
    multimedia: [ [Object], [Object], [Object], [Object], [Object] ],
    short_url: 'https://nyti.ms/2NiWRth' },
  { section: 'U.S.',
    subsection: 'Politics',
    title:
     'Trump Claims His Wall Is Being Built. It’s Just a Replacement of Old Barriers.',
    abstract:
     'The president showcased a video of construction on Twitter, but the work he highlighted was from funds previously allocated to replace damaged fencing.',
    url:
     'https://www.nytimes.com/2019/02/21/us/politics/new-mexico-wall-fact-check.html',
    byline: 'By MICHAEL TACKETT',
    item_type: 'Article',
    updated_date: '2019-02-22T00:18:43-05:00',
    created_date: '2019-02-21T13:26:33-05:00',
    published_date: '2019-02-21T13:26:33-05:00',
    material_type_facet: '',
    kicker: '',
    des_facet:
     [ 'Border Barriers',
       'Rumors and Misinformation',
       'Immigration and Emigration',
       'Building (Construction)',
       'Illegal Immigration' ],
    org_facet: [ 'Customs and Border Protection (US)' ],
    per_facet: [ 'Trump, Donald J' ],
    geo_facet: [ 'New Mexico' ],
    multimedia: [ [Object], [Object], [Object], [Object], [Object] ],
    short_url: 'https://nyti.ms/2GI4Z6v' },
  { section: 'U.S.',
    subsection: 'Politics',
    title:
     'A Green New Deal Is Technologically Possible. Its Political Prospects Are Another Question.',
    abstract:
     'The technology is feasible for a Green New Deal, though experts doubt its goals could be accomplished as quickly as advocates hope. Finding money and political will is a bigger challenge.',
    url:
     'https://www.nytimes.com/2019/02/21/us/politics/green-new-deal.html',
    byline: 'By LISA FRIEDMAN and TRIP GABRIEL',
    item_type: 'Article',
    updated_date: '2019-02-21T17:25:01-05:00',
    created_date: '2019-02-21T10:35:45-05:00',
    published_date: '2019-02-21T10:35:45-05:00',
    material_type_facet: '',
    kicker: '',
    des_facet:
     [ 'Greenhouse Gas Emissions',
       'Green New Deal',
       'United States Economy',
       'Alternative and Renewable Energy' ],
    org_facet: [ 'Intergovernmental Panel on Climate Change' ],
    per_facet: [ 'Holdren, John P', 'Ocasio-Cortez, Alexandria' ],
    geo_facet: [],
    multimedia: [ [Object], [Object], [Object], [Object], [Object] ],
    short_url: 'https://nyti.ms/2GAYkL7' },
  { section: 'Climate',
    subsection: '',
    title: 'Nine Key Questions About the Green New Deal',
    abstract:
     'If you’ve heard a lot recently about the Green New Deal but still aren’t quite sure what it is, we’re here to help.',
    url:
     'https://www.nytimes.com/2019/02/21/climate/green-new-deal-questions-answers.html',
    byline: 'By LISA FRIEDMAN',
    item_type: 'Article',
    updated_date: '2019-02-21T17:22:06-05:00',
    created_date: '2019-02-21T09:29:14-05:00',
    published_date: '2019-02-21T09:29:14-05:00',
    material_type_facet: '',
    kicker: '',
    des_facet:
     [ 'Global Warming',
       'Environment',
       'Greenhouse Gas Emissions',
       'Carbon Dioxide',
       'Green New Deal' ],
    org_facet: [ 'House of Representatives', 'Senate' ],
    per_facet: [ 'Ocasio-Cortez, Alexandria', 'Markey, Edward J' ],
    geo_facet: [],
    multimedia: [ [Object], [Object], [Object], [Object], [Object] ],
    short_url: 'https://nyti.ms/2GCkHjg' },
  { section: 'New York',
    subsection: '',
    title: 'With 2020 in Sight, de Blasio Turns Against Amazon',
    abstract:
     'The mayor went from Amazon booster to critic when the company scuttled plans for a Queens campus; the shift may please progressives if he runs for president.',
    url:
     'https://www.nytimes.com/2019/02/21/nyregion/de-blasio-amazon-hq2.html',
    byline: 'By WILLIAM NEUMAN and J. DAVID GOODMAN',
    item_type: 'Article',
    updated_date: '2019-02-21T18:58:47-05:00',
    created_date: '2019-02-21T05:00:10-05:00',
    published_date: '2019-02-21T05:00:10-05:00',
    material_type_facet: '',
    kicker: '',
    des_facet:
     [ 'Presidential Election of 2020', 'Politics and Government' ],
    org_facet: [ 'Amazon.com Inc' ],
    per_facet: [ 'de Blasio, Bill' ],
    geo_facet: [ 'New York City' ],
    multimedia: [ [Object], [Object], [Object], [Object], [Object] ],
    short_url: 'https://nyti.ms/2Nh0obK' },
  { section: 'Theater',
    subsection: '',
    title: 'Hillary Clinton Lost. The Play Won.',
    abstract:
     'Lucas Hnath wrote “Hillary and Clinton” as the Democratic nomination slipped away from Mrs. Clinton. The 2016 election made it newly relevant.',
    url:
     'https://www.nytimes.com/2019/02/21/theater/hillary-and-clinton-broadway-lucas-hnath.html',
    byline: 'By LAURA COLLINS-HUGHES',
    item_type: 'Article',
    updated_date: '2019-02-21T04:00:05-05:00',
    created_date: '2019-02-21T04:00:05-05:00',
    published_date: '2019-02-21T04:00:05-05:00',
    material_type_facet: '',
    kicker: '',
    des_facet: [ 'Theater', 'Hillary and Clinton (Play)' ],
    org_facet:
     [ 'Cape Cod Theater Project',
       'Philadelphia Theater Company',
       'Victory Gardens Theater',
       'Golden Theater' ],
    per_facet:
     [ 'Hnath, Lucas',
       'Lithgow, John',
       'Mantello, Joe',
       'Metcalf, Laurie',
       'Yew, Chay' ],
    geo_facet: [],
    multimedia: [ [Object], [Object], [Object], [Object], [Object] ],
    short_url: 'https://nyti.ms/2GAkpJV' },
  { section: 'U.S.',
    subsection: 'Politics',
    title:
     'On Politics: A Climate Denialist on Trump’s Climate Change Panel',
    abstract:
     'William Happer, a physicist serving as the president’s deputy assistant for emerging technologies, has said that carbon dioxide is beneficial to humanity.',
    url:
     'https://www.nytimes.com/2019/02/20/us/politics/climate-change-panel-denialist.html',
    byline: '',
    item_type: 'Article',
    updated_date: '2019-02-21T03:09:59-05:00',
    created_date: '2019-02-20T23:57:59-05:00',
    published_date: '2019-02-20T23:57:59-05:00',
    material_type_facet: '',
    kicker: '',
    des_facet: [ 'United States Politics and Government' ],
    org_facet: [],
    per_facet: [],
    geo_facet: [],
    multimedia: [],
    short_url: 'https://nyti.ms/2NlCADK' },
  { section: 'U.S.',
    subsection: 'Politics',
    title:
     'Michael Cohen Agrees to Testify Next Week, Setting Stage for a High-Stakes Hearing',
    abstract:
     'The hearing before Congress will give Mr. Cohen, once one of President Trump’s most loyal aides, a rare public platform to explain his work for the president.',
    url:
     'https://www.nytimes.com/2019/02/20/us/politics/michael-cohen-testimony.html',
    byline: 'By NICHOLAS FANDOS',
    item_type: 'Article',
    updated_date: '2019-02-20T21:32:24-05:00',
    created_date: '2019-02-20T21:32:24-05:00',
    published_date: '2019-02-20T21:32:24-05:00',
    material_type_facet: '',
    kicker: '',
    des_facet:
     [ 'United States Politics and Government',
       'Conflicts of Interest',
       'Russian Interference in 2016 US Elections and Ties to Trump Associates',
       'Elections, House of Representatives' ],
    org_facet:
     [ 'Democratic Party',
       'House of Representatives',
       'Justice Department' ],
    per_facet:
     [ 'Trump, Donald J',
       'Mueller, Robert S III',
       'Davis, Lanny J',
       'Cohen, Michael D (1966- )' ],
    geo_facet: [],
    multimedia: [ [Object], [Object], [Object], [Object], [Object] ],
    short_url: 'https://nyti.ms/2GBvJW7' } ]