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.