PingCAP Collections API

openapi: 3.2.0
info:
  title: OSSInsight Public Collections API
  description: "\nOSSInsight Public APIs (beta) provide a convenient way to access insight data for open source projects on GitHub, supplementing the existing GitHub API.\n\nIt provides data query in different dimensions, including:\n\n```mdx-code-block\nimport DocCardList from '@theme/DocCardList';\nimport {useCurrentSidebarCategory} from '@docusaurus/theme-common';\n\n<DocCardList items={useCurrentSidebarCategory().items.filter((item) => {\n    // Exclude Introduction and Showcase pages\n    return item.docId !== 'api/showcase' && item.docId !== 'api/ossinsight-public-api';\n})}/>\n```\n\n## Usage\n\nThe OSSInsight Public API is designed to follow the OpenAPI specification and can be accessed by initiating HTTP requests using the command line `curl` or web request libraries in different programming languages.\n\n### Base URL\n\nAll API requests are based on the following URL:\n\n```shell\nhttps://api.ossinsight.io/v1\n```\n\n### Authentication\n\nNo authentication is required for beta version of public APIs, but there are [rate limits](#rate-limit) for API requests.\n\n> Note:\n> We will add authentication way for larger API requests in future releases.\n\n### Rate Limit\n\nFor each IP address, the rate limit allows for up to **600 requests per hour**, which can be checked by the following fields in the Response Header to see the current usage:\n\n```\nx-ratelimit-limit: 600\nx-ratelimit-remaining: 599\n```\n\nIn addition, we have also set up a global rate limit of up to **1000 requests per minute**, which can be checked by the following fields in the Response Header to see the current usage:\n\n```\nx-ratelimit-limit-minute: 1000\nx-ratelimit-remaining-minute: 97\n```\n\n### Example\n\nFor example, if you want to know what countries the stargazers in the `pingcap/tidb` repository are located in, you can make a request using the curl command as follows:\n\n```shell\ncurl https://api.ossinsight.io/v1/repos/pingcap/tidb/stargazers/countries\n```\n\n<details>\n\n<summary>Example Response</summary>\n\n```json\n{\n  \"type\": \"sql_endpoint\",\n  \"data\": {\n    \"columns\": [\n      {\n        \"col\": \"country_or_area\",\n        \"data_type\": \"CHAR\",\n        \"nullable\": true\n      },\n      {\n        \"col\": \"count\",\n        \"data_type\": \"BIGINT\",\n        \"nullable\": true\n      },\n      {\n        \"col\": \"percentage\",\n        \"data_type\": \"DECIMAL\",\n        \"nullable\": true\n      }\n    ],\n    \"rows\": [\n      {\n        \"count\": \"9183\",\n        \"country_or_area\": \"CN\",\n        \"percentage\": \"0.5936\"\n      },\n      {\n        \"count\": \"1542\",\n        \"country_or_area\": \"US\",\n        \"percentage\": \"0.0997\"\n      },\n      {\n        \"count\": \"471\",\n        \"country_or_area\": \"JP\",\n        \"percentage\": \"0.0304\"\n      }\n    ],\n    \"result\": {\n      \"code\": 200,\n      \"message\": \"Query OK!\",\n      \"start_ms\": 1690351487809,\n      \"end_ms\": 1690351487930,\n      \"latency\": \"121ms\",\n      \"row_count\": 132,\n      \"row_affect\": 0,\n      \"limit\": 300,\n      \"databases\": [\n        \"gharchive_dev\"\n      ]\n    }\n  }\n}\n```\n\n</details>\n\n## Request New API \n\nIf the API in the documentation does not meet your query requirements, please contact us as follows:\n\n- Email us at ossinsight@pingcap.com\n- Open an issue in the [OSSInsight GitHub repository](https://github.com/pingcap/ossinsight/issues/new?assignees=&labels=type%2Ffeature&projects=&template=feature_request.md&title=New%20API)\n"
  version: v1beta
