spec.yaml

swagger: "2.0"
basePath: /svc/mostpopular/v2
host: api.nytimes.com
schemes:
  - https
info:
  version: 2.0.0
  title: Most Popular
  description: |
    Provides services for getting the most popular articles on NYTimes.com based on emails, shares, or views.

    Get most emailed articles for the last day:
    ```
    /emailed/1.json
    ```

    Get most shared articles on Facebook for the last day:
    ```
    /shared/1/facebook.json
    ```

    Get most viewed articles for the last seven days:
    ```
    /viewed/7.json
    ```

    ## Example Calls
    ```
    https://api.nytimes.com/svc/mostpopular/v2/emailed/7.json?api-key=yourkey
    ```

    ```
    https://api.nytimes.com/svc/mostpopular/v2/shared/1/facebook.json?api-key=yourkey
    ```

    ```
    https://api.nytimes.com/svc/mostpopular/v2/viewed/1.json?api-key=yourkey
    ```
produces:
  - application/json
security:
  - apikey: []
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
                description: API response status (e.g. OK).
              copyright:
                type: string
                description: Copyright message.
              num_results:
                type: integer
                description: Number of articles in the results (e.g. 20).
              results:
                type: array
                items:
                  $ref: "#/definitions/EmailedArticle"
                description: Array of articles.
        "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
                description: API response status (e.g. OK).
              copyright:
                type: string
                description: Copyright message.
              num_results:
                type: integer
                description: Number of articles in the results (e.g. 20).
              results:
                type: array
                items:
                  $ref: "#/definitions/SharedArticle"
                description: Array of articles.
        "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: facebook."
          required: true
          type: string
          enum:
            - facebook
          default: facebook
      tags:
        - Most Popular
      responses:
        "200":
          description: An array of articles.
          schema:
            type: object
            properties:
              status:
                type: string
                description: API response status (e.g. OK).
              copyright:
                type: string
                description: Copyright message.
              num_results:
                type: integer
                description: Number of articles in the results (e.g. 20).
              results:
                type: array
                items:
                  $ref: "#/definitions/SharedArticle"
                description: Array of articles.
        "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
                description: API response status (e.g. OK).
              copyright:
                type: string
                description: Copyright message.
              num_results:
                type: integer
                description: Number of articles in the results (e.g. 20).
              results:
                type: array
                items:
                  $ref: "#/definitions/ViewedArticle"
                description: Array of articles.
        "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
        description: Article's URL.
      adx_keywords:
        type: string
        description: Semicolon separated list of keywords.
      subsection:
        type: string
        description: Article's subsection (e.g. Politics). Can be empty string.
      column:
        type: string
        description: Deprecated. Set to null.
      eta_id:
        type: integer
        description: Deprecated. Set to 0.
      section:
        type: string
        description: Article's section (e.g. Sports).
      id:
        type: integer
        description: Asset ID number (e.g. 100000007772696).
      asset_id:
        type: integer
        description: Asset ID number (e.g. 100000007772696).
      nytdsection:
        type: string
        description: Article's section (e.g. sports).
      byline:
        type: string
        description: Article's byline (e.g. By Thomas L. Friedman).
      type:
        type: string
        description: Asset type (e.g. Article, Interactive, ...).
      title:
        type: string
        description: Article's headline (e.g. When the Cellos Play, the Cows Come Home).
      abstract:
        type: string
        description: Brief summary of the article.
      published_date:
        type: string
        description: When the article was published on the web (e.g. 2021-04-19).
      source:
        type: string
        description: Publisher (e.g. New York Times).
      updated:
        type: string
        description: When the article was last updated (e.g. 2021-05-12 06:32:03).
      des_facet:
        type: array
        items:
          type: string
        description: Array of description facets (e.g. Quarantine (Life and Culture)).
      org_facet:
        type: array
        items:
          type: string
        description: Array of organization facets (e.g. Sullivan Street Bakery).
      per_facet:
        type: array
        items:
          type: string
        description: Array of person facets (e.g. Bittman, Mark).
      geo_facet:
        type: array
        items:
          type: string
        description: Array of geographic facets (e.g. Canada).
      media:
        type: array
        items:
          $ref: "#/definitions/Media"
        description: Array of images.
      uri:
        type: string
        description: An article's globally unique identifier.
  Media:
    type: object
    properties:
      type:
        type: string
        description: Asset type (e.g. image).
      subtype:
        type: string
        description: Asset subtype (e.g. photo).
      caption:
        type: string
        description: Media caption.
      copyright:
        type: string
        description: Media credit.
      approved_for_syndication:
        type: boolean
        description: Whether media is approved for syndication.
      media-metadata:
        type: array
        items:
          $ref: "#/definitions/MediaMetadata"
        description: Media metadata (url, width, height, ...).
  MediaMetadata:
    type: object
    properties:
      url:
        type: string
        description: Image's URL.
      format:
        type: string
        description: Image's crop name.
      height:
        type: integer
        description: Image's height (e.g. 293).
      width:
        type: integer
        description: Image's width (e.g. 440).
  SharedArticle:
    type: object
    properties:
      url:
        type: string
        description: Article's URL.
      adx_keywords:
        type: string
        description: Semicolon separated list of keywords.
      subsection:
        type: string
        description: Article's subsection (e.g. Politics). Can be empty string.
      column:
        type: string
        description: Deprecated. Set to null.
      eta_id:
        type: integer
        description: Deprecated. Set to 0.
      section:
        type: string
        description: Article's section (e.g. Sports).
      id:
        type: integer
        description: Asset ID number (e.g. 100000007772696).
      asset_id:
        type: integer
        description: Asset ID number (e.g. 100000007772696).
      nytdsection:
        type: string
        description: Article's section (e.g. sports).
      byline:
        type: string
        description: Article's byline (e.g. By Thomas L. Friedman).
      type:
        type: string
        description: Asset type (e.g. Article, Interactive, ...).
      title:
        type: string
        description: Article's headline (e.g. When the Cellos Play, the Cows Come Home).
      abstract:
        type: string
        description: Brief summary of the article.
      published_date:
        type: string
        description: When the article was published on the web (e.g. 2021-04-19).
      source:
        type: string
        description: Publisher (e.g. New York Times).
      updated:
        type: string
        description: When the article was last updated (e.g. 2021-05-12 06:32:03).
      des_facet:
        type: array
        items:
          type: string
        description: Array of description facets (e.g. Quarantine (Life and Culture)).
      org_facet:
        type: array
        items:
          type: string
        description: Array of organization facets (e.g. Sullivan Street Bakery).
      per_facet:
        type: array
        items:
          type: string
        description: Array of person facets (e.g. Bittman, Mark).
      geo_facet:
        type: array
        items:
          type: string
        description: Array of geographic facets (e.g. Canada).
      media:
        type: array
        items:
          $ref: "#/definitions/Media"
        description: Array of images.
      uri:
        type: string
        description: An article's globally unique identifier.
  ViewedArticle:
    type: object
    properties:
      url:
        type: string
        description: Article's URL.
      adx_keywords:
        type: string
        description: Semicolon separated list of keywords.
      column:
        type: string
        description: Deprecated. Set to null.
      section:
        type: string
        description: Article's section (e.g. Sports).
      byline:
        type: string
        description: Article's byline (e.g. By Thomas L. Friedman).
      type:
        type: string
        description: Asset type (e.g. Article, Interactive, ...).
      title:
        type: string
        description: Article's headline (e.g. When the Cellos Play, the Cows Come Home).
      abstract:
        type: string
        description: Brief summary of the article.
      published_date:
        type: string
        description: When the article was published on the web (e.g. 2021-04-19).
      source:
        type: string
        description: Publisher (e.g. New York Times).
      id:
        type: integer
        description: Asset ID number (e.g. 100000007772696).
      asset_id:
        type: integer
        description: Asset ID number (e.g. 100000007772696).
      des_facet:
        type: array
        items:
          type: string
        description: Array of description facets (e.g. Quarantine (Life and Culture)).
      org_facet:
        type: array
        items:
          type: string
        description: Array of organization facets (e.g. Sullivan Street Bakery).
      per_facet:
        type: array
        items:
          type: string
        description: Array of person facets (e.g. Bittman, Mark).
      geo_facet:
        type: array
        items:
          type: string
        description: Array of geographic facets (e.g. Canada).
      media:
        type: array
        items:
          $ref: "#/definitions/Media"
        description: Array of images.
      uri:
        type: string
        description: An article's globally unique identifier.
securityDefinitions:
  apikey:
    type: apiKey
    name: api-key
    in: query
    description: API key