The New York Times Company

The New York Times Company Stories API

The Stories API from The New York Times Company — 1 operation(s) for stories.

Documentation GitHub OpenAPI

Documentation

https://developer.nytimes.com/docs/articlesearch-product/1/overview

https://developer.nytimes.com/docs/top-stories-product/1/overview

https://developer.nytimes.com/docs/most-popular-product/1/overview

https://developer.nytimes.com/docs/timeswire-product/1/overview

https://developer.nytimes.com/docs/archive-product/1/overview

https://developer.nytimes.com/docs/books-product/1/overview

https://developer.nytimes.com/docs/movie-reviews-api/1/overview

https://developer.nytimes.com/docs/timestags-product/1/overview

https://developer.nytimes.com/docs/semantic-api-product/1/overview

https://developer.nytimes.com/docs/geo-product/1/overview

https://developer.nytimes.com/docs/community-api-product/1/overview

Specifications

https://raw.githubusercontent.com/api-evangelist/new-york-times-company/refs/heads/main/openapi/new-york-times-company-stories-api-openapi.yml

Schemas & Data

https://raw.githubusercontent.com/api-evangelist/new-york-times-company/refs/heads/main/json-schema/article-schema.json

https://raw.githubusercontent.com/api-evangelist/new-york-times-company/refs/heads/main/json-schema/best-seller-book-schema.json

https://raw.githubusercontent.com/api-evangelist/new-york-times-company/refs/heads/main/json-schema/movie-review-schema.json

https://raw.githubusercontent.com/api-evangelist/new-york-times-company/refs/heads/main/json-schema/tag-schema.json

https://raw.githubusercontent.com/api-evangelist/new-york-times-company/refs/heads/main/json-schema/concept-schema.json

Other Resources

https://raw.githubusercontent.com/api-evangelist/new-york-times-company/refs/heads/main/examples/article-search-example.json

https://developer.nytimes.com/accounts/create

https://raw.githubusercontent.com/api-evangelist/new-york-times-company/refs/heads/main/examples/top-stories-home-example.json

https://raw.githubusercontent.com/api-evangelist/new-york-times-company/refs/heads/main/examples/most-popular-emailed-example.json

https://raw.githubusercontent.com/api-evangelist/new-york-times-company/refs/heads/main/examples/timeswire-content-example.json

https://raw.githubusercontent.com/api-evangelist/new-york-times-company/refs/heads/main/examples/archive-month-example.json

https://raw.githubusercontent.com/api-evangelist/new-york-times-company/refs/heads/main/examples/books-best-sellers-list-example.json

https://raw.githubusercontent.com/api-evangelist/new-york-times-company/refs/heads/main/examples/movie-reviews-search-example.json

https://raw.githubusercontent.com/api-evangelist/new-york-times-company/refs/heads/main/examples/times-tags-example.json

https://raw.githubusercontent.com/api-evangelist/new-york-times-company/refs/heads/main/examples/semantic-concept-example.json

https://raw.githubusercontent.com/api-evangelist/new-york-times-company/refs/heads/main/examples/geo-query-example.json

https://raw.githubusercontent.com/api-evangelist/new-york-times-company/refs/heads/main/examples/community-comments-example.json

https://developer.nytimes.com/docs/community-api-product/1/overview

OpenAPI Specification

swagger: '2.0'
info:
  version: 2.0.0
  title: Archive Stories API
  description: 'The Archive API returns an array of NYT articles for a given month, going back to 1851.  Its response fields are the same as the Article Search API. The Archive API is very useful if you want to build your own database of NYT article metadata. You simply pass the API the year and month and it returns a JSON object with all articles for that month.  The response size can be large (~20mb).


    ```

    /{year}/{month}.json

    ```


    ## Example Call

    ```

    https://api.nytimes.com/svc/archive/v1/2019/1.json?api-key=yourkey

    ```

    '
host: api.nytimes.com
basePath: /svc/archive/v1
schemes:
- https
produces:
- application/json
security:
- apikey: []
tags:
- name: Stories
paths:
  /{section}.json:
    get:
      summary: 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
        type: string
        default: home
        enum:
        - arts
        - automobiles
        - books
        - business
        - fashion
        - food
        - health
        - home
        - insider
        - magazine
        - movies
        - national
        - nyregion
        - obituaries
        - opinion
        - politics
        - realestate
        - science
        - sports
        - sundayreview
        - technology
        - theater
        - tmagazine
        - travel
        - upshot
        - world
      tags:
      - Stories
      responses:
        '200':
          description: An array of articles.
          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: '#/definitions/Article'
        '401':
          description: Unauthorized request.  Make sure api-key is set.
        '429':
          description: Too many requests.  You reached your per minute or per day rate limit.
definitions:
  Article:
    type: object
    properties:
      section:
        type: string
      subsection:
        type: string
      title:
        type: string
      abstract:
        type: string
      url:
        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
securityDefinitions:
  apikey:
    type: apiKey
    name: api-key
    in: query