API Documentation

Integra rankings de Trap Cubano en tu aplicacion en menos de 5 minutos.

Quick Start

1. Obtener API Key

Contacta a info@top50trapcubano.com para solicitar tu API key gratuita. Formato: t50_xxxxx...

2. Tu primera request

$ curl -X GET https://api.top50trapcubano.com/api/v1/charts/top50-trapcubano/ranking/current \
  -H "X-API-Key: t50_YOUR_KEY"

3. Parsear la respuesta

{
  "chart": "Top50 TrapCubano",
  "week_start": "2026-02-03",
  "week_end": "2026-02-10",
  "rankings": [
    {
      "position": 1,
      "title": "Nombre del Video",
      "channel_name": "Nombre del Canal",
      "view_count": 2450000,
      "score": 98.5
    }
  ]
}

Autenticacion

Todas las requests requieren el header X-API-Key. 

X-API-Key: t50_your_key_here

Tu API key tiene un tier asignado (free, pro, label) que determina:

  • • Freshness: Tiempo de delay en los datos (12h / 1h / 15min)
  • • Rate limit: Requests por minuto (30 default, configurable)

Endpoints

GET /api/v1/charts/{chart_slug}/ranking/current

Obtener el ranking actual de un chart.

Chart Slugs

  • top50-trapcubano — Top 50 Trap Cubano
  • nuevos-talentos-trapcubano — Nuevos Talentos

Headers requeridos

  • X-API-Key — Tu API key
POST /api/submit-video

Enviar un video de YouTube para tracking y ranking.

Body (JSON)

{
  "youtube_url": "https://www.youtube.com/watch?v=VIDEO_ID",
  "chart_name": "Top50 TrapCubano"
}
GET /salud

Health check. Devuelve el estado de la API. No requiere autenticacion.

Codigos de Error

Codigo Significado
200Exito
401API key invalida o no proporcionada
403Scope insuficiente para esta operacion
404Chart no encontrado
422URL de YouTube invalida
429Rate limit excedido
500Error interno del servidor

Rate Limits

Cada response incluye headers de rate limit: 

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 29
X-RateLimit-Reset: 1707580800
Tier Rate Limit Data Delay
Free30 req/min12 horas
ProConfigurable1 hora
LabelPremium15 minutos

Ejemplos de Codigo

Python

import requests

API_KEY = "t50_YOUR_KEY"

response = requests.get(
    "https://api.top50trapcubano.com/api/v1/charts/top50-trapcubano/ranking/current",
    headers={"X-API-Key": API_KEY}
)

rankings = response.json()["rankings"]
for r in rankings:
    print(f"#{r['position']} - {r['title']}")

JavaScript (Node.js / Browser)

const response = await fetch(
  "https://api.top50trapcubano.com/api/v1/charts/top50-trapcubano/ranking/current",
  { headers: { "X-API-Key": "t50_YOUR_KEY" } }
);

const data = await response.json();
data.rankings.forEach(r =>
  console.log(`#$${r.position} - $${r.title}`)
);