fn_registry/python/functions/datascience/scrape_tiktok_creative.md

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

name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	returns	returns_optional	error_type	imports	params	output	tested	tests	test_file_path	file_path	notes
scrape_tiktok_creative	function	py	datascience	1.0.0	impure	def scrape_tiktok_creative(country: str = 'ES', kind: str = 'hashtag', limit: int = 50, period: int = 7) -> list[dict]	Capta tendencias del TikTok Creative Center (hashtags, canciones, creadores y videos virales con metricas reales) via su API JSON interna creative_radar_api. Headers realistas con requests, paginacion, parseo tolerante a cambios de schema. Devuelve filas 1:1 con la tabla Postgres tiktok_trends. Impure: hace HTTP a un endpoint interno no publico que puede romperse o exigir anti-bot.	tiktok social trends market-intel datascience				false	error_go_core	requests	name desc country Codigo ISO de pais del ranking (ej. 'ES', 'US', 'MX'). El Creative Center segmenta las tendencias por mercado. Default 'ES'. name desc kind Tipo de tendencia: 'hashtag' (default, el mas estable), 'song', 'creator' o 'video'. Cada uno usa un endpoint interno distinto. Empieza por hashtag si no estas seguro. name desc limit Numero maximo de filas a devolver. El endpoint pagina de 50 en 50; la funcion concatena paginas hasta alcanzar limit o agotar resultados. Default 50. name desc period Ventana temporal en dias. Solo acepta 7 (default), 30 o 120 — el endpoint rechaza otros valores con error de validacion.	Lista de dicts con EXACTAMENTE las claves: country (str), kind (str), name (str|None), rank (int|None), views (int|None, BIGINT), growth_pct (float|None), industry (str|None), url (str|None). Mapea 1:1 con la tabla Postgres tiktok_trends (sin id/snapshot_date/scraped_at). Devuelve [] si el endpoint responde OK pero sin items para el segmento. Lanza ValueError (kind/period invalidos) o RuntimeError (403 anti-bot, HTTP de error, JSON invalido, code de error logico).	false			python/functions/datascience/scrape_tiktok_creative.py	ESTRATEGIA: el Creative Center (ads.tiktok.com/business/creativecenter) es una SPA JS-rendered, pero alimenta sus rankings desde una API interna de facto bajo https://ads.tiktok.com/creative_radar_api/v1/popular_trend/... Esta funcion habla directamente con ese endpoint con requests (mucho mas barato que un navegador headless CUANDO responde). El parseo tolera variaciones del schema (data.list, data.hashtags, data.items...) y nombres de campo distintos por kind. REALISMO: en pruebas reales desde un entorno headless/datacenter el endpoint respondio con code=40101 ("no permission") — rechazo anti-bot por falta de los tokens de sesion firmados (anonymous-user-id, user-sign, timestamp) que la SPA genera en cliente y que no se pueden falsear fuera del navegador. La funcion NO inventa datos: en ese caso lanza RuntimeError con un mensaje claro. Se considera el comportamiento esperado, no un bug de la funcion.

Ejemplo

from datascience.scrape_tiktok_creative import scrape_tiktok_creative

# Top 50 hashtags virales en Espana, ultimos 7 dias.
rows = scrape_tiktok_creative(country="ES", kind="hashtag", limit=50, period=7)
# rows[0] -> {
#   "country": "ES", "kind": "hashtag", "name": "fyp", "rank": 1,
#   "views": 12450000, "growth_pct": 42.0, "industry": "Entertainment",
#   "url": "https://ads.tiktok.com/business/creativecenter/hashtag/fyp/pc/en"
# }

# Canciones en tendencia en US, ventana de 30 dias.
songs = scrape_tiktok_creative(country="US", kind="song", limit=20, period=30)

# Las filas casan 1:1 con un INSERT en la tabla Postgres tiktok_trends
# (sin id/snapshot_date/scraped_at, que los pone la BD).

Cuando usarla

Usala cuando necesites market intelligence de TikTok: detectar hashtags, canciones, creadores o productos virales por pais con metricas reales (views, ranking, crecimiento) para alimentar la tabla tiktok_trends, un dashboard de tendencias o un analisis de oportunidad de contenido. Empieza por kind="hashtag" (el endpoint mas estable) antes de probar song/creator/video. Si el fetch HTTP devuelve RuntimeError por anti-bot, baja al browser MCP/CDP del ecosistema.

Gotchas

• El endpoint interno NO es una API publica versionada. creative_radar_api/v1/popular_trend es un contrato de facto que TikTok cambia sin aviso: ruta, parametros, schema del JSON y claves de campo pueden romperse en cualquier deploy. El parseo es tolerante pero no inmune; si TikTok mueve la lista a otra ruta, la funcion devuelve [] o lanza RuntimeError.
• Anti-bot real y frecuente. Desde IPs de datacenter o entornos headless el endpoint suele responder 403 o code=40101 (no permission). Los rankings se sirven solo a clientes con los tokens de sesion firmados que la SPA genera en navegador (anonymous-user-id, user-sign, timestamp). Esos tokens NO se pueden falsear con requests. Verificado en self-test: respondio code=40101.
• Alternativa robusta cuando el HTTP esta bloqueado: usar el browser MCP/CDP del ecosistema (regla flow_replay.md) navegando el Creative Center con una sesion de chrome real, dejando que el cliente genere los tokens, y leyendo el JSON de la respuesta XHR o el DOM renderizado. Es mas caro pero pasa el anti-bot.
• No inventa datos. Si no puede extraer de verdad, lanza una excepcion clara con el codigo HTTP / code logico para diagnostico, en vez de devolver filas falsas.
• growth_pct heuristico: el Creative Center expresa el crecimiento como ratio (0.42) o como porcentaje (42) segun campo/version; la funcion normaliza ratios en [-1, 1] a porcentaje (*100). Si TikTok cambia la convencion, revisar _row_from_item.
• Rate limiting: la paginacion hace una request por pagina de 50. Para limit altos puedes encadenar varias requests rapidas — anade backoff propio si scrapeas muchos paises seguidos para no acelerar el bloqueo.