Parcourir la documentation
Référence API
API de recherche étendue YouTube
Récupérez jusqu’à 700 résultats YouTube par requête, avec les détails des vidéos, les vignettes et des filtres de recherche.
Préparer une requête
Nombre maximal de résultats de recherche à renvoyer.
Paramètres avancés
https://data.flashdata.dev/v1/queries/realtimeParamètres
Envoyez source et query à la racine de l’objet JSON. Placez les options de la source dans params. Vous pouvez omettre les champs facultatifs.
Corps de la requête
sourcestring / Obligatoire- Définissez ce champ sur youtube_search_extended.
querystring / Obligatoire- Requête de recherche.1 à 2 000 caractèresPar défaut :
Non défini paramsobject / Facultatif- Paramètres de cette requête.Par défaut :
{} callback_urlstring · nullable / Facultatif- Async et Batch uniquement. URL HTTPS publique de notification sur le port 443, de 2 048 caractères maximum, sans identifiants ni fragment. Omettez ce champ, ou utilisez null ou une chaîne vide pour désactiver les notifications. Dans un Batch, définissez-le pour chaque requête, en dehors de params.Par défaut :
Non défini
Nombre de résultats
params.max_resultsinteger / Facultatif- Nombre de résultats demandé. Le nombre disponible peut être inférieur.1 à 700, nombres entiersPar défaut :
20
Filtres de recherche
params.filtersobject · nullable / Facultatif- Filtres facultatifs de date de publication, de type de résultat, de durée, de tri et de caractéristiques. Omettez ce champ ou utilisez null pour ne pas appliquer de filtres.Par défaut :
Non défini params.filters.upload_datestring / Facultatif- Filtrez par date de publication.1 à 2 000 caractèresValeurs :
today / last_hour / this_week / this_month / this_yearPar défaut :Non défini params.filters.typestring / Facultatif- Filtrez par type de résultat.1 à 2 000 caractèresValeurs :
video / channel / playlist / moviePar défaut :Non défini params.filters.durationstring / Facultatif- Filtrez par durée de la vidéo en minutes.1 à 2 000 caractèresValeurs :
<4 / 4-20 / >20Par défaut :Non défini params.filters.sort_bystring / Facultatif- Ordre des résultats. Omettez ce champ pour conserver le tri par défaut de YouTube.1 à 2 000 caractèresValeurs :
rating / relevance / view_count / upload_datePar défaut :Non défini params.filters.360boolean / Facultatif- Définissez ce champ sur true pour exiger la caractéristique 360.
trueoufalsePar défaut :Non défini params.filters.3dboolean / Facultatif- Définissez ce champ sur true pour exiger la caractéristique 3d.
trueoufalsePar défaut :Non défini params.filters.4kboolean / Facultatif- Définissez ce champ sur true pour exiger la caractéristique 4k.
trueoufalsePar défaut :Non défini params.filters.creative_commonsboolean / Facultatif- Définissez ce champ sur true pour exiger la caractéristique Creative Commons.
trueoufalsePar défaut :Non défini params.filters.hdboolean / Facultatif- Définissez ce champ sur true pour exiger la caractéristique hd.
trueoufalsePar défaut :Non défini params.filters.hdrboolean / Facultatif- Définissez ce champ sur true pour exiger la caractéristique hdr.
trueoufalsePar défaut :Non défini params.filters.liveboolean / Facultatif- Définissez ce champ sur true pour exiger la caractéristique live.
trueoufalsePar défaut :Non défini params.filters.locationboolean / Facultatif- Définissez ce champ sur true pour exiger la caractéristique location.
trueoufalsePar défaut :Non défini params.filters.purchasedboolean / Facultatif- Définissez ce champ sur true pour exiger la caractéristique purchased.
trueoufalsePar défaut :Non défini params.filters.subtitlesboolean / Facultatif- Définissez ce champ sur true pour exiger la caractéristique subtitles.
trueoufalsePar défaut :Non défini params.filters.vr180boolean / Facultatif- Définissez ce champ sur true pour exiger la caractéristique vr180.
trueoufalsePar défaut :Non défini
Réponse
Le mode temps réel renvoie status: done. Lisez le résultat de la source dans results[0].results; usage.credits indique les crédits facturés.
Le résultat contient query, totalResults et les éléments renvoyés. totalResults compte les éléments de cette réponse ; ce n’est pas le nombre total de vidéos correspondantes sur YouTube.
Lire le résultat
Enregistrez la réponse JSON d’une requête réussie dans response.json. Enregistrez le script ci-dessous dans read-response.py, dans le même dossier, puis exécutez python read-response.py. Il utilise uniquement la bibliothèque standard de Python et n’envoie aucune nouvelle requête.
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 vaut 20 par défaut et accepte de 1 à 700. Il s’agit d’une seule recherche plus volumineuse, pas de 700 tâches Batch distinctes. Les recherches volumineuses peuvent prendre plus de temps ; async évite de garder la connexion du client ouverte.
Placez les filtres dans params.filters. Le nombre de résultats disponibles peut être inférieur à celui demandé, et les champs détaillés peuvent valoir null ou être absents. La recherche étendue possède son propre tarif d’utilisation.
Tous les champs de réponse
| Champ | Description |
|---|---|
sourcestring | Source API demandée. |
statusstring | done lorsque la requête realtime réussit. |
created_atstring | Date et heure de création de la réponse au format ISO 8601. |
usage.creditsnumber | Crédits facturés pour la requête selon votre offre. |
results[0].querystring | Requête de recherche. |
results[0].totalResultsinteger | Nombre de résultats renvoyés. |
results[0].resultsarray | Résultats de recherche dans l’ordre renvoyé. |
results[0].results[].videoIdstring | Identifiant de la vidéo YouTube. |
results[0].results[].titlestring | Titre de la vidéo. |
results[0].results[].channelstring | Nom de la chaîne. |
results[0].results[].channelIdstring · nullable | Identifiant de la chaîne, lorsqu’il est disponible. |
results[0].results[].channelUrlstring · nullable | URL de la chaîne, lorsqu’elle est disponible. |
results[0].results[].durationnumber · nullable | Durée de la vidéo en secondes. |
results[0].results[].durationStringstring · nullable | Durée de la vidéo sous forme lisible, lorsqu’elle est disponible. |
results[0].results[].viewCountnumber · nullable | Nombre de vues, lorsqu’il est disponible. |
results[0].results[].uploadDatestring · nullable | Date de publication, lorsqu’elle est disponible. |
results[0].results[].descriptionstring · nullable | Extrait de la description, de 500 caractères maximum, ou null s’il est indisponible. |
results[0].results[].thumbnailsarray | URL et dimensions des vignettes. |
Les champs ci-dessus décrivent la réponse JSON par défaut. Formats JSON, texte brut et Markdown.
Async renvoie un reçu de tâche ; Batch en renvoie un par requête. Vérifiez l’état de chaque tâche et récupérez ses résultats à l’aide des liens renvoyés.
Cycle de traitement Async et Batch
La soumission renvoie un reçu, pas les résultats. Async crée une tâche ; Batch renvoie une tâche distincte dans queries[] pour chaque requête acceptée. Suivez chaque tâche et récupérez ses résultats séparément.
Soumettez les requêtes à data.flashdata.dev ; lisez l’état et les résultats sur api.flashdata.dev avec la même clé X-API-Key. Les exemples liés dans les bases de l’API utilisent Python et cURL.
1. Enregistrer les identifiants de tâche
Conservez les champs de requête de cette source en passant à Async. Pour Batch, placez chaque requête dans le tableau queries d’un objet JSON. Enregistrez tous les identifiants de tâche renvoyés.
Requête Async et reçu de soumission · Corps de requête Batch
2. Vérifier l’état
GET https://api.flashdata.dev/v2/jobs/{jobId}pending/processing: attendez entre les vérifications et respectezRetry-Afterlorsqu’il est présent.completed: récupérez les résultats.failed: consultezjob.error.Lisez job.status, et non le champ status du reçu de soumission.
Vérifier l’état · Python et cURL
Référence API : état d’une tâche3. Récupérer les résultats
GET https://api.flashdata.dev/v2/jobs/{jobId}/resultsAprès la fin du traitement, authentifiez la requête de lecture du résultat, puis récupérez l’URL de stockage renvoyée par la redirection 302, sans votre clé API. Enregistrez le JSON dans les 24 heures suivant la fin du traitement.
Récupérer les résultats · Python et cURL · Formats de réponse
Référence API : récupération des résultats
La vérification de l’état et la récupération de résultats existants ne consomment aucun crédit de requête. Un délai de vérification dépassé n’annule pas la tâche : conservez son identifiant pour éviter de soumettre des doublons facturables. Codes d’erreur et nouvelles tentatives.
Webhooks de fin de tâche
Configurer chaque requête
Définissez callback_url à la racine d’une requête Async, ou dans chaque requête d’un Batch, en dehors de params. Aucune requête distincte d’enregistrement de webhook n’est nécessaire. Les requêtes Realtime n’envoient pas de notifications.
Utilisez une URL HTTPS publique sur le port 443. FlashData envoie une notification POST pour chaque tâche atteignant l’état completed ou failed ; l’événement contient des liens, pas le résultat lui-même.
Accuser réception et vérifier
Renvoyez 2xx après avoir enregistré durablement l’événement. Dédupliquez à l’aide de delivery_id, également envoyé dans X-Delivery-Id. Les redirections ne sont pas suivies.
Les envois en échec sont retentés avec un délai exponentiel, dans la limite de 8 tentatives au total et au plus tard 24 heures après la fin du traitement. Conservez la vérification périodique de l’état comme solution de secours.
Les notifications ne sont pas signées. Vérifiez l’identifiant, la source et l’état final de la tâche via l’endpoint d’état authentifié avant de traiter la notification. L’identifiant d’envoi sert à la déduplication ; il ne prouve pas l’authenticité.
Exemple d’événement webhook et ses champs
{
"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"
}
]
}| Champ | Description |
|---|---|
delivery_idstring | Identifiant de livraison stable. Utilisez-le pour dédupliquer les notifications ; il est aussi envoyé dans l’en-tête X-Delivery-Id. |
idstring | Identifiant de la tâche. |
sourcestring | Source de données demandée. |
statusstring | completed ou failed. |
linksarray | Liens vers l’état et les résultats. Les notifications ne contiennent ni les résultats ni de clé API. |
links[].relstring | self ou results. |
links[].hrefstring | URL absolue de l’API de gestion ; authentifiez la requête avec votre clé API. |
links[].methodstring | GET. |
Résoudre les erreurs
Si une requête realtime volumineuse dépasse le délai d’attente, sa prise en compte peut être incertaine. Consultez l’historique des tâches avant de la soumettre à nouveau. Pour les recherches volumineuses suivantes, choisissez async et suivez l’identifiant renvoyé.
Pour les erreurs d’authentification, de solde, de format de requête ou de limite de débit, consultez la référence commune des erreurs. Une soumission ayant dépassé le délai d’attente peut tout de même avoir créé une tâche ; vérifiez les tâches existantes avant de réessayer.
Erreurs et codes d’état · Quand réessayer · Limites de débit
Guide étape par étape : Préparer une recherche avec davantage de résultats