Sfoglia la documentazione
Riferimento API
YouTube Ricerca estesa API
Recupera fino a 700 YouTube risultati di ricerca per richiesta, con dettagli video, miniature e filtri di ricerca.
Crea una richiesta
Numero massimo di risultati di ricerca da restituire.
Parametri avanzati
https://data.flashdata.dev/v1/queries/realtimeParametri
Invia source e query al livello superiore. Le opzioni di origine appartengono in params. I campi opzionali possono essere omessi.
Corpo della richiesta
sourcestring / Obbligatorio- Impostare su youtube_search_extended.
querystring / Obbligatorio- Cerca la query.1 a 2000 caratteriPredefinito:
Non impostato paramsobject / Facoltativo- Settings per questa richiesta.Predefinito:
{} callback_urlstring · nullable / Facoltativo- Async e solo lotto. Completamento HTTPS pubblico URL sulla porta 443, fino a caratteri 2,048. Nessuna credenziali utente o frammentazione URL. Omit, utilizzare null o una stringa vuota per nessuna notifica. In un lotto, impostare questo su ogni query, param esterni.Predefinito:
Non impostato
Conto dei risultati
params.max_resultsinteger / Facoltativo- Conto di risultato richiesto. Possono essere disponibili pochi risultati.1 a 700, numeri interiPredefinito:
20
Cerca filtri
params.filtersobject · nullable / Facoltativo- Data di caricamento opzionale, tipo di risultato, durata, selezione e filtri di funzionalità. Omit o utilizzare null per nessun filtro.Predefinito:
Non impostato params.filters.upload_datestring / Facoltativo- Filtra per data di caricamento.1 a 2000 caratteriValori:
today / last_hour / this_week / this_month / this_yearPredefinito:Non impostato params.filters.typestring / Facoltativo- Filtra per tipo di risultato.1 a 2000 caratteriValori:
video / channel / playlist / moviePredefinito:Non impostato params.filters.durationstring / Facoltativo- Filtra per durata video in pochi minuti.1 a 2000 caratteriValori:
<4 / 4-20 / >20Predefinito:Non impostato params.filters.sort_bystring / Facoltativo- Risultato di ordinazione. Omettere di utilizzare l'ordine predefinito di YouTube.1 a 2000 caratteriValori:
rating / relevance / view_count / upload_datePredefinito:Non impostato params.filters.360boolean / Facoltativo- Impostare true per richiedere la funzione 360.
trueofalsePredefinito:Non impostato params.filters.3dboolean / Facoltativo- Impostare true per richiedere la funzione 3d.
trueofalsePredefinito:Non impostato params.filters.4kboolean / Facoltativo- Impostare true per richiedere la funzione 4k.
trueofalsePredefinito:Non impostato params.filters.creative_commonsboolean / Facoltativo- Impostare true per richiedere la funzione di comuni creativi.
trueofalsePredefinito:Non impostato params.filters.hdboolean / Facoltativo- Impostare true per richiedere la funzione hd.
trueofalsePredefinito:Non impostato params.filters.hdrboolean / Facoltativo- Impostare true per richiedere la funzione hdr.
trueofalsePredefinito:Non impostato params.filters.liveboolean / Facoltativo- Impostare true per richiedere la funzionalità live.
trueofalsePredefinito:Non impostato params.filters.locationboolean / Facoltativo- Impostare true per richiedere la funzione di localizzazione.
trueofalsePredefinito:Non impostato params.filters.purchasedboolean / Facoltativo- Impostare true per richiedere la funzione acquistata.
trueofalsePredefinito:Non impostato params.filters.subtitlesboolean / Facoltativo- Impostare true per richiedere la funzione sottotitoli.
trueofalsePredefinito:Non impostato params.filters.vr180boolean / Facoltativo- Impostare true per richiedere la funzione vr180.
trueofalsePredefinito:Non impostato
Risposta
Realtime restituisce status: done. Leggi l'output sorgente results[0].results; usage.credits registra l'accusa.
L'output di ricerca contiene query, totalResults e gli elementi restituiti. totalResults conta gli elementi di questa risposta; non è il numero totale di video corrispondenti su YouTube.
Leggi il risultato
Salvare la risposta di successo JSON come response.json. Salvare questo come read-response.py ed eseguire pitone read-response.py. Utilizza solo la libreria standard di Python e non fa nuove richieste.
import json
from pathlib import Path
response = json.loads(Path("response.json").read_text(encoding="utf-8-sig"))
if response.get("status") not in ("done", "completed") or not isinstance(response.get("results"), list):
raise SystemExit("Expected completed result JSON; inspect the response or job status.")
if not response["results"]:
print("[]")
raise SystemExit(0)
result = response["results"][0]
output = [
{"videoId": item.get("videoId"), "title": item.get("title"), "channel": item.get("channel")}
for item in result.get("results", [])
]
print(json.dumps(output, ensure_ascii=False, indent=2))max_results predefinisce 20 e accetta 1 a 700. Questa è una richiesta di ricerca più grande, non 700 lavori separati in batch. Le richieste più grandi possono richiedere più tempo; l'asinclinazione evita di tenere aperta la connessione del mittente.
I filtri appartengono a params.filters. Pochi risultati possono essere disponibili, e i campi di articoli ricchi possono essere null o assenti. Extended Search ha il proprio tasso di utilizzo.
Tutti i campi di risposta
| Campo di applicazione | Designazione |
|---|---|
sourcestring | La fonte API richiesta. |
statusstring | fatto quando la richiesta in tempo reale riesce. |
created_atstring | Tempo di creazione di risposta in formato ISO 8601. |
usage.creditsnumber | Crediti a carico della richiesta, in base al tuo piano. |
results[0].querystring | La query di ricerca. |
results[0].totalResultsinteger | Numero di risultati restituiti. |
results[0].resultsarray | Risultati di ricerca nel loro ordine restituito. |
results[0].results[].videoIdstring | YouTube video ID. |
results[0].results[].titlestring | Titolo video. |
results[0].results[].channelstring | Nome del canale. |
results[0].results[].channelIdstring · nullable | Canale ID quando disponibile. |
results[0].results[].channelUrlstring · nullable | Canale URL quando disponibile. |
results[0].results[].durationnumber · nullable | Durata video in pochi secondi. |
results[0].results[].durationStringstring · nullable | Durata video formattata quando disponibile. |
results[0].results[].viewCountnumber · nullable | Visualizza il conteggio quando disponibile. |
results[0].results[].uploadDatestring · nullable | Data di caricamento quando disponibile. |
results[0].results[].descriptionstring · nullable | Descrizione estratto, fino a caratteri 500, o null quando non disponibile. |
results[0].results[].thumbnailsarray | Thumbnail URLs e dimensioni. |
I campi sopra descritti descrivono la risposta predefinita JSON. formati JSON, testo semplice e Markdown.
Async restituisce una ricevuta di lavoro; il lotto restituisce uno per query. Controllare lo stato di ogni lavoro e recuperare i risultati utilizzando i link restituiti.
Async & ciclo di vita in batch
La sottomissione restituisce una ricevuta, non i risultati. Async crea un lavoro; batch restituisce un lavoro separato in queries[] per ogni domanda accettata. Tracciare e recuperare ogni lavoro in modo indipendente.
Inviare a data.flashdata.dev; leggi lo stato del lavoro e i risultati ottenuti api.flashdata.dev con lo stesso X-API-Key. Gli esempi di base API collegati utilizzano Python e cURL.
1. Salvare il lavoro IDs
Mantenere i campi di richiesta di questa fonte quando si passa a Async. Per Batch, inserire ogni richiesta all'interno dell'array query di un oggetto JSON. Salvare ogni lavoro restituito ID.
2. Controllare lo stato
GET https://api.flashdata.dev/v2/jobs/{jobId}pending/processing: sondaggio con ritardo e rispettoRetry-Afterquando presente.completed: risultati di ricerca.failed: ispezionejob.error.Leggi job.status, non lo stato della ricevuta di presentazione.
Stato di controllo · Python e cURL
Stato del lavoro API riferimento3. Risultati di riduzione
GET https://api.flashdata.dev/v2/jobs/{jobId}/resultsDopo il completamento, autenticare il risultato letto, quindi prendere il 302 di archiviazione URL senza la chiave API. Salvare la JSON entro le ore di completamento 24.
Risultati di riduzione · Python e cURL · Formati di risposta
Risultato download API riferimento
L'inquinamento e l'ottenimento dei risultati esistenti non consumano i crediti di query. Un timeout inquinante non cancella il lavoro: mantieni il suo ID invece di presentare il lavoro duplicato fatturabile. Codici di errore e comportamento di riprovazione.
Webhook di completamento
Iscriviti per query
Set Set callback_url al livello superiore di una richiesta asincrona, o dentro ogni query in un lotto, fuori params. Non è richiesta alcuna richiesta di registrazione webhook separata. Le richieste di Realtime non inviano i callback.
Utilizzare un HTTPS URL pubblico sulla porta 443. FlashData POSTs una notifica per ogni lavoro che raggiunge completed o failed; l'evento contiene collegamenti, non il risultato stesso.
Riconoscimento e verifica
Ritorno 2xx dopo aver accettato duramente l'evento. Deduplicato da delivery_id, anche inviato come X-Delivery-Id. I reindirizzamenti non sono seguiti.
Recuperare le consegne non effettuate con backoff esponenziale, fino a 8 tenta totale e al massimo 24 ore dopo il completamento. Continua a inquinare come un fallback.
Le chiamate non sono firmate. Confermare il lavoro ID, lo stato sorgente e terminale attraverso endpoint di stato autenticato prima di elaborare la notifica. La consegna ID è per la deduplica, non la prova di autenticità.
Esempio webhook evento e campi
{
"delivery_id": "completion:job_example0001",
"id": "job_example0001",
"source": "youtube_search_extended",
"status": "completed",
"links": [
{
"rel": "self",
"href": "https://api.flashdata.dev/v2/jobs/job_example0001",
"method": "GET"
},
{
"rel": "results",
"href": "https://api.flashdata.dev/v2/jobs/job_example0001/results",
"method": "GET"
}
]
}| Campo di applicazione | Designazione |
|---|---|
delivery_idstring | Identificatore di consegna stabile. Deduplicare le notifiche utilizzando questo valore; viene inviato anche nell'intestazione X-Delivery-Id. |
idstring | Lavoro ID. |
sourcestring | Fonte di dati richiesta. |
statusstring | completato o fallito. |
linksarray | Collegamenti di stato e di risultato. Le notifiche non includono il contenuto dei risultati o una chiave API. |
links[].relstring | auto o risultati. |
links[].hrefstring | Gestione assoluta API URL; autenticare con la chiave API. |
links[].methodstring | GET. |
Recupero di errore
Se un grande tempo di richiesta in tempo reale fuori, l'accettazione può essere incerta. Controllare la cronologia del lavoro prima di rispedirlo. Per ulteriori grandi ricerche, scegliere asincrona e tracciare il ID restituito.
Per l'autenticazione, l'equilibrio, il formato delle richieste e i guasti dei limiti di velocità, utilizzare il riferimento di errore condiviso. Un timeout di presentazione può ancora aver creato un lavoro; controllare il lavoro esistente prima di riprovare.
Guida passo-passo: Pianifica una ricerca più ampia dei candidati