Caldo oggi
Leggi l'ultima istantanea hot-video stabile.
GET
https://api.shortsmonkey.com/v1/rankings/hot-today?region=US&tier=all&limit=201 credito per 1-20 articoli effettivi
Caldo oggi#
Leggi l'ultima istantanea hot-video stabile.
Autenticazione#
Invia Authorization: Bearer sm_live_.... Non inserire mai la chiave completa in URL, cookie, corpi, log o analisi.
Freschezza dei dati#
Le classifiche leggono istantanee stabili pubblicate dal lavoratore. Le letture pubbliche non attivano mai un aggiornamento YouTube.
Richiesta#
| Articolo | Valore | Descrizione |
|---|---|---|
| Metodo | GET | Metodo di richiesta HTTP |
| URL completo | https://api.shortsmonkey.com/v1/rankings/hot-today?region=US&tier=all&limit=20 | Produzione API URL |
| Autenticazione | Authorization: Bearer sm_live_... | Invia la chiave completa solo nell'intestazione |
| Tipo di contenuto | Nessun corpo della richiesta | Le richieste GET non hanno un corpo della richiesta |
| Crediti | 1 credito per 1-20 articoli effettivi | Le risposte agli errori costano 0 crediti |
Richiedi parametri#
| Nome | Posizione | Tipo | Necessario | Predefinito | Valori o limiti | Descrizione |
|---|---|---|---|---|---|---|
region | Domanda | string | NO | Tutte le regioni | 2-16 caratteri | Codice regionale come US o JP |
tier | Domanda | string | NO | all | S / A / B / C / all | Filtro di livello caldo |
limit | Domanda | integer | NO | 20 | 1–50 | Numero massimo di elementi in questa pagina |
all_cursor | Domanda | string | NO | — | data.all_data.next_cursor | Recupera la pagina successiva non filtrata |
filter_cursor | Domanda | string | NO | — | data.filter_data.next_cursor | Recupera la pagina filtrata successiva senza modificare i filtri |
cursor | Domanda | string | NO | — | Parametro di compatibilità deprecato | Alias per filter_cursor; non inviarli entrambi |
Campi di risposta di successo#
all_data è una pagina non filtrata dallo snapshot stabile; filter_data è una pagina dello stesso snapshot dopo le impostazioni predefinite dell'endpoint e i filtri delle richieste. Ogni risultato viene impaginato in modo indipendente.
La notazione con punti rappresenta oggetti nidificati e [] rappresenta elementi dell'array. Il numero di abbonati sconosciuti è null con subscriber_count_hidden: true. Una richiesta viene fatturata una volta utilizzando il numero maggiore di articoli restituiti, mai la somma di entrambi i set.
| Sentiero del campo | Tipo | Nullabile | Descrizione |
|---|---|---|---|
data.all_data.items | array<object> | NO | Elementi video non filtrati nella pagina corrente |
data.all_data.items[].video_id | string | NO | ID video YouTube |
data.all_data.items[].title | string | NO | Titolo del video |
data.all_data.items[].video_url | string | NO | YouTube video URL |
data.all_data.items[].channel.id | string | SÌ | ID del canale |
data.all_data.items[].channel.title | string | NO | Titolo del canale |
data.all_data.items[].channel.subscribers | integer | SÌ | Conteggio degli iscritti; null quando nascosto |
data.all_data.items[].channel.subscriber_count_hidden | boolean | NO | Se il conteggio degli iscritti è nascosto |
data.all_data.items[].views | integer | NO | Istantanea del conteggio delle visualizzazioni |
data.all_data.items[].views_to_subscribers_ratio | number | SÌ | Rapporto visualizzazioni/abbonati |
data.all_data.items[].opportunity_score | number | SÌ | Punteggio opportunità |
data.all_data.items[].duration_seconds | integer | NO | Durata del video in secondi |
data.all_data.items[].published_at | string(date-time) | SÌ | Orario di pubblicazione del video in UTC ISO 8601 |
data.all_data.items[].snapshot_at | string(date-time) | SÌ | Orario di raccolta dati |
data.all_data.items[].niche | string | SÌ | Nicchia o categoria |
data.all_data.items[].track | string | SÌ | Identificatore della traccia del set di dati |
data.all_data.items[].region | string | SÌ | Codice regionale |
data.all_data.items[].reasons | array<string> | NO | Ragioni di classifica |
data.all_data.items[].video_type | string | NO | shorts o long |
data.all_data.next_cursor | string | SÌ | Pagina successiva cursor per questo set di risultati; null al termine |
data.filter_data.items | array<object> | NO | Elementi video dopo le impostazioni predefinite e i filtri di richiesta |
data.filter_data.items[].video_id | string | NO | ID video YouTube |
data.filter_data.items[].title | string | NO | Titolo del video |
data.filter_data.items[].video_url | string | NO | YouTube video URL |
data.filter_data.items[].channel.id | string | SÌ | ID del canale |
data.filter_data.items[].channel.title | string | NO | Titolo del canale |
data.filter_data.items[].channel.subscribers | integer | SÌ | Conteggio degli iscritti; null quando nascosto |
data.filter_data.items[].channel.subscriber_count_hidden | boolean | NO | Se il conteggio degli iscritti è nascosto |
data.filter_data.items[].views | integer | NO | Istantanea del conteggio delle visualizzazioni |
data.filter_data.items[].views_to_subscribers_ratio | number | SÌ | Rapporto visualizzazioni/abbonati |
data.filter_data.items[].opportunity_score | number | SÌ | Punteggio opportunità |
data.filter_data.items[].duration_seconds | integer | NO | Durata del video in secondi |
data.filter_data.items[].published_at | string(date-time) | SÌ | Orario di pubblicazione del video in UTC ISO 8601 |
data.filter_data.items[].snapshot_at | string(date-time) | SÌ | Orario di raccolta dati |
data.filter_data.items[].niche | string | SÌ | Nicchia o categoria |
data.filter_data.items[].track | string | SÌ | Identificatore della traccia del set di dati |
data.filter_data.items[].region | string | SÌ | Codice regionale |
data.filter_data.items[].reasons | array<string> | NO | Ragioni di classifica |
data.filter_data.items[].video_type | string | NO | shorts o long |
data.filter_data.next_cursor | string | SÌ | Pagina successiva cursor per questo set di risultati; null al termine |
data.all_data.items[].tier | string | NO | Livello caldo S / A / B / C |
data.filter_data.items[].tier | string | NO | Livello caldo S / A / B / C |
meta.request_id | string | NO | Richiedi l'ID di traccia |
meta.snapshot_id | string | NO | ID istantanea stabile |
meta.snapshot_at | string(date-time) | NO | Timestamp dell'istantanea |
meta.data_status | string | NO | Stato del set di dati |
credits.cost | integer | NO | Crediti effettivi addebitati |
credits.remaining | integer | NO | Crediti rimanenti sul conto |
credits.period_ends_at | string(date-time) | NO | Fine del periodo di credito corrente |
Impaginazione e cursors#
Invia all_data.next_cursor come all_cursor e filter_data.next_cursor come filter_cursor. Gli cursor sono indipendenti, opachi, firmati e validi per 24 ore; legacy cursor è solo un alias per filter_cursor.
ETag#
Le classifiche supportano If-None-Match. Un successo restituisce HTTP 304 con X-Credits-Cost: 0.
Errori e limiti di velocità#
Ogni errore contiene code, inglese stabile message, request_id e details. Tutte le risposte 4xx/5xx costano zero crediti.
| Stato HTTP | Codice | Causa | Azione suggerita |
|---|---|---|---|
| 400 | INVALID_REQUEST | Formato, combinazione o intervallo del parametro non valido | Correggere i parametri utilizzando details.issues |
| 401 | INVALID_API_KEY | La chiave non è valida o è inattiva | Controlla l'intestazione del portatore e lo stato della chiave |
| 402 | SUBSCRIPTION_REQUIRED / CREDITS_EXHAUSTED | L'abbonamento o i crediti non sono disponibili | Controllare il piano, il bilancio e il budget chiave per la sicurezza |
| 429 | RATE_LIMITED | Limite di velocità o concorrenza superato | Riprovare dopo l'intervallo Retry-After |
| 503 | DATA_STALE / SERVICE_UNAVAILABLE | I dati o il servizio sono temporaneamente non disponibili | Riprova più tardi e mantieni request_id |
curl -X GET "https://api.shortsmonkey.com/v1/rankings/hot-today?region=US&tier=all&limit=20" \
-H "Authorization: Bearer $SHORTSMONKEY_API_KEY"