openapi: 3.0.0
info:
  title: GitHub Trending API
  description: |
    The GitHub Trending API scrapes github.com/trending into structured JSON: the repositories or developers GitHub ranks as trending for a day, a week, or a month. GitHub publishes no official API for this list.

    Trending repositories carry the repository id, name, owner, description, primary language and its color, total stars and forks, the stars gained in the selected date range, the contributors GitHub credits under "Built by" (including GitHub Apps), and a sponsors link when the owner is sponsorable. Trending developers carry their rank, id, login, display name, avatar, and the popular repository GitHub features for them, or their company, location or join date when no repository is featured.

    Pass `type=developers` for developers. Repositories are the default. Filter either list with `language` and `since`. `spoken_language` applies to repositories only, and GitHub classifies only older repositories by spoken language. `sponsorable=true` applies to developers only and returns the developers who accept GitHub Sponsors, whom GitHub leaves out of its default developers list. GitHub lists up to 25 entries and has no pagination.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: GitHub Trending
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Search engine to use
          schema:
            type: string
            enum: ["github_trending"]
            default: "github_trending"
        - name: type
          in: query
          required: false
          description: Which trending list to return, trending repositories or trending developers.
          schema:
            type: string
            enum: ["repositories", "developers"]
            default: "repositories"
        - name: language
          in: query
          required: false
          description: >-
            Programming language to filter by, as GitHub's slug (e.g. "python", "c++", "c#",
            "jupyter-notebook") or its display name (e.g. "Jupyter Notebook"), which is normalized to the
            slug. Use "unknown" for repositories without a detected language. In a URL, encode "#" as %23
            (e.g. c%23), otherwise everything after it is dropped. The full list of supported values is at
            https://www.searchapi.io/docs/parameters/github-trending/language. Omit it for all languages.
          schema:
            type: string
        - name: since
          in: query
          required: false
          description: >-
            Date range GitHub ranks the list over, and the range current_period_stars counts stars for:
            daily (today), weekly (this week), or monthly (this month).
          schema:
            type: string
            enum: ["daily", "weekly", "monthly"]
            default: "daily"
        - name: spoken_language
          in: query
          required: false
          description: >-
            Spoken language repositories are written in, as an ISO 639-1 code, e.g. "zh" or "en". The full
            list of supported codes is at https://www.searchapi.io/docs/parameters/github-trending/spoken-language.
            GitHub classifies only older repositories by spoken language, so these lists rarely overlap the
            unfiltered trending list. Supported for type=repositories only, and type=developers returns a 400.
          schema:
            type: string
        - name: sponsorable
          in: query
          required: false
          description: >-
            Set to true to return the trending developers who accept GitHub Sponsors. GitHub leaves these
            developers out of its default developers list, so the two lists never overlap. Supported for
            type=developers only, and sponsorable=true with type=repositories returns a 400.
          schema:
            type: boolean
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication Error. The API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate Limit Exceeded. The number of allowed requests has been exceeded. Consider upgrading your plan or waiting for the limit to reset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server Error. Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Timeout. We could not retrieve results in 90 seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"'
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Pass API key as query parameter
  schemas:
    SearchResponse:
      type: object
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        error:
          type: string
          description: Error message when GitHub has no trending entries for the requested filters
        trending_repositories:
          type: array
          description: Trending repositories in GitHub's ranking order, up to 25
          items:
            $ref: '#/components/schemas/TrendingRepository'
        trending_developers:
          type: array
          description: Trending developers in GitHub's ranking order, up to 25
          items:
            $ref: '#/components/schemas/TrendingDeveloper'
    SearchMetadata:
      type: object
      required: [id, status, created_at]
      properties:
        id:
          type: string
          description: Unique identifier for the search request
        status:
          type: string
          description: Status of the search request
        created_at:
          type: string
          format: date-time
          description: Timestamp when the search was created
        request_time_taken:
          type: number
          description: Time taken to make the request in seconds
        parsing_time_taken:
          type: number
          description: Time taken to parse the results in seconds
        total_time_taken:
          type: number
          description: Total time taken for the search in seconds
        request_url:
          type: string
          description: GitHub Trending URL for this search
        html_url:
          type: string
          description: URL to view HTML results
        json_url:
          type: string
          description: URL to view JSON results
    SearchParameters:
      type: object
      properties:
        engine:
          type: string
          description: Search engine used
        type:
          type: string
          description: The trending list returned, repositories or developers
        language:
          type: string
          description: The language filter, normalized to GitHub's slug (e.g. "jupyter-notebook")
        since:
          type: string
          description: The date range requested
        spoken_language:
          type: string
          description: The spoken language code requested
        sponsorable:
          type: string
          description: The sponsorable filter as sent ("true" or "false")
    TrendingRepository:
      type: object
      required: [position, name, full_name, owner, link, stars, current_period_stars]
      properties:
        position:
          type: integer
          description: Rank of the repository in the trending list, starting at 1
        id:
          type: integer
          description: GitHub repository ID
        name:
          type: string
          description: Repository name
        full_name:
          type: string
          description: Owner and repository name (e.g. alibaba/open-code-review)
        owner:
          $ref: '#/components/schemas/RepositoryOwner'
        link:
          type: string
          description: URL of the repository
        description:
          type: string
          description: Repository description
        language:
          type: string
          description: Primary language GitHub detected for the repository
        language_color:
          type: string
          description: GitHub's hex color for the primary language (e.g. "#3572A5")
        stars:
          type: integer
          description: Total stars
        forks:
          type: integer
          description: Total forks
        current_period_stars:
          type: integer
          description: Stars gained in the date range selected by since - today, this week, or this month
        built_by:
          type: array
          description: Contributors GitHub credits under "Built by", up to 5, including GitHub Apps such as dependabot[bot]
          items:
            $ref: '#/components/schemas/AccountAvatar'
        sponsors_link:
          type: string
          description: GitHub Sponsors page of the owner
        is_sponsorable:
          type: boolean
          description: Whether the owner accepts GitHub Sponsors
    RepositoryOwner:
      type: object
      required: [login]
      properties:
        login:
          type: string
          description: Login of the user or organization that owns the repository
    AccountAvatar:
      type: object
      required: [login, link, avatar_url]
      properties:
        login:
          type: string
          description: GitHub login, or {slug}[bot] for a GitHub App
        id:
          type: integer
          description: GitHub account ID
        link:
          type: string
          description: URL of the GitHub profile, or https://github.com/apps/{slug} for a GitHub App
        avatar_url:
          type: string
          description: Full-size avatar URL
    TrendingDeveloper:
      type: object
      required: [position, login, link, avatar_url]
      properties:
        position:
          type: integer
          description: Rank of the developer in the trending list, starting at 1
        id:
          type: integer
          description: GitHub account ID
        login:
          type: string
          description: GitHub login
        name:
          type: string
          description: Display name the developer set
        link:
          type: string
          description: URL of the GitHub profile
        avatar_url:
          type: string
          description: Full-size avatar URL
        company:
          type: string
          description: Company GitHub shows for the developer, without the "@" when it is a single organization handle
        location:
          type: string
          description: Location GitHub shows for the developer
        joined_date:
          type: string
          format: date
          description: Date the developer joined GitHub, as YYYY-MM-DD
        sponsors_link:
          type: string
          description: GitHub Sponsors page of the developer
        is_sponsorable:
          type: boolean
          description: Whether the developer accepts GitHub Sponsors
        popular_repository:
          $ref: '#/components/schemas/PopularRepository'
    PopularRepository:
      type: object
      description: The repository GitHub features for the developer
      required: [name, full_name, link]
      properties:
        id:
          type: integer
          description: GitHub repository ID
        name:
          type: string
          description: Repository name
        full_name:
          type: string
          description: Owner and repository name (e.g. JustVugg/colibri)
        link:
          type: string
          description: URL of the repository
        description:
          type: string
          description: Repository description as GitHub truncates it in the list
        is_fork:
          type: boolean
          description: Whether the featured repository is a fork
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message