# GitHub Trending Repos Tracker (`emperor1978/github-trending-tracker`) Actor

Track trending repositories on GitHub. Scrape daily, weekly, or monthly trending repos with names, descriptions, star counts, fork counts, languages, and URLs. Filter by programming language. Perfect for developer tools research, open source monitoring, and tech trend analysis.

- **URL**: https://apify.com/emperor1978/github-trending-tracker.md
- **Developed by:** [The Emperor](https://apify.com/emperor1978) (community)
- **Categories:** Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$1.00 / 1,000 result items

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## GitHub Trending Repos Tracker

Scrape [GitHub Trending](https://github.com/trending) and get structured, dataset-ready records for every trending repository — ranks, star counts, fork counts, stars gained today, contributor avatars, programming language, and description — all filtered exactly the way you need.

***

### What It Does

GitHub Trending is a server-rendered HTML page; there is no official API. This actor:

1. Builds the correct GitHub Trending URL from your input parameters (language, date range, spoken language).
2. Fetches the page with a polite `User-Agent` header, retrying up to 3 times with exponential backoff on transient failures.
3. Parses the HTML using [BeautifulSoup4](https://www.crummy.com/software/BeautifulSoup/) to extract structured data from each repository card.
4. Pushes each repository as a structured record to the Apify default dataset.

No authentication or API keys are required.

***

### Input Parameters

| Parameter | Type | Default | Description |
|---|---|---|---|
| `language` | string | `""` | Programming language slug (e.g. `python`, `javascript`, `rust`). Empty = all languages. |
| `date_range` | enum | `daily` | Time window: `daily`, `weekly`, or `monthly`. |
| `spoken_language` | string | `""` | ISO 639-1 code for the human language of the repo (e.g. `en`, `zh`). Empty = any. |
| `max_repos` | integer | `25` | Max repositories to return. GitHub shows at most 25 per page. |

#### Example Input

Trending Python repos this week, English README only:

```json
{
  "language": "python",
  "date_range": "weekly",
  "spoken_language": "en",
  "max_repos": 25
}
```

All-languages daily trending (default):

```json
{
  "language": "",
  "date_range": "daily",
  "spoken_language": "",
  "max_repos": 25
}
```

***

### Output Format

Each record in the dataset represents one trending repository:

```json
{
  "rank": 1,
  "full_name": "owner/repository-name",
  "url": "https://github.com/owner/repository-name",
  "description": "A short description of what the repository does.",
  "language": "Python",
  "stars": 48312,
  "forks": 3201,
  "stars_today": 872,
  "built_by": [
    {
      "username": "alice",
      "avatar_url": "https://avatars.githubusercontent.com/u/12345?s=40&v=4"
    },
    {
      "username": "bob",
      "avatar_url": "https://avatars.githubusercontent.com/u/67890?s=40&v=4"
    }
  ],
  "scraped_language": "python",
  "scraped_date_range": "weekly",
  "scraped_spoken_language": "en",
  "source_url": "https://github.com/trending/python?since=weekly&spoken_language_code=en"
}
```

#### Field Reference

| Field | Type | Description |
|---|---|---|
| `rank` | integer | Position on the trending page (1-based). |
| `full_name` | string | `owner/repo` slug, unique identifier on GitHub. |
| `url` | string | Full GitHub URL to the repository. |
| `description` | string | null | Repository description from the GitHub card. |
| `language` | string | null | Primary programming language as detected by GitHub. |
| `stars` | integer | null | Total cumulative star count. |
| `forks` | integer | null | Total cumulative fork count. |
| `stars_today` | integer | null | Stars gained during the selected `date_range` period. |
| `built_by` | array | List of contributor objects with `username` and `avatar_url`. |
| `scraped_language` | string | null | The `language` input used for this scrape run. |
| `scraped_date_range` | string | The `date_range` input used for this scrape run. |
| `scraped_spoken_language` | string | null | The `spoken_language` input used for this scrape run. |
| `source_url` | string | The exact GitHub Trending URL that was scraped. |

***

### Language Slugs

Use GitHub's own slug format, which is the language name lowercased with spaces replaced by hyphens. Common examples:

| Language | Slug |
|---|---|
| Python | `python` |
| JavaScript | `javascript` |
| TypeScript | `typescript` |
| Rust | `rust` |
| Go | `go` |
| C++ | `c++` |
| C# | `c%23` |
| Ruby | `ruby` |
| Java | `java` |
| Swift | `swift` |
| Kotlin | `kotlin` |
| Shell | `shell` |
| Jupyter Notebook | `jupyter-notebook` |

You can find any language's slug by browsing to [github.com/trending](https://github.com/trending), selecting the language from the dropdown, and reading the URL path segment.

***

### Spoken Language Codes

Common ISO 639-1 codes supported by GitHub Trending:

| Language | Code |
|---|---|
| English | `en` |
| Chinese (Simplified) | `zh` |
| Japanese | `ja` |
| Korean | `ko` |
| Spanish | `es` |
| French | `fr` |
| German | `de` |
| Portuguese | `pt` |
| Russian | `ru` |

***

### Use Cases

#### Technology Radar

Run the actor daily across multiple languages to track which projects are gaining traction fastest. Combine `stars_today` with total `stars` to separate genuinely new entrants from established projects getting a burst of attention.

#### Newsletter & Content Curation

Schedule a daily or weekly run to automatically populate a "what's trending on GitHub" section in a developer newsletter. Filter by `language` to stay on-topic for a specific audience.

#### Competitive Intelligence

Monitor trending repos in a domain (e.g. `language=python`, `date_range=weekly`) to catch newly open-sourced tools that compete with or complement your product before they go viral.

#### Recruiting & Ecosystem Mapping

The `built_by` contributor list surfaces active GitHub users working on high-momentum projects. Cross-reference with LinkedIn or other sources to identify talent in a specific language ecosystem.

#### Data Analysis & Trend Forecasting

Export daily snapshots to a time-series dataset (BigQuery, DuckDB, pandas) and analyze how quickly repositories rise and fall on the trending page, or how trending topics shift over months.

***

### Error Handling

- **Transient network errors** (timeouts, connection resets): retried up to 3 times with 2-second exponential backoff before the actor fails.
- **HTTP 4xx errors** (except 429 Too Many Requests): logged and treated as permanent failures — the actor will call `Actor.fail()` with a descriptive message.
- **GitHub markup changes**: if the HTML parser finds no `article.Box-row` elements, it logs a warning and exits cleanly rather than pushing empty or malformed data.
- **Invalid inputs**: `date_range` values outside `daily`/`weekly`/`monthly` cause an immediate graceful failure with a descriptive error message.

***

### Rate Limiting & Politeness

GitHub does not publish a rate limit for the public trending page. The actor:

- Sends a single HTTP request per run (the trending page is one URL).
- Uses a descriptive `User-Agent` string that identifies the actor.
- Does **not** paginate or crawl linked repositories.

The total runtime for a single run is typically under 5 seconds.

***

### Technical Details

- **Language**: Python 3.12
- **HTTP client**: [httpx](https://www.python-httpx.org/) (async)
- **HTML parser**: [BeautifulSoup4](https://www.crummy.com/software/BeautifulSoup/) with Python's built-in `html.parser`
- **Apify SDK**: [apify](https://pypi.org/project/apify/) >= 2.0.0
- **Docker base image**: `apify/actor-python:3.12`
- **Concurrency**: single async request (GitHub Trending is one page)

#### Project Structure

```
github-trending/
├── .actor/
│   ├── actor.json          # Actor metadata and dataset view configuration
│   └── INPUT_SCHEMA.json   # Input parameter schema for the Apify UI
├── src/
│   ├── __init__.py
│   └── main.py             # Actor entry point, HTTP fetch, HTML parsing
├── Dockerfile
├── requirements.txt
└── README.md
```

# Actor input Schema

## `language` (type: `string`):

Filter by programming language slug (e.g. 'python', 'javascript', 'rust', 'c++'). Leave empty to show all languages. Use the slug as it appears in GitHub Trending URLs.

## `date_range` (type: `string`):

Time window for trending calculations. 'daily' shows repositories that gained the most stars today; 'weekly' and 'monthly' extend that window.

## `spoken_language` (type: `string`):

Filter repositories by spoken (human) language of the README and description. Use an ISO 639-1 two-letter language code (e.g. 'en' for English, 'zh' for Chinese, 'es' for Spanish). Leave empty for all spoken languages.

## `max_repos` (type: `integer`):

Maximum number of repositories to return. GitHub Trending shows at most 25 repositories per page, so this is capped at 25.

## Actor input object example

```json
{
  "language": "python",
  "date_range": "daily",
  "spoken_language": "en",
  "max_repos": 25
}
```

# Actor output Schema

## `results` (type: `string`):

Scraped results stored in the default dataset

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("emperor1978/github-trending-tracker").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("emperor1978/github-trending-tracker").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call emperor1978/github-trending-tracker --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,emperor1978/github-trending-tracker"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/SceGVe7ot3edxSAZw/builds/TBoWapHhahN1KxP8U/openapi.json