openapi: 3.0.3
info:
  title: METACRAN CranLogs API
  description: >-
    REST API providing download statistics for R packages from the RStudio CRAN
    mirror. Supports per-package and top-package download counts across daily,
    weekly, monthly, and all-time periods. Returns JSON responses.
  version: 1.0.0
  contact:
    name: METACRAN
    url: https://r-pkg.org
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: https://cranlogs.r-pkg.org
    description: METACRAN CranLogs production server
tags:
  - name: Downloads
    description: Package download statistics
  - name: Top Packages
    description: Most-downloaded CRAN packages
  - name: Badges
    description: Download count badge endpoints
paths:
  /downloads/total/{period}/{packages}:
    get:
      operationId: getPackageDownloadTotals
      summary: Get Package Download Totals
      description: >-
        Returns the total number of downloads for one or more R packages
        over the specified time period from the RStudio CRAN mirror.
      tags:
        - Downloads
      parameters:
        - name: period
          in: path
          required: true
          description: >-
            Time period for download stats. Use last-day, last-week,
            last-month, grand-total, or a date range like 2023-01-01:2023-12-31.
          schema:
            type: string
            enum:
              - last-day
              - last-week
              - last-month
              - grand-total
            example: last-week
        - name: packages
          in: path
          required: true
          description: >-
            Package name or comma-separated list of package names.
          schema:
            type: string
            example: ggplot2
      responses:
        '200':
          description: Download totals for the specified packages
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DownloadTotal'
  /downloads/daily/{period}/{packages}:
    get:
      operationId: getPackageDownloadDaily
      summary: Get Package Daily Downloads
      description: >-
        Returns daily download counts for one or more R packages over
        the specified time period.
      tags:
        - Downloads
      parameters:
        - name: period
          in: path
          required: true
          description: Time period (last-day, last-week, last-month, or date range)
          schema:
            type: string
            example: last-month
        - name: packages
          in: path
          required: true
          description: Package name or comma-separated list
          schema:
            type: string
            example: dplyr,tidyr
      responses:
        '200':
          description: Daily download counts for the specified packages
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DownloadDaily'
  /top/{period}/{count}:
    get:
      operationId: getTopPackages
      summary: Get Top Downloaded Packages
      description: >-
        Returns the most-downloaded CRAN packages for the specified time period.
        Count is limited to a maximum of 100.
      tags:
        - Top Packages
      parameters:
        - name: period
          in: path
          required: true
          description: Time period for ranking (last-day, last-week, last-month)
          schema:
            type: string
            enum:
              - last-day
              - last-week
              - last-month
            example: last-week
        - name: count
          in: path
          required: true
          description: Number of top packages to return (max 100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            example: 20
      responses:
        '200':
          description: Top downloaded packages for the period
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopPackages'
  /badges/{period}/{package}:
    get:
      operationId: getDownloadBadge
      summary: Get Download Count Badge
      description: >-
        Returns an SVG badge showing the download count for an R package
        over the specified period. Suitable for embedding in README files.
      tags:
        - Badges
      parameters:
        - name: period
          in: path
          required: true
          description: Badge period (last-day, last-week, grand-total)
          schema:
            type: string
            enum:
              - last-day
              - last-week
              - grand-total
            example: grand-total
        - name: package
          in: path
          required: true
          description: R package name
          schema:
            type: string
            example: Rcpp
      responses:
        '200':
          description: SVG badge image
          content:
            image/svg+xml:
              schema:
                type: string
components:
  schemas:
    DownloadTotal:
      type: object
      properties:
        package:
          type: string
          description: R package name
          example: ggplot2
        start:
          type: string
          format: date
          description: Start date of the period
          example: '2024-01-01'
        end:
          type: string
          format: date
          description: End date of the period
          example: '2024-01-07'
        downloads:
          type: integer
          description: Total download count for the period
          example: 142835
    DownloadDaily:
      type: object
      properties:
        package:
          type: string
          description: R package name
          example: dplyr
        start:
          type: string
          format: date
          description: Start date of the period
          example: '2024-01-01'
        end:
          type: string
          format: date
          description: End date of the period
          example: '2024-01-31'
        downloads:
          type: array
          description: Daily download counts
          items:
            $ref: '#/components/schemas/DailyCount'
    DailyCount:
      type: object
      properties:
        day:
          type: string
          format: date
          description: Date of downloads
          example: '2024-01-15'
        downloads:
          type: integer
          description: Number of downloads on this day
          example: 4821
    TopPackages:
      type: object
      properties:
        start:
          type: string
          format: date
          description: Start date of the period
          example: '2024-01-22'
        end:
          type: string
          format: date
          description: End date of the period
          example: '2024-01-28'
        downloads:
          type: array
          description: Package download rankings
          items:
            $ref: '#/components/schemas/PackageRanking'
    PackageRanking:
      type: object
      properties:
        package:
          type: string
          description: R package name
          example: Rcpp
        downloads:
          type: integer
          description: Download count for the period
          example: 853210