Outlier ricerca video
Cerca i dati archiviati per parola chiave, nicchia, regione e rapporto visualizzazioni-abbonati.
POST
https://api.shortsmonkey.com/v1/videos/outliers/search2 crediti per 1-20 elementi effettivi
Outlier ricerca video#
Cerca i dati archiviati per parola chiave, nicchia, regione e rapporto visualizzazioni-abbonati.
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 | POST | Metodo di richiesta HTTP |
| URL completo | https://api.shortsmonkey.com/v1/videos/outliers/search | Produzione API URL |
| Autenticazione | Authorization: Bearer sm_live_... | Invia la chiave completa solo nell'intestazione |
| Tipo di contenuto | application/json | Il corpo della richiesta utilizza JSON |
| Crediti | 2 crediti per 1-20 elementi effettivi | Le risposte agli errori costano 0 crediti |
Richiedi parametri#
| Nome | Posizione | Tipo | Necessario | Predefinito | Valori o limiti | Descrizione |
|---|---|---|---|---|---|---|
keyword | Corpo JSON | string | NO | — | 1–120 caratteri | Parola chiave abbinata al titolo memorizzato o al testo di nicchia |
niche | Corpo JSON | string | NO | — | 1–80 caratteri | Filtro di nicchia o di categoria |
video_type | Corpo JSON | string | NO | all | shorts / long / all | Tipo di video |
region | Corpo JSON | string | NO | — | 2-16 caratteri | Codice regionale |
max_channel_subscribers | Corpo JSON | integer | NO | — | 0–10,000,000 | Conteggio massimo degli iscritti al canale |
min_views | Corpo JSON | integer | NO | — | 0–1,000,000,000 | Numero minimo di visualizzazioni |
min_vs_ratio | Corpo JSON | number | NO | 10 | 0–100,000 | Rapporto minimo visualizzazioni/iscritti |
time_window | Corpo JSON | string | NO | 7d | 24h / 3d / 7d / 30d | Finestra di pubblicazione video |
limit | Corpo JSON | integer | NO | 20 | 1–50 | Numero massimo di elementi in questa pagina |
all_cursor | Corpo JSON | string | NO | — | data.all_data.next_cursor | Recupera la pagina successiva non filtrata |
filter_cursor | Corpo JSON | string | NO | — | data.filter_data.next_cursor | Recupera la pagina filtrata successiva senza modificare i filtri |
cursor | Corpo JSON | 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 |
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 POST "https://api.shortsmonkey.com/v1/videos/outliers/search" \
-H "Authorization: Bearer $SHORTSMONKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"keyword":"finance","video_type":"all","time_window":"7d","min_vs_ratio":10,"limit":20}'