openapi: 3.0.0
servers:
  - url: http://api.nytimes.com/svc/mostpopular/v2
  - url: https://api.nytimes.com/svc/mostpopular/v2
info:
  description: Get lists of NYT Articles based on shares, emails, and views.
  termsOfService: http://developer.nytimes.com/tou
  title: Most Popular API
  version: 2.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/most_popular_api/most_popular_api_v2.json
      version: "3.0"
  x-providerName: nytimes.com
  x-serviceName: most_popular_api
externalDocs:
  url: http://developer.nytimes.com/
paths:
  "/mostemailed/{section}/{time-period}.json":
    get:
      description: ""
      operationId: GET_mostemailed-section-time-period-json
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  copyright:
                    type: string
                  num_results:
                    type: integer
                  results:
                    items:
                      $ref: "#/components/schemas/ArticleWithCountType"
                    type: array
                  status:
                    type: string
                type: object
            application/xml:
              schema:
                properties:
                  copyright:
                    type: string
                  num_results:
                    type: integer
                  results:
                    items:
                      $ref: "#/components/schemas/ArticleWithCountType"
                    type: array
                  status:
                    type: string
                type: object
          description: An array of Articles
        "400":
          content:
            application/json:
              examples:
                response:
                  value:
                    copyright: Copyright (c) 2016 The New York Times Company.  All Rights Reserved.
                    errors:
                      - Param 'period' is invalid.
                    results: []
                    status: ERROR
              schema:
                properties:
                  copyright:
                    type: string
                  errors:
                    items:
                      type: string
                    type: array
                  results:
                    items: {}
                    type: array
                  status:
                    type: string
                type: object
            application/xml:
              schema:
                properties:
                  copyright:
                    type: string
                  errors:
                    items:
                      type: string
                    type: array
                  results:
                    items: {}
                    type: array
                  status:
                    type: string
                type: object
          description: ""
        "403":
          content:
            application/json:
              schema:
                type: object
            application/xml:
              examples:
                response:
                  value: <h1>Developer Over Qps</h1>
              schema:
                type: object
          description: ""
      security:
        - api-key: []
      summary: Most Emailed by Section & Time Period
    parameters:
      - $ref: "#/components/parameters/Section"
      - $ref: "#/components/parameters/TimePeriod"
  "/mostshared/{section}/{time-period}.json":
    get:
      description: ""
      operationId: GET_mostshared-section-time-period-json
      responses:
        "200":
          content:
            application/json:
              examples:
                response:
                  value:
                    copyright: Copyright (c) 2016 The New York Times Company.  All Rights Reserved.
                    num_results: 24
                    results:
                      - abstract: Timothy D. Cook, Apple’s chief, said the government’s request to bypass security on the phone used by Syed Rizwan Farook had “chilling” implications.
                        asset_id: 100000004214575
                        byline: By ERIC LICHTBLAU and KATIE BENNER
                        column: ""
                        des_facet:
                          - IPHONE
                        geo_facet: ""
                        media:
                          - caption: Timothy D. Cook, the chief executive of Apple, released a letter to customers several hours after a California judge ordered the company to unlock an iPhone used by one of the shooters in a recent attack that killed 14 people in San Bernardino.
                            copyright: Jeff Chiu/Associated Press
                            media-metadata:
                              - format: Standard Thumbnail
                                height: 75
                                url: http://static01.nyt.com/images/2016/02/18/world/18Appleletter-web/18Appleletter-web-thumbStandard.jpg
                                width: 75
                            subtype: photo
                            type: image
                        org_facet:
                          - APPLE INC
                        per_facet:
                          - COOK, TIMOTHY D
                        published_date: 2016-02-18
                        section: Technology
                        source: The New York Times
                        title: Apple Fights Order to Unlock San Bernardino Gunman’s iPhone
                        total_shares: 1
                        url: http://www.nytimes.com/2016/02/18/technology/apple-timothy-cook-fbi-san-bernardino.html
                    status: OK
              schema:
                properties:
                  copyright:
                    type: string
                  num_results:
                    type: integer
                  results:
                    items:
                      $ref: "#/components/schemas/Article"
                    type: array
                  status:
                    type: string
                type: object
          description: An array of Articles
        "400":
          content:
            application/json:
              examples:
                response:
                  value:
                    copyright: Copyright (c) 2016 The New York Times Company.  All Rights Reserved.
                    errors:
                      - "Please specify a supported period, options are: 1,7,30"
                    results: []
                    status: ERROR
              schema:
                properties:
                  copyright:
                    type: string
                  errors:
                    items:
                      type: string
                    type: array
                  results:
                    items: {}
                    type: array
                  status:
                    type: string
                type: object
          description: ""
      security:
        - api-key: []
      summary: Most Shared by Section & Time Period
    parameters:
      - $ref: "#/components/parameters/Section"
      - $ref: "#/components/parameters/TimePeriod"
  "/mostviewed/{section}/{time-period}.json":
    get:
      description: ""
      operationId: GET_mostviewed-section-time-period-json
      responses:
        "200":
          content:
            application/json:
              examples:
                response:
                  value:
                    copyright: Copyright (c) 2016 The New York Times Company.  All Rights Reserved.
                    num_results: 121
                    results:
                      - abstract: Republicans have parked themselves so far to the right for so many years that it’s not clear if they can hear how deranged they sound.
                        adx_keywords: Supreme Court (US);McConnell, Mitch;Scalia, Antonin;Obama, Barack;Kirk, Mark Steven;Republican Party;Senate;Cornyn, John;Collins, Susan M
                        asset_id: 100000004229487
                        byline: By THE EDITORIAL BOARD
                        column: Editorial
                        des_facet: ""
                        geo_facet: ""
                        id: 100000004229487
                        media: ""
                        org_facet:
                          - SUPREME COURT (US)
                        per_facet:
                          - MCCONNELL, MITCH
                        published_date: 2016-02-25
                        section: Opinion
                        source: The New York Times
                        title: Senate Republicans Lose Their Minds on a Supreme Court Seat
                        type: Article
                        url: http://www.nytimes.com/2016/02/25/opinion/senate-republicans-lose-their-minds-on-a-supreme-court-seat.html
                        views: 1
                    status: OK
              schema:
                properties:
                  copyright:
                    type: string
                  num_results:
                    type: integer
                  results:
                    items:
                      $ref: "#/components/schemas/Article"
                    type: array
                  status:
                    type: string
                type: object
          description: An array of Articles
      security:
        - api-key: []
      summary: Most Viewed by Section & Time Period
    parameters:
      - $ref: "#/components/parameters/Section"
      - $ref: "#/components/parameters/TimePeriod"
