openapi: 3.0.0
servers:
  - url: http://api.nytimes.com/svc/search/v2
  - url: https://api.nytimes.com/svc/search/v2
info:
  description: |-
    With the Article Search API, you can search New York Times articles from Sept. 18, 1851 to today, retrieving headlines, abstracts, lead paragraphs, links to associated multimedia and other article metadata.  

     Note: In URI examples and field names, italics indicate placeholders for variables or values. Brackets [ ] indicate optional items. Parentheses ( ) are not a convention — when URIs include parentheses, interpret them literally.
  termsOfService: http://developer.nytimes.com/tou
  title: Article Search API
  version: 1.0.0
  x-apiClientRegistration:
    url: http://developer.nytimes.com/signup
  x-apisguru-categories:
    - media
    - open_data
  x-logo:
    url: 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/article_search/article_search_v2.json
      version: "3.0"
  x-providerName: nytimes.com
  x-serviceName: article_search
externalDocs:
  url: http://developer.nytimes.com/
security:
  - apikey: []
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. 

            The filter query can be specified with or without a limiting field: label. 

            See Filtering Your Search for more information about filtering."
          in: query
          name: fq
          required: false
          schema:
            type: string
        - description: |
            "Format: YYYYMMDD 

            Restricts responses to results with publication dates of the date specified or later."
          in: query
          name: begin_date
          required: false
          schema:
            type: string
        - description: |
            "Format: YYYYMMDD 

            Restricts responses to results with publication dates of the date specified or earlier."
          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)

              Limits the fields returned in your search results. By default (unless you include an fl list in your request), the following fields are returned: 
              
              web_url
              
              snippet
              
              lead_paragraph
              
              abstract
              
              print_page
              
              blog
              
              source
              
              multimedia
              
              headline
              
              keywords
              
              pub_date
              
              document_type
              
              news_desk
              
              byline
              
              type_of_material
              
              _id
              
              word_count"
          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: Article Search
      tags:
        - Stories
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
  securitySchemes:
    apikey:
      in: query
      name: api-key
      type: apiKey
