fn_registry/python/functions/datascience/scrape_aliexpress_trending.md

name, kind, lang, domain, version, purity, signature, description, tags, params, output, uses_functions, uses_types, returns, returns_optional, error_type, imports, tested, tests, test_file_path, file_path

name	kind	lang	domain	version	purity	signature	description	tags	params	output	uses_functions	uses_types	returns	returns_optional	error_type	imports	tested	tests	test_file_path	file_path
scrape_aliexpress_trending	function	py	datascience	1.0.0	impure	def scrape_aliexpress_trending(query: str | None = None, category: str | None = None, limit: int = 40, ship_to: str = 'ES') -> list[dict]	Capta productos populares de AliExpress como señal de e-commerce/dropshipping (orders, rating, precio). Hace una request HTTP a la página de listado ordenada por número de pedidos y extrae el JSON embebido en el HTML (window.runParams / _dida_config). Best-effort: ante anti-bot lanza RuntimeError, ante HTML sin JSON devuelve []. NUNCA inventa datos.	aliexpress ecommerce dropshipping trends market-intel datascience	name desc query Texto de búsqueda (ej. 'kitchen gadgets'). Si se da, manda en la URL sobre category. name desc category ID numérico de categoría AliExpress o slug. Ignorado si hay query. None usa un listado 'hot products' genérico. name desc limit Número máximo de productos a devolver. Default 40. name desc ship_to Código de país ISO-2 (ES, US, GB, DE, ...) que fija región y moneda via cookies de AliExpress. Default 'ES'.	Lista de dicts con claves exactas (casan 1:1 con la tabla Postgres aliexpress_trends, sin id/snapshot_date/scraped_at): category (str|None), product_id (str), title (str|None), price (float|None), currency (str|None), orders (int|None), rating (float|None), url (str). Lista vacía si el HTML no traía JSON parseable.				false	error_go_core	requests	false			python/functions/datascience/scrape_aliexpress_trending.py

Ejemplo

import sys, os
sys.path.insert(0, os.path.join("python", "functions"))
from datascience.scrape_aliexpress_trending import scrape_aliexpress_trending

# Top productos por número de pedidos para una búsqueda concreta, enviando a España.
rows = scrape_aliexpress_trending(query="phone holder", limit=20, ship_to="ES")
for r in rows[:3]:
    print(r["title"], "->", r["orders"], "pedidos |", r["price"], r["currency"])

# Cada dict (las 8 claves casan con la tabla aliexpress_trends):
# {"category": "phone holder", "product_id": "100500...", "title": "...",
#  "price": 3.21, "currency": "EUR", "orders": 12000, "rating": 4.8,
#  "url": "https://www.aliexpress.com/item/100500....html"}

Cuando usarla

Cuando necesites una señal de qué productos están vendiendo bien en AliExpress para research de dropshipping o market-intel: detectar tendencias, sourcing de productos ganadores, o alimentar un histórico (tabla aliexpress_trends) que cruce orders / rating / precio por categoría. Úsala antes de decidir un nicho o para vigilar periódicamente una keyword. El output va directo a un INSERT Postgres (las 8 claves coinciden con las columnas no autogeneradas).

Gotchas

• Anti-bot fuerte (CRÍTICO): AliExpress bloquea agresivamente headless/datacenter con captcha (/_____tmd_____/punish), 403/429 y fingerprinting. Desde una IP de datacenter o un patrón de scraping evidente, esta función lanzará RuntimeError con frecuencia. Para extracción fiable y sostenida, la alternativa robusta es el browser MCP/CDP con sesión real (Chrome del usuario, cookies legítimas), no requests. Esta función es la vía barata; si falla repetidamente, sube de nivel.
• JSON embebido volátil: el nombre/estructura del blob (window.runParams, _dida_config_, _init_data_) cambia con frecuencia. Se prueban varios patrones y un walk genérico, pero si AliExpress cambia el layout la función devuelve [] (HTML válido sin JSON parseable) — NO inventa datos. Diferencia clave: RuntimeError = bloqueado; [] = layout cambiado o shell vacío.
• Región/moneda dependen de ship_to: se setean por cookies (aep_usuc_f, intl_locale). Un ship_to no mapeado cae a ES/EUR. El currency devuelto depende de lo que AliExpress decida servir, no se fuerza tras el fetch.
• orders/price/rating pueden venir None si el item no expone ese campo en el JSON (productos nuevos sin ventas, listados sin rating). No asumir no-null.
• Una sola página: devuelve hasta limit items de la primera página de resultados; no pagina. Para más volumen, llamar con queries/categorías distintas.
• Sin reintentos ni rotación de proxy/UA: es una request única con headers fijos. Para uso periódico, orquestar reintentos y backoff fuera de la función.