# GitHub Trending & Topic Scraper (`viralanalyzer/github-trending-by-topic`) Actor

Scrapes GitHub trending repositories by language and date, or searches popular repositories by technical topic (LLM, AI, Agents) with high-speed hybrid extraction.

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

## Pricing

from $1.50 / 1,000 repository scrapeds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## 🚀 GitHub Trending & Topic Scraper — Discover Hot Repos by Topic, Language & Time Window

> 🔗 [View on Apify Store](https://apify.com/viralanalyzer/github-trending-by-topic) | 🇺🇸 English | [🇧🇷 Português](#português)

Extract **trending and popular GitHub repositories** in two modes: scrape the **official GitHub Trending charts** (daily / weekly / monthly, optionally filtered by programming language), or **search popular repositories by topic / technology keyword** (e.g. `llm`, `agents`, `machine-learning`). Pure HTTP — no browser, no GitHub token, and no OAuth required.

### ✨ Features

- 📈 **Official Trending charts** — Scrape `github.com/trending` for daily, weekly, or monthly hot repos
- 🔤 **Language filter** — Narrow trending to a single language (e.g. `python`, `javascript`, `go`, `rust`)
- 🏷️ **Topic / keyword search** — Find the most-starred repos for any technology topic (e.g. `llm`, `generative-ai`, `agents`)
- 🔁 **API + HTML fallback** — Topic mode tries the GitHub Search API first, then auto-falls back to HTML scraping if the API is rate-limited
- ⭐ **Star & fork counts** — Total stars, forks, and (in trending mode) stars gained during the selected period
- ⚡ **Pure HTTP** — Powered by `got-scraping` (dynamic browser-header fingerprinting) + Cheerio; no browser instance needed
- 🔒 **100% anonymous** — No GitHub login, personal access token, or OAuth credentials required
- 🛡️ **Diagnostic guard (UAG-SG)** — On a zero-result run, writes the raw HTML to the Key-Value Store and returns a remediation guide instead of silently succeeding
- 🌍 **Proxy-ready** — Optional proxy configuration to rotate IPs and avoid GitHub rate limits

### 📥 Input

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `mode` | string | ✅ | `"trending"` | `"trending"` (official charts) or `"topic"` (search by keyword) |
| `language` | string | ❌ | `""` | Language filter for trending charts (e.g. `python`, `go`). Only used in `trending` mode |
| `since` | string | ❌ | `"daily"` | Trending period: `daily`, `weekly`, `monthly`. Only used in `trending` mode |
| `topic` | string | ❌ | `"llm"` | Technology topic / keyword to search (e.g. `llm`, `agents`). Only used in `topic` mode |
| `maxItems` | integer | ✅ | `25` | Maximum repositories to scrape (min 5, max 200) |
| `proxyConfiguration` | object | ❌ | `{ "useApifyProxy": true }` | Proxy settings to rotate IPs and avoid rate limits |

#### Input Examples

```json
// Trending mode
{ "mode": "trending", "language": "python", "since": "weekly", "maxItems": 25, "proxyConfiguration": { "useApifyProxy": true } }

// Topic mode
{ "mode": "topic", "topic": "llm", "maxItems": 50, "proxyConfiguration": { "useApifyProxy": true } }
```

### 📤 Output

Each repository is pushed as one dataset item. Field availability depends on the mode and code path used.

| Field | Type | Description |
|---|---|---|
| `repoName` | string | Repository name |
| `owner` | string | Owner / organization login |
| `url` | string | Full repository URL |
| `description` | string | Repository description |
| `language` | string | Primary language. Trending → repo language (fallback `"Markdown/Other"`); Topic API → repo language (fallback `"Other"`); Topic HTML fallback → literal `"GitHub Topic"` |
| `stars` | number | Total star count |
| `forks` | number | Total fork count (`0` in the topic HTML fallback) |
| `starsAdded` | number | Stars gained during the selected period (**trending mode only**) |
| `scrapedAt` | string | ISO 8601 timestamp |

#### Output Example

```json
{
  "repoName": "awesome-llm-apps",
  "owner": "Shubhamsaboo",
  "url": "https://github.com/Shubhamsaboo/awesome-llm-apps",
  "description": "Collection of awesome LLM apps with AI Agents and RAG.",
  "language": "Python",
  "stars": 38214,
  "forks": 4127,
  "starsAdded": 612,
  "scrapedAt": "2026-06-06T12:00:00.000Z"
}
```

> In topic mode, `starsAdded` is omitted; the topic HTML fallback also sets `forks` to `0` and `language` to `"GitHub Topic"`.

#### Zero-Result Diagnostic Output

If a run extracts no repositories, the actor does **not** push an empty success. It saves the raw HTML to the Key-Value Store (key `debug-github-html`) and pushes a single diagnostic record with `setup_status: "DIAGNOSTIC_GUIDE"`, a `message` explaining likely causes (IP rate-limited, language not trending today, or topic keyword with no match), and a `remediation_steps` array (enable a proxy, verify the language value, try a generic topic, inspect the saved HTML).

### 📋 Use Cases

- **Tech trend monitoring** — Track which repos are exploding on the daily/weekly/monthly charts
- **Topic discovery** — Find the top-starred projects for any keyword (`llm`, `agents`, `rag`, `cli`)
- **Content & newsletters** — Auto-source "trending this week" lists for blogs and digests
- **Investment / scouting signals** — Use `starsAdded` momentum to detect fast-rising projects
- **Dataset building** — Collect repository metadata for analysis, dashboards, or ML features

### ❓ FAQ

**Q: What is the difference between the two modes?**
A: `trending` scrapes the official `github.com/trending` charts (supports a `language` filter and a `since` time window: daily/weekly/monthly). `topic` searches the most-starred repositories for a keyword via the GitHub Search API, with an HTML fallback to `github.com/topics/<keyword>` if the API is unavailable.

**Q: Do I need a GitHub API token or login?**
A: No. The actor runs 100% anonymously — no OAuth, personal access token, or account is required. Topic mode uses GitHub's public search endpoint with no authentication, and because unauthenticated requests are rate-limited, it automatically falls back to HTML scraping when the limit is hit.

**Q: Why is `starsAdded` missing in topic mode, and why does `language` sometimes say "GitHub Topic"?**
A: "Stars gained during the period" only exists on the official Trending charts, so `starsAdded` is trending-only. In the topic HTML fallback the per-repo language is not reliably available, so `language` is set to the literal `"GitHub Topic"`; in trending mode, repos with no detected language (e.g. docs-only) fall back to `"Markdown/Other"`.

**Q: My run returned 0 items — what happened?**
A: GitHub may have rate-limited your IP, the language might not be trending today, or the topic keyword may not match any repository. The actor saves the raw HTML to the `debug-github-html` Key-Value Store key and returns a remediation guide. Enabling `proxyConfiguration` usually resolves rate-limit issues.

**Q: How many repositories can I get per run?**
A: Between 5 and 200 (`maxItems`). Topic API mode caps the page size at 100 per the GitHub Search API.

### 💰 Pricing

This actor uses **Pay-Per-Event (PPE)** pricing with a single billable event:

| Event | When it fires |
|---|---|
| `repo-scraped` | Once per repository successfully extracted and pushed |

You are charged only for repositories actually returned — diagnostic (zero-result) runs do not bill the `repo-scraped` event, and the actor owner's own runs skip billing automatically. For current per-event rates, see the live pricing on the actor page: **[apify.com/viralanalyzer/github-trending-by-topic](https://apify.com/viralanalyzer/github-trending-by-topic)**.

### 🔗 Related Actors

- [arXiv Paper Intelligence](https://apify.com/viralanalyzer/arxiv-paper-intelligence) — Academic research monitoring
- [TradingView Screener](https://apify.com/viralanalyzer/tradingview-screener) — Technical analysis & market scanner
- [RSS News Intelligence](https://apify.com/viralanalyzer/rss-news-intelligence) — News & feed aggregation
- [Yahoo Finance Intelligence](https://apify.com/viralanalyzer/yahoo-finance-intelligence) — Stock quotes & fundamentals

### 📝 Changelog

#### v1.0 (Current)

- ✅ Dual-mode extraction: official Trending charts + topic/keyword search
- ✅ Language filter and daily/weekly/monthly time windows for trending
- ✅ GitHub Search API in topic mode with automatic HTML fallback
- ✅ Stars, forks, and period stars-added (trending) extraction
- ✅ Pure HTTP via `got-scraping` + Cheerio (no browser, no token)
- ✅ Universal Autocheck Guard (UAG-SG): zero-result diagnostics + raw HTML capture
- ✅ Proxy support to avoid GitHub rate limits
- ✅ PPE billing via `repo-scraped` with owner-skip

***

<a name="português"></a>

## 🚀 GitHub Trending & Topic Scraper — Descubra Repositórios em Alta por Tópico, Linguagem & Período

> [🇺🇸 English](#-github-trending--topic-scraper--discover-hot-repos-by-topic-language--time-window) | 🇧🇷 Português

Extraia **repositórios do GitHub em alta e populares** em dois modos: raspe as **listas oficiais de Trending do GitHub** (diário / semanal / mensal, opcionalmente filtrado por linguagem), ou **busque repositórios populares por tópico / palavra-chave de tecnologia** (ex: `llm`, `agents`, `machine-learning`). HTTP puro — sem navegador, sem token do GitHub e sem OAuth.

### ✨ Funcionalidades

- 📈 **Listas oficiais de Trending** — Raspe `github.com/trending` para repos em alta diário, semanal ou mensal
- 🔤 **Filtro por linguagem** — Restrinja o trending a uma única linguagem (ex: `python`, `javascript`, `go`, `rust`)
- 🏷️ **Busca por tópico / palavra-chave** — Encontre os repos mais estrelados para qualquer tópico de tecnologia (ex: `llm`, `generative-ai`, `agents`)
- 🔁 **API + fallback HTML** — O modo tópico tenta a API de Busca do GitHub primeiro e, se houver rate limit, cai automaticamente para scraping HTML
- ⭐ **Contagem de estrelas & forks** — Total de estrelas, forks e (no modo trending) estrelas ganhas no período selecionado
- ⚡ **HTTP puro** — Usa `got-scraping` (fingerprinting dinâmico de cabeçalhos de navegador) + Cheerio; sem instância de navegador
- 🔒 **100% anônimo** — Sem login, token de acesso pessoal ou credenciais OAuth do GitHub
- 🛡️ **Guard de diagnóstico (UAG-SG)** — Em runs com zero resultados, salva o HTML bruto no Key-Value Store e retorna um guia de remediação em vez de "suceder" vazio
- 🌍 **Pronto para proxy** — Configuração de proxy opcional para rotacionar IPs e evitar rate limits do GitHub

### 📥 Entrada

| Parâmetro | Tipo | Obrigatório | Padrão | Descrição |
|---|---|---|---|---|
| `mode` | string | ✅ | `"trending"` | `"trending"` (listas oficiais) ou `"topic"` (busca por palavra-chave) |
| `language` | string | ❌ | `""` | Filtro de linguagem para o trending (ex: `python`, `go`). Usado apenas no modo `trending` |
| `since` | string | ❌ | `"daily"` | Período do trending: `daily`, `weekly`, `monthly`. Usado apenas no modo `trending` |
| `topic` | string | ❌ | `"llm"` | Tópico / palavra-chave de tecnologia a buscar (ex: `llm`, `agents`). Usado apenas no modo `topic` |
| `maxItems` | inteiro | ✅ | `25` | Máximo de repositórios a raspar (mín. 5, máx. 200) |
| `proxyConfiguration` | objeto | ❌ | `{ "useApifyProxy": true }` | Configuração de proxy para rotacionar IPs e evitar rate limits |

#### Exemplos de Entrada

```json
// Modo trending
{ "mode": "trending", "language": "python", "since": "weekly", "maxItems": 25, "proxyConfiguration": { "useApifyProxy": true } }

// Modo tópico
{ "mode": "topic", "topic": "llm", "maxItems": 50, "proxyConfiguration": { "useApifyProxy": true } }
```

### 📤 Saída

Cada repositório é enviado como um item do dataset. A disponibilidade dos campos depende do modo e do caminho de código usado.

| Campo | Tipo | Descrição |
|---|---|---|
| `repoName` | string | Nome do repositório |
| `owner` | string | Login do dono / organização |
| `url` | string | URL completa do repositório |
| `description` | string | Descrição do repositório |
| `language` | string | Linguagem principal. Trending → linguagem do repo (fallback `"Markdown/Other"`); Tópico API → linguagem do repo (fallback `"Other"`); Tópico HTML → literal `"GitHub Topic"` |
| `stars` | número | Total de estrelas |
| `forks` | número | Total de forks (`0` no fallback HTML do tópico) |
| `starsAdded` | número | Estrelas ganhas no período selecionado (**apenas modo trending**) |
| `scrapedAt` | string | Timestamp ISO 8601 |

#### Exemplo de Saída

```json
{
  "repoName": "awesome-llm-apps",
  "owner": "Shubhamsaboo",
  "url": "https://github.com/Shubhamsaboo/awesome-llm-apps",
  "description": "Collection of awesome LLM apps with AI Agents and RAG.",
  "language": "Python",
  "stars": 38214,
  "forks": 4127,
  "starsAdded": 612,
  "scrapedAt": "2026-06-06T12:00:00.000Z"
}
```

> No modo tópico, `starsAdded` é omitido; o fallback HTML do tópico também define `forks` como `0` e `language` como `"GitHub Topic"`.

#### Saída de Diagnóstico (Zero Resultados)

Se um run não extrair nenhum repositório, o actor **não** envia um sucesso vazio. Ele salva o HTML bruto no Key-Value Store (chave `debug-github-html`) e envia um único registro de diagnóstico com `setup_status: "DIAGNOSTIC_GUIDE"`, uma `message` explicando as causas prováveis (IP com rate limit, linguagem não está em alta hoje, ou palavra-chave sem correspondência) e um array `remediation_steps` (ativar proxy, verificar o valor da linguagem, tentar um tópico genérico, inspecionar o HTML salvo).

### 📋 Casos de Uso

- **Monitoramento de tendências** — Acompanhe quais repos estão explodindo nas listas diária/semanal/mensal
- **Descoberta por tópico** — Encontre os projetos mais estrelados para qualquer palavra-chave (`llm`, `agents`, `rag`, `cli`)
- **Conteúdo & newsletters** — Gere listas "em alta esta semana" para blogs e digests
- **Sinais de scouting / investimento** — Use o momentum de `starsAdded` para detectar projetos em rápida ascensão
- **Construção de datasets** — Colete metadados de repositórios para análise, dashboards ou features de ML

### ❓ Perguntas Frequentes

**P: Qual a diferença entre os dois modos?**
R: `trending` raspa as listas oficiais `github.com/trending` (suporta filtro `language` e janela de tempo `since`: diário/semanal/mensal). `topic` busca os repositórios mais estrelados para uma palavra-chave via API de Busca do GitHub, com fallback HTML para `github.com/topics/<palavra-chave>` se a API estiver indisponível.

**P: Preciso de um token de API ou login do GitHub?**
R: Não. O actor roda 100% de forma anônima — sem OAuth, token de acesso pessoal ou conta. O modo tópico usa o endpoint público de busca do GitHub sem autenticação e, como requisições sem autenticação têm rate limit, ele cai automaticamente para scraping HTML quando o limite é atingido.

**P: Por que `starsAdded` não aparece no modo tópico, e por que `language` às vezes mostra "GitHub Topic"?**
R: "Estrelas ganhas no período" só existe nas listas oficiais de Trending, então `starsAdded` é exclusivo do trending. No fallback HTML do tópico a linguagem por repo não está disponível de forma confiável, então `language` recebe o literal `"GitHub Topic"`; no modo trending, repos sem linguagem detectada (ex: só docs) recebem o fallback `"Markdown/Other"`.

**P: Meu run retornou 0 itens — o que aconteceu?**
R: O GitHub pode ter aplicado rate limit ao seu IP, a linguagem pode não estar em alta hoje, ou a palavra-chave pode não corresponder a nenhum repositório. O actor salva o HTML bruto na chave `debug-github-html` do Key-Value Store e retorna um guia de remediação. Ativar o `proxyConfiguration` geralmente resolve problemas de rate limit.

**P: Quantos repositórios consigo por run?**
R: Entre 5 e 200 (`maxItems`). O modo tópico via API limita o tamanho da página a 100, conforme a API de Busca do GitHub.

### 💰 Preços

Este actor usa precificação **Pay-Per-Event (PPE)** com um único evento cobrável:

| Evento | Quando dispara |
|---|---|
| `repo-scraped` | Uma vez por repositório extraído e enviado com sucesso |

Você é cobrado apenas pelos repositórios realmente retornados — runs de diagnóstico (zero resultados) não cobram o evento `repo-scraped`, e os runs do próprio dono do actor pulam a cobrança automaticamente. Para os valores por evento vigentes, veja o preço ao vivo na página do actor: **[apify.com/viralanalyzer/github-trending-by-topic](https://apify.com/viralanalyzer/github-trending-by-topic)**.

### 🔗 Actors Relacionados

- [arXiv Paper Intelligence](https://apify.com/viralanalyzer/arxiv-paper-intelligence) — Monitoramento de pesquisa acadêmica
- [TradingView Screener](https://apify.com/viralanalyzer/tradingview-screener) — Análise técnica & scanner de mercado
- [RSS News Intelligence](https://apify.com/viralanalyzer/rss-news-intelligence) — Agregação de notícias & feeds
- [Yahoo Finance Intelligence](https://apify.com/viralanalyzer/yahoo-finance-intelligence) — Cotações & fundamentos de ações

### 📝 Changelog

#### v1.0 (Atual)

- ✅ Extração dual-mode: listas oficiais de Trending + busca por tópico/palavra-chave
- ✅ Filtro por linguagem e janelas diário/semanal/mensal para trending
- ✅ API de Busca do GitHub no modo tópico com fallback HTML automático
- ✅ Extração de estrelas, forks e estrelas-ganhas-no-período (trending)
- ✅ HTTP puro via `got-scraping` + Cheerio (sem navegador, sem token)
- ✅ Universal Autocheck Guard (UAG-SG): diagnóstico de zero resultados + captura de HTML bruto
- ✅ Suporte a proxy para evitar rate limits do GitHub
- ✅ Cobrança PPE via `repo-scraped` com owner-skip

# Actor input Schema

## `mode` (type: `string`):

Choose between official daily/weekly/monthly trending charts or searching popular repositories by topic/technology keyword.

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

Optional programming language to filter official trending charts (e.g. javascript, python, go, rust). Only used in 'trending' mode.

## `since` (type: `string`):

Time window for official trending charts. Only used in 'trending' mode.

## `topic` (type: `string`):

Technology topic or keyword to search (e.g. llm, generative-ai, agents, machine-learning). Only used in 'topic' mode.

## `maxItems` (type: `integer`):

Maximum number of repositories to scrape.

## `proxyConfiguration` (type: `object`):

GitHub reads are lightweight, but using a proxy is recommended to avoid rate limits.

## Actor input object example

```json
{
  "mode": "trending",
  "language": "",
  "since": "daily",
  "topic": "llm",
  "maxItems": 25,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

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

Dataset of all results; each item follows the dataset schema.

# 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("viralanalyzer/github-trending-by-topic").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("viralanalyzer/github-trending-by-topic").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).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 viralanalyzer/github-trending-by-topic --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=viralanalyzer/github-trending-by-topic",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

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