servers:
- url: https://api.ossinsight.io/v1
tags:
- name: Collections
paths:
  /collections/:
    get:
      operationId: list-collections
      summary: List collections
      tags:
      - Collections
      description: List collections.
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                required:
                - type
                - data
                properties:
                  type:
                    type: string
                    description: The type of the endpoint.
                    enum:
                    - sql_endpoint
                    example: sql_endpoint
                  data:
                    type: object
                    required:
                    - columns
                    - rows
                    - result
                    properties:
                      columns:
                        type: array
                        items:
                          type: object
                          required:
                          - col
                          - data_type
                          - nullable
                          properties:
                            col:
                              type: string
                              description: The name of the column in the query result.
                            data_type:
                              type: string
                              enum:
                              - CHAR
                              - BIGINT
                              - DECIMAL
                              - INT
                              - UNSIGNED BIGINT
                              - TINYINT
                              - TIMESTAMP
                              - TEXT
                              - VARCHAR
                              - DATETIME
                              - DOUBLE
                              - FLOAT
                              - DATE
                              - TIME
                              - YEAR
                              - MEDIUMINT
                              - SMALLINT
                              - BIT
                              - BINARY
                              - VARBINARY
                              - JSON
                              - ENUM
                              - SET
                              - TINYTEXT
                              - MEDIUMTEXT
                              - LONGTEXT
                              - TINYBLOB
                              - MEDIUMBLOB
                              - BLOB
                              - LONGBLOB
                              description: The data type of the column.
                            nullable:
                              type: boolean
                              description: Whether the column is nullable.
                          additionalProperties: true
                        example:
                        - col: id
                          data_type: BIGINT
                        - col: name
                          data_type: VARCHAR
                      rows:
                        type: array
                        items:
                          type: object
                          properties:
                            repo_id:
                              type: string
                              description: Repository ID
                            repo_name:
                              type: string
                              description: Repository name
                          additionalProperties: true
                        example:
                        - id: '1'
                          name: Static Site Generator
                        - id: '2'
                          name: Open Source Database
                        - id: '10001'
                          name: CSS Framework
                        - id: '10002'
                          name: Google Analytics Alternative
                        - id: '10003'
                          name: Low Code Development Tool
                      result:
                        type: object
                        properties:
                          code:
                            type: number
                            description: The code of the response.
                          message:
                            type: string
                            description: The message of the response.
                          start_ms:
                            type: number
                            description: The start time of the query in milliseconds.
                          end_ms:
                            type: number
                            description: The end time of the query in milliseconds.
                          latency:
                            type: string
                            description: The latency of the query.
                          row_count:
                            type: number
                            description: The number of rows in the query result.
                          row_affect:
                            type: number
                            description: The number of rows affected by the query.
                          limit:
                            type: number
                            description: The maximum number of rows in the query result.
                          databases:
                            type: array
                            description: The databases used in the query.
                            items:
                              type: string
                        additionalProperties: true
                        example:
                          code: 200
                          message: Query OK!
                          start_ms: 1690957407469
                          end_ms: 1690957407499
                          latency: 30ms
                          row_count: 5
                          row_affect: 0
                          limit: 50
                          databases:
                          - gharchive_dev
  /collections/hot/:
    get:
      operationId: list-hot-collections
      summary: List hot collections
      tags:
      - Collections
      description: List hot collections with top repositories of the collection.
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                required:
                - type
                - data
                properties:
                  type:
                    type: string
                    description: The type of the endpoint.
                    enum:
                    - sql_endpoint
                    example: sql_endpoint
                  data:
                    type: object
                    required:
                    - columns
                    - rows
                    - result
                    properties:
                      columns:
                        type: array
                        items:
                          type: object
                          required:
                          - col
                          - data_type
                          - nullable
                          properties:
                            col:
                              type: string
                              description: The name of the column in the query result.
                            data_type:
                              type: string
                              enum:
                              - CHAR
                              - BIGINT
                              - DECIMAL
                              - INT
                              - UNSIGNED BIGINT
                              - TINYINT
                              - TIMESTAMP
                              - TEXT
                              - VARCHAR
                              - DATETIME
                              - DOUBLE
                              - FLOAT
                              - DATE
                              - TIME
                              - YEAR
                              - MEDIUMINT
                              - SMALLINT
                              - BIT
                              - BINARY
                              - VARBINARY
                              - JSON
                              - ENUM
                              - SET
                              - TINYTEXT
                              - MEDIUMTEXT
                              - LONGTEXT
                              - TINYBLOB
                              - MEDIUMBLOB
                              - BLOB
                              - LONGBLOB
                              description: The data type of the column.
                            nullable:
                              type: boolean
                              description: Whether the column is nullable.
                          additionalProperties: true
                        example:
                        - col: id
                          data_type: BIGINT
                        - col: name
                          data_type: VARCHAR
                        - col: repos
                          data_type: BIGINT
                        - col: repo_id
                          data_type: BIGINT
                        - col: repo_name
                          data_type: VARCHAR
                        - col: repo_current_period_rank
                          data_type: INT
                        - col: repo_past_period_rank
                          data_type: INT
                        - col: repo_rank_changes
                          data_type: BIGINT
                      rows:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              description: Collection ID
                            name:
                              type: string
                              description: Collection name
                            repos:
                              type: string
                              description: The number of repositories in the collection
                            repo_id:
                              type: string
                              description: Repository ID
                            repo_name:
                              type: string
                              description: Repository name
                            repo_current_period_rank:
                              type: string
                              description: The rank of the repository in the collection in the current period
                            repo_past_period_rank:
                              type: string
                              description: The rank of the repository in the collection in the past period
                            repo_rank_changes:
                              type: string
                              description: The rank changes of the repository in the collection
                          additionalProperties: true
                        example:
                        - id: '10010'
                          name: Artificial Intelligence
                          repos: '36'
                          repo_id: '155220641'
                          repo_name: huggingface/transformers
                          repo_current_period_rank: '1'
                          repo_past_period_rank: '1'
                          repo_rank_changes: '0'
                        - id: '10010'
                          name: Artificial Intelligence
                          repos: '36'
                          repo_id: '65600975'
                          repo_name: pytorch/pytorch
                          repo_current_period_rank: '3'
                          repo_past_period_rank: '4'
                          repo_rank_changes: '1'
                        - id: '10010'
                          name: Artificial Intelligence
                          repos: '36'
                          repo_id: '458588993'
                          repo_name: nebuly-ai/nebullvm
                          repo_current_period_rank: '2'
                          repo_past_period_rank: '2'
                          repo_rank_changes: '0'
                        - id: '10078'
                          name: ChatGPT Apps
                          repos: '36'
                          repo_id: '599394820'
                          repo_name: Chanzhaoyu/chatgpt-web
                          repo_current_period_rank: '3'
                          repo_past_period_rank: '6'
                          repo_rank_changes: '3'
                        - id: '10078'
                          name: ChatGPT Apps
                          repos: '36'
                          repo_id: '609416865'
                          repo_name: yetone/openai-translator
                          repo_current_period_rank: '2'
                          repo_past_period_rank: ''
                          repo_rank_changes: ''
                        - id: '10078'
                          name: ChatGPT Apps
                          repos: '36'
                          repo_id: '608555244'
                          repo_name: microsoft/visual-chatgpt
                          repo_current_period_rank: '1'
                          repo_past_period_rank: ''
                          repo_rank_changes: ''
                      result:
                        type: object
                        properties:
                          code:
                            type: number
                            description: The code of the response.
                          message:
                            type: string
                            description: The message of the response.
                          start_ms:
                            type: number
                            description: The start time of the query in milliseconds.
                          end_ms:
                            type: number
                            description: The end time of the query in milliseconds.
                          latency:
                            type: string
                            description: The latency of the query.
                          row_count:
                            type: number
                            description: The number of rows in the query result.
                          row_affect:
                            type: number
                            description: The number of rows affected by the query.
                          limit:
                            type: number
                            description: The maximum number of rows in the query result.
                          databases:
                            type: array
                            description: The databases used in the query.
                            items:
                              type: string
                        additionalProperties: true
                        example:
                          code: 200
                          message: Query OK!
                          start_ms: 1690957407469
                          end_ms: 1690957407499
                          latency: 30ms
                          row_count: 6
                          row_affect: 0
                          limit: 50
                          databases:
                          - gharchive_dev
  /collections/{collection_id}/ranking_by_issues/:
    get:
      operationId: collection-repo-ranking-by-issues
      summary: Repository ranking by issues
      tags:
      - Collections
      description: Rank the GitHub repositories in the specified collection according to the number of issues.
      parameters:
      - schema:
          type: string
          enum:
          - past_28_days
          - past_month
          default: past_28_days
        in: query
        name: period
        required: false
        description: The period of the range.
      - schema:
          type: number
        in: path
        name: collection_id
        required: true
        description: The ID of collection
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                required:
                - type
                - data
                properties:
                  type:
                    type: string
                    description: The type of the endpoint.
                    enum:
                    - sql_endpoint
                    example: sql_endpoint
                  data:
                    type: object
                    required:
                    - columns
                    - rows
                    - result
                    properties:
                      columns:
                        type: array
                        items:
                          type: object
                          required:
                          - col
                          - data_type
                          - nullable
                          properties:
                            col:
                              type: string
                              description: The name of the column in the query result.
                            data_type:
                              type: string
                              enum:
                              - CHAR
                              - BIGINT
                              - DECIMAL
                              - INT
                              - UNSIGNED BIGINT
                              - TINYINT
                              - TIMESTAMP
                              - TEXT
                              - VARCHAR
                              - DATETIME
                              - DOUBLE
                              - FLOAT
                              - DATE
                              - TIME
                              - YEAR
                              - MEDIUMINT
                              - SMALLINT
                              - BIT
                              - BINARY
                              - VARBINARY
                              - JSON
                              - ENUM
                              - SET
                              - TINYTEXT
                              - MEDIUMTEXT
                              - LONGTEXT
                              - TINYBLOB
                              - MEDIUMBLOB
                              - BLOB
                              - LONGBLOB
                              description: The data type of the column.
                            nullable:
                              type: boolean
                              description: Whether the column is nullable.
                          additionalProperties: true
                        example:
                        - col: repo_id
                          data_type: BIGINT
                        - col: repo_name
                          data_type: VARCHAR
                        - col: current_period_growth
                          data_type: BIGINT
                        - col: current_period_rank
                          data_type: BIGINT
                        - col: past_period_growth
                          data_type: BIGINT
                        - col: past_period_rank
                          data_type: BIGINT
                        - col: growth_pop
                          data_type: DECIMAL
                        - col: rank_pop
                          data_type: BIGINT
                        - col: total
                          data_type: BIGINT
                      rows:
                        type: array
                        items:
                          type: object
                          properties:
                            repo_id:
                              type: string
                              description: The repository ID
                            repo_name:
                              type: string
                              description: The repository name
                            current_period_growth:
                              type: string
                              description: issues growth in the current period (past 28 days / current month)
                            past_period_growth:
                              type: string
                              description: issues growth in the past period (The 28 days before the past 28 days / past month)
                            growth_pop:
                              type: string
                              description: The period-over-period growth of issues
                            rank_pop:
                              type: string
                              description: The period-over-period rank changes of issues
                            total:
                              type: string
                              description: The current total issues of repository
                          additionalProperties: true
                        example:
                        - repo_id: '16563587'
                          repo_name: cockroachdb/cockroach
                          current_period_growth: '677'
                          past_period_growth: '729'
                          growth_pop: '-7.13'
                          rank_pop: '0'
                          total: '54541'
                          current_period_rank: '1'
                          past_period_rank: '1'
                        - repo_id: '60246359'
                          repo_name: clickhouse/clickhouse
                          current_period_growth: '268'
                          past_period_growth: '296'
                          growth_pop: '-9.46'
                          rank_pop: '-1'
                          total: '16732'
                          current_period_rank: '2'
                          past_period_rank: '3'
                        - repo_id: '41986369'
                          repo_name: pingcap/tidb
                          current_period_growth: '263'
                          past_period_growth: '214'
                          growth_pop: '22.90'
                          rank_pop: '-3'
                          total: '15622'
                          current_period_rank: '3'
                          past_period_rank: '6'
                        - repo_id: '105944401'
                          repo_name: yugabyte/yugabyte-db
                          current_period_growth: '246'
                          past_period_growth: '298'
                          growth_pop: '-17.45'
                          rank_pop: '2'
                          total: '15079'
                          current_period_rank: '4'
                          past_period_rank: '2'
                        - repo_id: '208728772'
                          repo_name: milvus-io/milvus
                          current_period_growth: '234'
                          past_period_growth: '237'
                          growth_pop: '-1.27'
                          rank_pop: '0'
                          total: '8675'
                          current_period_rank: '5'
                          past_period_rank: '5'
                        - repo_id: '507775'
                          repo_name: elastic/elasticsearch
                          current_period_growth: '214'
                          past_period_growth: '144'
                          growth_pop: '48.61'
                          rank_pop: '-3'
                          total: '31578'
                          current_period_rank: '6'
                          past_period_rank: '9'
                      result:
                        type: object
                        properties:
                          code:
                            type: number
                            description: The code of the response.
                          message:
                            type: string
                            description: The message of the response.
                          start_ms:
                            type: number
                            description: The start time of the query in milliseconds.
                          end_ms:
                            type: number
                            description: The end time of the query in milliseconds.
                          latency:
                            type: string
                            description: The latency of the query.
                          row_count:
                            type: number
                            description: The number of rows in the query result.
                          row_affect:
                            type: number
                            description: The number of rows affected by the query.
                          limit:
                            type: number
                            description: The maximum number of rows in the query result.
                          databases:
                            type: array
                            description: The databases used in the query.
                            items:
                              type: string
                        additionalProperties: true
                        example:
                          code: 200
                          message: Query OK!
                          start_ms: 1690957407469
                          end_ms: 1690957407499
                          latency: 30ms
                          row_count: 7
                          row_affect: 0
                          limit: 50
                          databases:
                          - gharchive_dev
  /collections/{collection_id}/ranking_by_prs/:
    get:
      operationId: collection-repo-ranking-by-prs
      summary: Repository ranking by prs
      tags:
      - Collections
      description: Rank the GitHub repositories in the specified collection according to the number of pull requests.
      parameters:
      - schema:
          type: string
          enum:
          - past_28_days
          - past_month
          default: past_28_days
        in: query
        name: period
        required: false
        description: The period of the range.
      - schema:
          type: number
        in: path
        name: collection_id
        required: true
        description: The ID of collection
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                required:
                - type
                - data
                properties:
                  type:
                    type: string
                    description: The type of the endpoint.
                    enum:
                    - sql_endpoint
                    example: sql_endpoint
                  data:
                    type: object
                    required:
                    - columns
                    - rows
                    - result
                    properties:
                      columns:
                        type: array
                        items:
                          type: object
                          required:
                          - col
                          - data_type
                          - nullable
                          properties:
                            col:
                              type: string
                              description: The name of the column in the query result.
                            data_type:
                              type: string
                              enum:
                              - CHAR
                              - BIGINT
                              - DECIMAL
                              - INT
                              - UNSIGNED BIGINT
                              - TINYINT
                              - TIMESTAMP
                              - TEXT
                              - VARCHAR
                              - DATETIME
                              - DOUBLE
                              - FLOAT
                              - DATE
                              - TIME
                              - YEAR
                              - MEDIUMINT
                              - SMALLINT
                              - BIT
                              - BIN

# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/pingcap/refs/heads/main/openapi/pingcap-collections-api-openapi.yml