PyPI Stats API

openapi: 3.1.0
info:
  title: PyPI Stats API
  description: >-
    The PyPI Stats API provides aggregate download statistics and time series
    data for Python packages hosted on PyPI. It offers JSON endpoints for
    querying download counts broken down by Python version, operating system,
    and time period. Time series data is retained for 180 days and all download
    statistics are updated once daily. The API is hosted at pypistats.org and
    serves as the primary programmatic interface for analyzing Python package
    adoption and download trends across the ecosystem.
  version: '1.0'
  contact:
    name: PyPI Stats
    url: https://pypistats.org/
  termsOfService: https://pypistats.org/
externalDocs:
  description: PyPI Stats API Documentation
  url: https://pypistats.org/api/
servers:
  - url: https://pypistats.org/api
    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:
    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
    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.
    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.