The New York Times Stories API

openapi: 3.0.0
info:
  description: The Archive API provides lists of NYT articles by month going back to 1851.  You can use it to build your own local database of NYT article metadata.
  termsOfService: http://developer.nytimes.com/tou
  title: The New York Times Archive Stories API
  version: 1.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/archive_api/archive_api.json
    version: '3.0'
  x-providerName: nytimes.com
  x-serviceName: archive
servers:
- url: http://api.nytimes.com/svc/archive/v1
- url: https://api.nytimes.com/svc/archive/v1
security:
- apikey: []
tags:
- name: Stories
paths:
  /articlesearch.json:
    get:
      description: 'Article Search requests use the following URI structure:

        '
      parameters:
      - description: 'Search query term. Search is performed on the article body, headline and byline.

          '
        in: query
        name: q
        required: false
        schema:
          type: string
      - description: "\"Filtered search query using standard Lucene syntax. \n\nThe filter query can be specified with or without a limiting field: label. \n\nSee Filtering Your Search for more information about filtering.\"\n"
        in: query
        name: fq
        required: false
        schema:
          type: string
      - description: "\"Format: YYYYMMDD \n\nRestricts responses to results with publication dates of the date specified or later.\"\n"
        in: query
        name: begin_date
        required: false
        schema:
          type: string
      - description: "\"Format: YYYYMMDD \n\nRestricts responses to results with publication dates of the date specified or earlier.\"\n"
        in: query
        name: end_date
        required: false
        schema:
          type: string
      - description: '"By default, search results are sorted by their relevance to the query term (q). Use the sort parameter to sort by pub_date."

          '
        in: query
        name: sort
        required: false
        schema:
          enum:
          - newest
          - oldest
          type: string
      - description: "\"Comma-delimited list of fields (no limit)\n\n  Limits the fields returned in your search results. By default (unless you include an fl list in your request), the following fields are returned: \n  \n  web_url\n  \n  snippet\n  \n  lead_paragraph\n  \n  abstract\n  \n  print_page\n  \n  blog\n  \n  source\n  \n  multimedia\n  \n  headline\n  \n  keywords\n  \n  pub_date\n  \n  document_type\n  \n  news_desk\n  \n  byline\n  \n  type_of_material\n  \n  _id\n  \n  word_count\"\n"
        in: query
        name: fl
        required: false
        schema:
          type: string
      - description: 'Enables highlighting in search results. When set to true, the query term (q) is highlighted in the headline and lead_paragraph fields.


          Note: If highlighting is enabled, snippet will be returned even if it is not specified in your fl list."

          '
        in: query
        name: hl
        required: false
        schema:
          default: false
          type: boolean
      - description: '"The value of page corresponds to a set of 10 results (it does not indicate the starting number of the result set). For example, page=0 corresponds to records 0-9. To return records 10-19, set page to 1, not 10."

          '
        in: query
        name: page
        required: false
        schema:
          default: 0
          maximum: 10
          minimum: 0
          type: integer
      - description: 'Comma-delimited list of facets


          Specifies the sets of facet values to include in the facets array at the end of response, which collects the facet values from all the search results. By default no facet fields will be returned. Below is the list of valid facets:


          section_name


          document_type


          type_of_material


          source


          day_of_week


          To learn more about using facets, see Using Facets.

          '
        in: query
        name: facet_field
        required: false
        schema:
          type: string
      - description: 'When set to true, facet counts will respect any applied filters (fq, date range, etc.) in addition to the main query term. To filter facet counts, specifying at least one facet_field is required. To learn more about using facets, see Using Facets.

          '
        in: query
        name: facet_filter
        required: false
        schema:
          default: false
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  response:
                    properties:
                      docs:
                        items:
                          $ref: '#/components/schemas/Doc'
                        type: array
                      meta:
                        properties:
                          hits:
                            type: integer
                          offset:
                            type: integer
                          time:
                            type: integer
                        type: object
                    type: object
                type: object
          description: The docs requested by the article search.
      summary: The New York Times Article Search
      tags:
      - Stories
  /{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:
    Doc:
      properties:
        _id:
          type: string
        abstract:
          type: string
        blog:
          items: {}
          type: array
        byline:
          properties:
            organization:
              type: string
            original:
              type: string
            person:
              items: {}
              type: array
          type: object
        document_type:
          type: string
        headline:
          properties:
            kicker:
              type: string
            main:
              type: string
          type: object
        keywords:
          properties:
            name:
              type: string
            rank:
              type: string
            value:
              type: string
          type: object
        lead_paragraph:
          type: string
        multimedia:
          items:
            properties:
              caption:
                type: string
              copyright:
                type: string
              format:
                type: string
              height:
                type: integer
              subtype:
                type: string
              type:
                type: string
              url:
                type: string
              width:
                type: integer
            type: object
          type: array
        news_desk:
          type: string
        print_page:
          type: string
        pub_date:
          type: string
        section_name:
          type: string
        slideshow_credits:
          type: string
        snippet:
          type: string
        source:
          type: string
        subsection_name:
          type: string
        type_of_material:
          type: string
        web_url:
          type: string
        word_count:
          type: string
      type: object
    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:
      in: query
      name: api-key
      type: apiKey
externalDocs:
  url: http://developer.nytimes.com/