API Documentation - Italia Che Adora Play

Introduzione

L'API pubblica di Italia Che Adora Play consente l'accesso programmato ai dati di artisti, album e statistiche di riproduzione. Tutte le richieste richiedono una chiave API valida.

Base URL

https://play.italiacheadora.it/api/v1

Autenticazione

Tutte le richieste API devono includere una chiave API valida nell'header X-API-Key o come parametro query api_key.

Esempio con Header

curl -H "X-API-Key: ica_your_api_key_here" \
  https://play.italiacheadora.it/api/v1/artists

Esempio con Query Parameter

curl https://play.italiacheadora.it/api/v1/artists?api_key=ica_your_api_key_here

Rate Limiting

Ogni chiave API ha un limite di richieste configurabile (default: 1000 richieste al giorno). Le richieste che superano il limite riceveranno una risposta 429 Too Many Requests.

Nota: Il rate limit viene resettato ogni 24 ore.

Endpoints

GET /artists

Ottieni la lista di tutti gli artisti.

Query Parameters

Parametro	Tipo	Default	Descrizione
limit	integer	50	Numero massimo di risultati
offset	integer	0	Numero di risultati da saltare
search	string	-	Cerca artisti per nome

Risposta di Successo

{
  "success": true,
  "data": [
    {
      "id": "artist_123",
      "name": "Nome Artista",
      "description": "Descrizione artista",
      "imageUrl": "https://...",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 100,
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}

GET /artists/:id

Ottieni i dettagli di un artista specifico con i suoi album.

Parametri URL

id - ID dell'artista

Risposta di Successo

{
  "success": true,
  "data": {
    "id": "artist_123",
    "name": "Nome Artista",
    "description": "Descrizione artista",
    "imageUrl": "https://...",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z",
    "albums": [
      {
        "id": "album_456",
        "title": "Titolo Album",
        "coverUrl": "https://...",
        "releaseDate": "2024-01-01",
        "price": 10.00
      }
    ]
  }
}

GET /albums

Ottieni la lista di tutti gli album.

Query Parameters

Parametro	Tipo	Default	Descrizione
limit	integer	50	Numero massimo di risultati
offset	integer	0	Numero di risultati da saltare
artistId	string	-	Filtra per ID artista
search	string	-	Cerca album per titolo

Risposta di Successo

{
  "success": true,
  "data": [
    {
      "id": "album_456",
      "title": "Titolo Album",
      "artistId": "artist_123",
      "description": "Descrizione album",
      "coverUrl": "https://...",
      "releaseDate": "2024-01-01",
      "price": 10.00,
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 50,
    "limit": 50,
    "offset": 0,
    "hasMore": false
  }
}

GET /albums/:id

Ottieni i dettagli di un album specifico con le sue tracce (senza link audio).

Parametri URL

id - ID dell'album

Risposta di Successo

{
  "success": true,
  "data": {
    "id": "album_456",
    "title": "Titolo Album",
    "artistId": "artist_123",
    "artist": {
      "id": "artist_123",
      "name": "Nome Artista",
      "imageUrl": "https://..."
    },
    "description": "Descrizione album",
    "coverUrl": "https://...",
    "releaseDate": "2024-01-01",
    "price": 10.00,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z",
    "tracks": [
      {
        "id": "track_789",
        "title": "Titolo Traccia",
        "trackNumber": 1,
        "duration": 180,
        "playCount": 1000
      }
    ]
  }
}

GET /stats/plays

Ottieni il totale delle riproduzioni, con filtri opzionali.

Query Parameters

Parametro	Tipo	Descrizione
artistId	string	Filtra per ID artista
albumId	string	Filtra per ID album
trackId	string	Filtra per ID traccia

Risposta di Successo

{
  "success": true,
  "data": {
    "totalPlays": 15000,
    "filters": {
      "artistId": null,
      "albumId": null,
      "trackId": null
    }
  }
}

GET /stats

Ottieni statistiche generali del sistema.

Risposta di Successo

{
  "success": true,
  "data": {
    "totalArtists": 25,
    "totalAlbums": 100,
    "totalTracks": 500,
    "totalPlays": 15000,
    "topTracks": [
      {
        "id": "track_789",
        "title": "Titolo Traccia",
        "playCount": 1000,
        "album": {
          "id": "album_456",
          "title": "Titolo Album"
        }
      }
    ]
  }
}

Risposte di Errore

Tutti gli errori seguono un formato consistente:

{
  "success": false,
  "error": "Error type",
  "message": "Detailed error message"
}

Codici di Stato HTTP

Codice	Significato
200	OK - Richiesta riuscita
401	Unauthorized - API key mancante o non valida
403	Forbidden - Endpoint non permesso per questa API key
404	Not Found - Risorsa non trovata
429	Too Many Requests - Rate limit superato
500	Internal Server Error - Errore del server

Supporto

Per assistenza o domande sull'API, contatta:

Email: admin@italiacheadora.it