The New York Times Top Stories API

The Top Stories API returns an array of articles currently on the specified section (arts, business, health, home, etc.) of NYTimes.com. Use the home section to get articles currently on the homepage.

OpenAPI Specification

new-york-times-top-stories-openapi-original.yml Raw ↑
openapi: 3.0.1
info:
  title: The New York Times Top Stories
  description: |
    The Top Stories API returns an array of articles currently on the specified section (arts, business, ...).

    ```
    /{section}.json
    ```

    Use home to get articles currently on the homepage.

    ```
    /home.json
    ```

    The possible section value are: _arts, automobiles, books/review, business, fashion, food, health, home, insider, magazine, movies, nyregion, obituaries, opinion, politics, realestate, science, sports, sundayreview, technology, theater, t-magazine, travel, upshot, us, and world_.

    ## Example Calls
    ```
    https://api.nytimes.com/svc/topstories/v2/arts.json?api-key=yourkey
    https://api.nytimes.com/svc/topstories/v2/home.json?api-key=yourkey
    https://api.nytimes.com/svc/topstories/v2/science.json?api-key=yourkey
    https://api.nytimes.com/svc/topstories/v2/us.json?api-key=yourkey
    https://api.nytimes.com/svc/topstories/v2/world.json?api-key=yourkey
    ```
  version: 2.0.0
servers:
  - url: https://api.nytimes.com/svc/topstories/v2
security:
  - apikey: []
paths:
  /{section}.json:
    get:
      tags:
        - Stories
      summary: The New York Times Top Stories
      description: |
        The Top Stories API returns an array of articles currently on the specified section.
      parameters:
        - name: section
          in: path
          description: The section the story appears in.
          required: true
          schema:
            type: string
            default: home
            enum:
              - arts
              - automobiles
              - books/review
              - business
              - fashion
              - food
              - health
              - home
              - insider
              - magazine
              - movies
              - nyregion
              - obituaries
              - opinion
              - politics
              - realestate
              - science
              - sports
              - sundayreview
              - technology
              - theater
              - t-magazine
              - travel
              - upshot
              - us
              - world
      responses:
        "200":
          description: An array of articles.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  copyright:
                    type: string
                  section:
                    type: string
                  last_updated:
                    type: string
                  num_results:
                    type: integer
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Article'
        "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:
    Article:
      type: object
      properties:
        section:
          type: string
        subsection:
          type: string
        title:
          type: string
        abstract:
          type: string
        url:
          type: string
        uri:
          type: string
        byline:
          type: string
        item_type:
          type: string
        updated_date:
          type: string
        created_date:
          type: string
        published_date:
          type: string
        material_type_facet:
          type: string
        kicker:
          type: string
        des_facet:
          type: array
          items:
            type: string
        org_facet:
          type: array
          items:
            type: string
        per_facet:
          type: array
          items:
            type: string
        geo_facet:
          type: array
          items:
            type: string
        multimedia:
          type: array
          items:
            type: object
            properties:
              url:
                type: string
              format:
                type: string
              height:
                type: integer
              width:
                type: integer
              type:
                type: string
              subtype:
                type: string
              caption:
                type: string
              copyright:
                type: string
        short_url:
          type: string
  securitySchemes:
    apikey:
      type: apiKey
      name: api-key
      in: query
tags:
  - name: Stories