# VIRALCHART — Sistema de charts virales globales

Sistema PHP/MySQL que extrae canciones virales de fuentes gratuitas/oficiales,
calcula un top 50 por país (y un estimado por ciudad), lo expone vía API JSON,
y genera un código `<iframe>` embebible para cualquier sitio web.

## 1. Instalación

1. Sube toda la carpeta a tu hosting (cPanel: `public_html/viralchart/` o subdominio).
2. Crea la base de datos y ejecuta `sql/schema.sql`.
3. Copia `config.php` y completa:
   - Credenciales de MySQL.
   - `YOUTUBE_API_KEY` (gratis en Google Cloud Console → habilita "YouTube Data API v3").
4. Carga algunas ciudades de ejemplo por país en la tabla `cities` (ver sección 4).
5. En `widget/generar_embed.php`, cambia `$dominio` por tu dominio real.

## 2. Cron jobs (en cPanel: sección "Cron Jobs")

```
0 6 * * *  php /home/tuusuario/public_html/viralchart/cron/fetch_youtube.php
0 6 * * *  php /home/tuusuario/public_html/viralchart/cron/fetch_spotify.php
15 6 * * * php /home/tuusuario/public_html/viralchart/cron/rank_engine.php
```

El de `rank_engine.php` debe correr DESPUÉS de los dos extractores (por eso el
horario 15 minutos más tarde).

## 3. Uso de la API

- `GET /api/top50.php?pais=CO` → top 50 real (Spotify + YouTube combinados) de Colombia.
- `GET /api/top50.php?pais=CO&ciudad=5` → top 50 estimado para la ciudad con id 5.
- `GET /api/top50.php?pais=CO&formato=html` → HTML ya diseñado, listo para iframe.

## 4. Código para incrustar en cualquier web

Visita `widget/generar_embed.php?pais=CO&ciudad=5` (usuario final) y copia el
`<iframe>` que se genera. Ese iframe consulta tu API en vivo, así que se
actualiza solo cada vez que corres los cron jobs.

## 4b. Tendencia y géneros (nuevo)

- **Tendencia (▲ sube / ▼ baja / ● igual / NUEVO)**: se calcula solo comparando
  el ranking de hoy contra el de ayer para la misma canción/país (o ciudad).
  Ya viene incluida en la API (`tendencia`) y en el widget, sin configuración extra.
- **Filtro por género**: reguetón, urbano, afrobeat, champeta, vallenato, popular, corridos.
  - Requiere credenciales gratis de **Spotify Web API** (Client Credentials,
    distintas a la de charts): créalas en
    https://developer.spotify.com/dashboard y complétalas en `config.php`
    (`SPOTIFY_CLIENT_ID` / `SPOTIFY_CLIENT_SECRET`).
  - Corre `cron/fetch_genres.php` después de los otros cron jobs para
    clasificar canciones nuevas (procesa 200 por corrida).
  - Clasifica según los géneros del ARTISTA en Spotify, mapeados a tus 7
    categorías (ajustables en `GENRE_MAP` dentro de `config.php`).
  - Si ya tenías la base de datos creada, corre `sql/migration_generos.sql`.
- Cron job adicional sugerido:
  ```
  30 6 * * * php /home/tuusuario/public_html/viralchart/cron/fetch_genres.php
  ```

## 5. Limitaciones honestas (para que no haya sorpresas)

- **Compatibilidad de hosting**: si tu PHP tiene mysqli sin la extensión
  `mysqlnd` (común en algunos hostings compartidos), los métodos
  `bind_param()` + `get_result()` no existen. Todo el sistema ya está escrito
  usando `mysqli_query()` con valores escapados/tipados en su lugar, así que
  funciona igual en ambos casos.

- **Nivel país = dato real.** Viene directo de YouTube (oficial) y Spotify (vía
  kworb.net, espejo público de Spotify Charts).
- **Nivel ciudad = estimado**, no dato exacto de plataforma. Ninguna fuente
  gratuita da virialidad real por ciudad. Se distribuye el top país usando el
  peso poblacional que tú cargues en la tabla `cities`. El widget lo aclara
  siempre con la etiqueta "estimado".
- **kworb.net puede cambiar su HTML** sin aviso. El parser en
  `fetch_spotify.php` puede necesitar un ajuste si el sitio cambia de
  estructura — te aviso qué revisar si un día deja de traer datos.
- **TikTok y Shazam no están incluidos** porque no tienen API pública gratuita.
  Si más adelante quieres sumarlos con datos reales, la vía es un agregador
  pago (Chartmetric o Soundcharts) — puedo integrarlo después sin rehacer el
  sistema, solo se añade como una fuente más en `chart_snapshots`.

## 6. Estructura de archivos

```
viralchart/
├── config.php                  → credenciales y lista de países
├── sql/schema.sql               → estructura de base de datos
├── cron/fetch_youtube.php       → extractor YouTube (oficial)
├── cron/fetch_spotify.php       → extractor Spotify (vía kworb.net)
├── cron/rank_engine.php         → combina fuentes + calcula ciudades
├── api/top50.php                → endpoint JSON/HTML
└── widget/
    ├── render.php                → diseño visual del ranking
    └── generar_embed.php         → genera el <iframe> para copiar y pegar
```