components:
  parameters:
    OffSet:
      description: Positive integer in a multiple of 20
      in: query
      name: offset
      schema:
        default: 20
        type: integer
    Section:
      description: |
        Limits the results by one or more sections. You can use
        `all-sections` or one or more section names seperated by semicolons. See `viewed/sections.json` call to get a list of sections. 
      in: path
      name: section
      required: true
      schema:
        enum:
          - Arts
          - Automobiles
          - Blogs
          - Books
          - Business Day
          - Education
          - Fashion & Style
          - Food
          - Health
          - Job Market
          - Magazine
          - membercenter
          - Movies
          - Multimedia
          - N.Y.%20%2F%20Region
          - NYT Now
          - Obituaries
          - Open
          - Opinion
          - Public Editor
          - Real Estate
          - Science
          - Sports
          - Style
          - Sunday Review
          - T Magazine
          - Technology
          - The Upshot
          - Theater
          - Times Insider
          - Today’s Paper
          - Travel
          - U.S.
          - World
          - Your Money
          - all-sections
        type: string
    SharedTypes:
      description: Limits the results by the method used to share the items only works on mostshared requests.
      in: query
      name: shared-types
      schema:
        enum:
          - digg
          - email
          - facebook
          - mixx
          - myspace
          - permalink
          - timespeople
          - twitter
          - yahoobuzz
        type: string
    TimePeriod:
      description: Number of days `1 | 7 | 30 ` corresponds to a day, a week, or a month of content.
      in: path
      name: time-period
      required: true
      schema:
        enum:
          - "1"
          - "7"
          - "30"
        type: string
  schemas:
    Article:
      properties:
        abstract:
          type: string
        byline:
          type: string
        column:
          type: string
        des_facet:
          $ref: "#/components/schemas/DesFacet"
        geo_facet:
          $ref: "#/components/schemas/GeoFacet"
        media:
          items: {}
          oneOf:
            - items: {}
              type: array
            - type: string
        org_facet:
          $ref: "#/components/schemas/OrgFacet"
        per_facet:
          $ref: "#/components/schemas/PerFacet"
        published_date:
          type: string
        section:
          type: string
        source:
          type: string
        title:
          type: string
        url:
          type: string
      type: object
    ArticleWithCountType:
      properties:
        abstract:
          type: string
        byline:
          type: string
        column:
          type: string
        count_type:
          type: string
        des_facet:
          $ref: "#/components/schemas/DesFacet"
        geo_facet:
          $ref: "#/components/schemas/GeoFacet"
        media:
          items:
            properties:
              caption:
                type: string
              copyright:
                type: string
              media-metadata:
                properties:
                  format:
                    type: string
                  height:
                    type: integer
                  url:
                    type: string
                  width:
                    type: integer
                type: object
              subtype:
                type: string
              type:
                type: string
            type: object
          type: array
          x-runscope/nullable: true
          x-runscope/nullable/value: "''"
        org_facet:
          $ref: "#/components/schemas/OrgFacet"
        per_facet:
          $ref: "#/components/schemas/PerFacet"
        published_date:
          type: string
        section:
          type: string
        source:
          type: string
        title:
          type: string
        url:
          type: string
      type: object
    DesFacet:
      items: {}
      oneOf:
        - items: {}
          type: array
        - type: string
    GeoFacet:
      enum:
        - ""
      items: {}
      nullable: true
      oneOf:
        - items: {}
          type: array
        - type: string
    OrgFacet:
      items: {}
      nullable: true
      type: array
    PerFacet:
      items: {}
      nullable: true
      type: array
  securitySchemes:
    api-key:
      in: query
      name: api-key
      type: apiKey