swagger: '2.0'
info:
  version: 2.0.0
  title: Archive Most Popular 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: Most Popular
paths:
  /emailed/{period}.json:
    get:
      summary: Most emailed articles on NYTimes.com.
      description: 'Returns an array of the most emailed articles on NYTimes.com for specified period of time (1 day, 7 days, or 30 days).

        '
      parameters:
      - name: period
        in: path
        description: 'Time period: 1, 7, or 30 days.'
        required: true
        type: integer
        enum:
        - 1
        - 7
        - 30
        default: 1
      tags:
      - Most Popular
      responses:
        '200':
          description: An array of articles.
          schema:
            type: object
            properties:
              status:
                type: string
              copyright:
                type: string
              num_results:
                type: integer
              results:
                type: array
                items:
                  $ref: '#/definitions/EmailedArticle'
        '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.
  /shared/{period}.json:
    get:
      summary: Most shared articles on NYTimes.com.
      description: 'Returns an array of the most shared articles on NYTimes.com for specified period of time (1 day, 7 days, or 30 days).

        '
      parameters:
      - name: period
        in: path
        description: 'Time period: 1, 7, or 30 days.'
        required: true
        type: integer
        enum:
        - 1
        - 7
        - 30
        default: 1
      tags:
      - Most Popular
      responses:
        '200':
          description: An array of articles.
          schema:
            type: object
            properties:
              status:
                type: string
              copyright:
                type: string
              num_results:
                type: integer
              results:
                type: array
                items:
                  $ref: '#/definitions/SharedArticle'
        '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.
  /shared/{period}/{share_type}.json:
    get:
      summary: Most shared articles on NYTimes.com of specified share type.
      description: 'Returns an array of the most shared articles by share type on NYTimes.com for specified period of time (1 day, 7 days, or 30 days).

        '
      parameters:
      - name: period
        in: path
        description: 'Time period: 1, 7, or 30 days.'
        required: true
        type: integer
        enum:
        - 1
        - 7
        - 30
        default: 1
      - name: share_type
        in: path
        description: 'Share type: email, facebook, or twitter.'
        required: true
        type: string
        enum:
        - email
        - facebook
        - twitter
        default: facebook
      tags:
      - Most Popular
      responses:
        '200':
          description: An array of articles.
          schema:
            type: object
            properties:
              status:
                type: string
              copyright:
                type: string
              num_results:
                type: integer
              results:
                type: array
                items:
                  $ref: '#/definitions/SharedArticle'
        '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.
  /viewed/{period}.json:
    get:
      summary: Most viewed articles on NYTimes.com.
      description: 'Returns an array of the most viewed articles on NYTimes.com for specified period of time (1 day, 7 days, or 30 days).

        '
      parameters:
      - name: period
        in: path
        description: 'Time period: 1, 7, or 30 days.'
        required: true
        type: integer
        enum:
        - 1
        - 7
        - 30
        default: 1
      tags:
      - Most Popular
      responses:
        '200':
          description: An array of articles.
          schema:
            type: object
            properties:
              status:
                type: string
              copyright:
                type: string
              num_results:
                type: integer
              results:
                type: array
                items:
                  $ref: '#/definitions/ViewedArticle'
        '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:
  EmailedArticle:
    type: object
    properties:
      url:
        type: string
      adx_keywords:
        type: string
      subsection:
        type: string
      email_count:
        type: integer
      count_type:
        type: string
      column:
        type: string
      eta_id:
        type: integer
      section:
        type: string
      id:
        type: integer
      asset_id:
        type: integer
      nytdsection:
        type: string
      byline:
        type: string
      type:
        type: string
      title:
        type: string
      abstract:
        type: string
      published_date:
        type: string
      source:
        type: string
      updated:
        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
      media:
        type: array
        items:
          $ref: '#/definitions/Media'
      uri:
        type: string
  SharedArticle:
    type: object
    properties:
      url:
        type: string
      adx_keywords:
        type: string
      subsection:
        type: string
      share_count:
        type: integer
      count_type:
        type: string
      column:
        type: string
      eta_id:
        type: integer
      section:
        type: string
      id:
        type: integer
      asset_id:
        type: integer
      nytdsection:
        type: string
      byline:
        type: string
      type:
        type: string
      title:
        type: string
      abstract:
        type: string
      published_date:
        type: string
      source:
        type: string
      updated:
        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
      media:
        type: array
        items:
          $ref: '#/definitions/Media'
      uri:
        type: string
  ViewedArticle:
    type: object
    properties:
      url:
        type: string
      adx_keywords:
        type: string
      column:
        type: string
      section:
        type: string
      byline:
        type: string
      type:
        type: string
      title:
        type: string
      abstract:
        type: string
      published_date:
        type: string
      source:
        type: string
      id:
        type: integer
      asset_id:
        type: integer
      views:
        type: integer
      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
      media:
        type: array
        items:
          $ref: '#/definitions/Media'
      uri:
        type: string
  MediaMetadata:
    type: object
    properties:
      url:
        type: string
      format:
        type: string
      height:
        type: integer
      width:
        type: integer
  Media:
    type: object
    properties:
      type:
        type: string
      subtype:
        type: string
      caption:
        type: string
      copyright:
        type: string
      approved_for_syndication:
        type: boolean
      media-metadata:
        type: array
        items:
          $ref: '#/definitions/MediaMetadata'
securityDefinitions:
  apikey:
    type: apiKey
    name: api-key
    in: query