GitHub Trending API is a small FastAPI service that scrapes GitHub Trending and returns JSON data for trending repositories and developers. It is based on the idea of huchenme/github-trending-api, but implemented in Python.

There is currently no hosted public instance of this API. Run it locally or use the Docker image.

Features

• Trending repository and developer endpoints.
• Optional since filters: daily, weekly, monthly.
• Optional repository spoken_language_code filter.
• Typed OpenAPI responses via Pydantic models.
• Short in-memory cache for upstream GitHub Trending HTML responses.
• /health and /metadata operational endpoints.
• Docker image with non-root runtime user and healthcheck.

Examples

Data you can retrieve from this API after starting it locally.

Trending Repositories

❯ curl -X GET "http://127.0.0.1:1313/repositories" -H  "accept: application/json"
[
  {
    "rank": 1,
    "username": "sherlock-project",
    "repositoryName": "sherlock",
    "url": "https://github.com/sherlock-project/sherlock",
    "description": "Hunt down social media accounts by username across social networks",
    "language": "Python",
    "languageColor": "#3572A5",
    "totalStars": 21977,
    "forks": 2214,
    "starsSince": 462,
    "since": "daily",
    "builtBy": [
      {
        "username": "hoadlck",
        "url": "https://github.com/hoadlck",
        "avatar": "https://avatars.githubusercontent.com/u/1666888?s=40&v=4"
      },
      ...
    ]
  },
  ...
]

Trending Developers

❯ curl -X GET "http://127.0.0.1:1313/developers" -H  "accept: application/json"
[
  {
    "rank": 1,
    "username": "felangel",
    "name": "Felix Angelov",
    "url": "https://github.com/felangel",
    "avatar": "https://avatars.githubusercontent.com/u/8855632?s=96&v=4",
    "since": "daily",
    "popularRepository": {
      "repositoryName": "bloc",
      "description": "A predictable state management library that helps implement the BLoC design pattern",
      "url": "https://github.com/felangel/bloc"
    }
  },
  ...
]

API

FastAPI exposes interactive documentation at http://127.0.0.1:1313/docs after startup.

endpoint	description
/	route discovery
/health	minimal health check
/metadata	API metadata, cache TTL, supported date ranges, parameter counts
/repositories	trending repositories
/repositories/{prog_lang}	trending repositories for a programming language
/developers	trending developers
/developers/{prog_lang}	trending developers for a programming language

A path parameter for the programming language can limit the scope of the search. The allowed values currently come from the project's AllowedProgrammingLanguages enum.

The since query parameter selects the date range:

• daily
• weekly
• monthly

Repositories can also be limited to a spoken language with spoken_language_code.

Here are some examples. Repositories can be queried for 3 parameters...

example	programming lang	date range	spoken lang
/repositories	❌	❌	❌
/repositories?since=weekly	❌	✔️	❌
/repositories/python	✔️	❌	❌
/repositories/python?since=monthly	✔️	✔️	❌
/repositories/python?since=weekly&spoken_language_code=zh	✔️	✔️	✔️

...whereas developers can only be queried for 2 parameters.

example	programming lang	date range
/developers	❌	❌
/developers?since=weekly	❌	✔️
/developers/c++	✔️	❌
/developers/c++?since=weekly	✔️	✔️

Local Development

You can easily clone the project and run it locally:

❯ git clone https://github.com/NiklasTiede/Github-Trending-API.git
❯ cd Github-Trending-API

Install uv and sync the locked Python 3.13 environment:

❯ brew install uv
❯ uv sync --dev
❯ uv run python -m uvicorn app.main:app --host 127.0.0.1 --port 1313 --reload

Useful commands:

❯ uv run pytest
❯ uv run pre-commit run --all-files
❯ uv run ruff check app tests

The Makefile wraps common commands:

❯ make run
❯ make test
❯ make pre-commit
❯ make docker-build

Docker

Or build and run the Docker image locally:

❯ docker build -t github-trending-api .
❯ docker run -p 5000:5000 github-trending-api

The container exposes port 5000, runs as a non-root user, and includes a Docker healthcheck against /health.

Publishing Docker Images

Releases publish the Docker image to Docker Hub when a Git tag matching v*.*.* is pushed. The workflow publishes:

• niklastiede/github-trending-api:latest
• niklastiede/github-trending-api:<tag>

The GitHub repository needs these Actions secrets:

• DOCKER_USERNAME
• DOCKER_PASSWORD