---
name: fetch_reddit_search
kind: function
lang: py
domain: datascience
version: "1.0.0"
purity: impure
signature: "def fetch_reddit_search(query: str, subreddits: list[str] = None, limit: int = 50, sort: str = \"new\") -> list[dict]"
description: "Busca posts en Reddit via la API JSON publica (sin auth) y los normaliza a un shape comun de market intelligence. Por subreddit (o global si None), GET a search.json con t=year. Tolera errores por subreddit (429, red) continuando con los demas. Requiere User-Agent obligatorio."
tags: [market-intel, reddit, scraping, http, social, demand, impure, datascience]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: [requests]
params:
  - name: query
    desc: "termino de busqueda (ej: 'csv dedupe tool')"
  - name: subreddits
    desc: "lista de subreddits sin prefijo r/ (ej: ['SaaS','Entrepreneur']). Si None o vacio -> busqueda global en todo Reddit"
  - name: limit
    desc: "maximo de resultados por subreddit (o por la busqueda global). Reddit topea ~100"
  - name: sort
    desc: "orden de Reddit: 'new' (default), 'relevance', 'top', 'comments', 'hot'"
output: "list[dict] (puede ser []). Cada fila: {source:'reddit', platform_id:str, title:str, body:str, url:str, author:str, channel:str, created_utc:float, platform_score:int, query:str}"
tested: true
tests:
  - "parser normaliza children al shape exacto"
  - "selftext vacio se mapea a body vacio"
  - "children vacio devuelve lista vacia"
test_file_path: "python/functions/datascience/fetch_reddit_search_test.py"
file_path: "python/functions/datascience/fetch_reddit_search.py"
---

## Ejemplo

```python
from datascience import fetch_reddit_search

# Buscar en subreddits concretos
rows = fetch_reddit_search(
    "csv dedupe tool",
    subreddits=["SaaS", "Entrepreneur"],
    limit=25,
    sort="new",
)
for r in rows[:3]:
    print(r["channel"], r["platform_score"], r["title"])

# Busqueda global (sin subreddits)
rows_global = fetch_reddit_search("i wish there was a tool", limit=50)
```

## Cuando usarla

Usala como primera fase de un pipeline de market intelligence: recolectar
conversaciones reales de Reddit donde la gente expresa necesidades o busca
herramientas. Combina la salida con `score_demand_signal` para puntuar cada
post por senal de demanda. Cubre subreddits de nicho (`subreddits=[...]`) o
escanea todo Reddit (busqueda global).

## Gotchas

- **User-Agent obligatorio**: Reddit devuelve `429 Too Many Requests` si no se
  envia un User-Agent identificable. Esta funcion envia
  `demand_radar/0.1 (registry market-intel)` por defecto.
- **Rate limiting**: la API publica sin auth tiene limites estrictos. Si haces
  muchas llamadas seguidas o pides muchos subreddits, Reddit puede empezar a
  devolver 429. La funcion **tolera** estos fallos por subreddit (try/except) y
  sigue con los demas — un 429 en un subreddit no aborta la busqueda completa,
  simplemente ese subreddit aporta 0 filas.
- **Sin red = lista vacia, no excepcion**: si todas las peticiones fallan,
  devuelve `[]`. Revisa el tamano del resultado, no asumas exito.
- `created_utc` es epoch en segundos (float). `platform_score` son los upvotes
  netos (`ups`), 0 si Reddit no lo provee.
- `t=year` fija la ventana temporal a un ano; no es parametrizable en esta
  version (mantiene la firma simple).