openapi: 3.1.0
info:
  title: PyPI Index Downloads API
  description: The PyPI Index API implements the PEP 503 (HTML) and PEP 691 (JSON) simple repository standards for discovering and downloading Python packages. It provides a machine-readable index of all registered projects and their available distribution files. The API is available in both HTML and JSON formats, with JSON recommended for new integrations. This is the primary API that package installers like pip use to resolve and download dependencies from the Python Package Index.
  version: '1.0'
  contact:
    name: PyPI Support
    url: https://pypi.org/help/
  termsOfService: https://pypi.org/policy/terms-of-use/
servers:
- url: https://pypi.org
  description: Production Server
tags:
- name: Downloads
  description: Retrieve aggregate download statistics and time series data for Python packages.
paths:
  /packages/{package}/recent:
    get:
      operationId: getRecentDownloads
      summary: Get recent download counts
      description: Retrieves the aggregate download quantities for the last day, last week, and last month for the specified package. This provides a quick overview of recent download activity without a full time series.
      tags:
      - Downloads
      parameters:
      - $ref: '#/components/parameters/PackageName'
      - name: period
        in: query
        required: false
        description: Filter to a specific time period. If omitted, returns all three periods.
        schema:
          type: string
          enum:
          - day
          - week
          - month
      responses:
        '200':
          description: Recent download counts retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecentDownloads'
        '404':
          description: Package not found
  /packages/{package}/overall:
    get:
      operationId: getOverallDownloads
      summary: Get overall download time series
      description: Retrieves the aggregate daily download time series for the specified package, with or without mirror downloads included. Time series data is retained for 180 days.
      tags:
      - Downloads
      parameters:
      - $ref: '#/components/parameters/PackageName'
      - name: mirrors
        in: query
        required: false
        description: Filter by whether downloads from known mirrors are included. Use true to include only mirror downloads, false to exclude them.
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
      responses:
        '200':
          description: Overall download time series retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DownloadTimeSeries'
        '404':
          description: Package not found
  /packages/{package}/python_major:
    get:
      operationId: getDownloadsByPythonMajor
      summary: Get downloads by Python major version
      description: Retrieves the aggregate daily download time series broken down by Python major version number (e.g., 2 or 3). Time series data is retained for 180 days.
      tags:
      - Downloads
      parameters:
      - $ref: '#/components/parameters/PackageName'
      - name: version
        in: query
        required: false
        description: Filter to a specific Python major version. If omitted, returns all versions including null.
        schema:
          type: string
          examples:
          - '2'
          - '3'
      responses:
        '200':
          description: Downloads by Python major version retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DownloadTimeSeries'
        '404':
          description: Package not found
  /packages/{package}/python_minor:
    get:
      operationId: getDownloadsByPythonMinor
      summary: Get downloads by Python minor version
      description: Retrieves the aggregate daily download time series broken down by Python minor version number (e.g., 2.7 or 3.11). Time series data is retained for 180 days.
      tags:
      - Downloads
      parameters:
      - $ref: '#/components/parameters/PackageName'
      - name: version
        in: query
        required: false
        description: Filter to a specific Python minor version. If omitted, returns all versions including null.
        schema:
          type: string
          examples:
          - '2.7'
          - '3.11'
          - '3.12'
      responses:
        '200':
          description: Downloads by Python minor version retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DownloadTimeSeries'
        '404':
          description: Package not found
  /packages/{package}/system:
    get:
      operationId: getDownloadsBySystem
      summary: Get downloads by operating system
      description: Retrieves the aggregate daily download time series broken down by operating system (Windows, Linux, Darwin, or other). Time series data is retained for 180 days.
      tags:
      - Downloads
      parameters:
      - $ref: '#/components/parameters/PackageName'
      - name: os
        in: query
        required: false
        description: Filter to a specific operating system. If omitted, returns all operating systems including null.
        schema:
          type: string
          enum:
          - windows
          - linux
          - darwin
          - other
      responses:
        '200':
          description: Downloads by operating system retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DownloadTimeSeries'
        '404':
          description: Package not found
components:
  parameters:
    PackageName:
      name: package
      in: path
      required: true
      description: The name of the Python package to retrieve download statistics for.
      schema:
        type: string
        examples:
        - requests
        - numpy
  schemas:
    DownloadTimeSeries:
      type: object
      description: Daily download time series data, optionally broken down by category.
      properties:
        data:
          type: array
          description: Array of daily download count records.
          items:
            $ref: '#/components/schemas/DownloadRecord'
        package:
          type: string
          description: The name of the package.
        type:
          type: string
          description: The type of statistics returned, such as overall_downloads, python_major_downloads, python_minor_downloads, or system_downloads.
    RecentDownloads:
      type: object
      description: Aggregate download counts for the last day, week, and month.
      properties:
        data:
          type: object
          description: The download count data.
          properties:
            last_day:
              type: integer
              nullable: true
              description: Total downloads in the last day.
            last_week:
              type: integer
              nullable: true
              description: Total downloads in the last week.
            last_month:
              type: integer
              nullable: true
              description: Total downloads in the last month.
        package:
          type: string
          description: The name of the package.
        type:
          type: string
          description: The type of statistics returned.
          examples:
          - recent_downloads
    DownloadRecord:
      type: object
      description: A single daily download count record.
      properties:
        category:
          type: string
          nullable: true
          description: The category for this record, such as a Python version number, operating system name, or mirror inclusion flag. Null when no category breakdown is applied.
        date:
          type: string
          format: date
          description: The date of the download count in YYYY-MM-DD format.
        downloads:
          type: integer
          description: The number of downloads on this date for this category.
externalDocs:
  description: PyPI Index API Documentation
  url: https://docs.pypi.org/api/index-api/