PingCAP Stargazers API

openapi: 3.2.0
info:
  title: OSSInsight Public Stargazers 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: Stargazers
paths:
  /repos/{owner}/{repo}/stargazers/countries/:
    get:
      operationId: list-countries-of-stargazers
      summary: List countries/regions of stargazers
      tags:
      - Stargazers
      description: "List countries/regions of stargazers for the specified repository.\n  \n> **Notice**:\n> In the overall data, about **3.5%** of GitHub users provided valid country/region information.\n\n> **Note**: \n> By default, the API does not count users without valid country/region information. \n> If you need to count these users, you can set the `exclude_unknown` parameter to `false`.\n"
      parameters:
      - schema:
          type: boolean
          default: true
        in: query
        name: exclude_unknown
        required: false
        description: Whether to exclude issue creators with unknown country/region information
      - schema:
          type: string
          default: 2000-01-01
        in: query
        name: from
        required: false
        description: The start date of the range.
      - schema:
          type: string
          default: 2099-01-01
        in: query
        name: to
        required: false
        description: The end date of the range.
      - schema:
          type: string
        example: pingcap
        in: path
        name: owner
        required: true
        description: The owner of the repo.
      - schema:
          type: string
        example: tidb
        in: path
        name: repo
        required: true
        description: The name of the repo.
      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: country_code
                          data_type: CHAR
                        - col: stargazers
                          data_type: BIGINT
                        - col: percentage
                          data_type: DECIMAL
                      rows:
                        type: array
                        items:
                          type: object
                          properties:
                            country_code:
                              type: string
                              description: Country/region code
                            stargazers:
                              type: string
                              description: Number of stargazers from the country/region
                            percentage:
                              type: string
                              description: Percentage of stargazers from the country/region
                        example:
                        - country_code: CN
                          percentage: '0.5935'
                          stargazers: '9189'
                        - country_code: US
                          percentage: '0.0996'
                          stargazers: '1542'
                        - country_code: JP
                          percentage: '0.0305'
                          stargazers: '473'
                        - country_code: DE
                          percentage: '0.0267'
                          stargazers: '413'
                      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: 4
                          row_affect: 0
                          limit: 50
                          databases:
                          - gharchive_dev
  /repos/{owner}/{repo}/stargazers/history/:
    get:
      operationId: stargazers-history
      summary: Stargazers history
      tags:
      - Stargazers
      description: Querying the historical trend of the number of stargazers in a given repository.
      parameters:
      - schema:
          type: string
          enum:
          - day
          - week
          - month
          default: month
        in: query
        name: per
        required: false
        description: The time interval of the data points.
      - schema:
          type: string
          default: 2000-01-01
        in: query
        name: from
        required: false
        description: The start date of the time range.
      - schema:
          type: string
          default: 2099-01-01
        in: query
        name: to
        required: false
        description: The end date of the time range.
      - schema:
          type: string
        example: pingcap
        in: path
        name: owner
        required: true
        description: The owner of the repo.
      - schema:
          type: string
        example: tidb
        in: path
        name: repo
        required: true
        description: The name of the repo.
      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: date
                          data_type: VARCHAR
                        - col: pull_request_creators
                          data_type: DECIMAL
                      rows:
                        type: array
                        items:
                          type: object
                          properties:
                            date:
                              type: string
                              description: The date of the data point
                            stargazers:
                              type: string
                              description: The cumulative number of stargazers
                        example:
                        - date: 2023-04-01
                          stargazers: '35389'
                        - date: 2023-05-01
                          stargazers: '35593'
                        - date: 2023-06-01
                          stargazers: '35805'
                        - date: 2023-07-01
                          stargazers: '36019'
                        - date: 2023-08-01
                          stargazers: '36026'
                      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
  /repos/{owner}/{repo}/stargazers/organizations/:
    get:
      operationId: list-organizations-of-stargazers
      summary: List organizations of stargazers
      tags:
      - Stargazers
      description: "List organizations of stargazers for the specified repository. \n\n> **Notice**:\n> In the overall data, about **5.62%** of GitHub users provided valid organization information.\n\n> **Note**: \n> By default, the API does not count users without valid organization information. \n> If you need to count these users, you can set the `exclude_unknown` parameter to `false`.\n"
      parameters:
      - schema:
          type: boolean
          default: true
        in: query
        name: exclude_unknown
        required: false
        description: Whether to exclude stargazers with unknown organization information
      - schema:
          type: string
          default: 2000-01-01
        in: query
        name: from
        required: false
        description: The start date of the range.
      - schema:
          type: string
          default: 2099-01-01
        in: query
        name: to
        required: false
        description: The end date of the range.
      - schema:
          type: string
        example: pingcap
        in: path
        name: owner
        required: true
        description: The owner of the repo.
      - schema:
          type: string
        example: tidb
        in: path
        name: repo
        required: true
        description: The name of the repo.
      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: org_name
                          data_type: VARCHAR
                        - col: stargazers
                          data_type: BIGINT
                        - col: percentage
                          data_type: DECIMAL
                      rows:
                        type: array
                        items:
                          type: object
                          properties:
                            org_name:
                              type: string
                              description: Name of the organization
                            percentage:
                              type: string
                              description: Percentage of stargazers from the organization
                            stargazers:
                              type: string
                              description: Number of stargazers from the organization
                        example:
                        - org_name: tencent
                          percentage: '0.0217'
                          stargazers: '199'
                        - org_name: bytedance
                          percentage: '0.0192'
                          stargazers: '176'
                        - org_name: alibaba
                          percentage: '0.0162'
                          stargazers: '148'
                        - org_name: pingcap
                          percentage: '0.0119'
                          stargazers: '109'
                      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: 4
                          row_affect: 0
                          limit: 50
                          databases:
                          - gharchive_dev