Aller au contenu
FR
Obtenir une clé API
Parcourir la documentation

Référence API

Temps réel et asynchrone

Recevez les résultats dans la réponse ou soumettez une tâche pour les récupérer plus tard. Choisissez comment votre application ou votre agent attend le traitement.

Sur cette page

Choisir un mode de requête

Google Search et YouTube Data acceptent les deux modes. YouTube Download nécessite async, Batch ou Bulk ; realtime n’est pas pris en charge. Les paramètres de la source restent identiques lorsque vous passez de realtime à async.

ModeQuand l’utiliserCe que vous recevez
RealtimeLe résultat de recherche est nécessaire pendant l’interaction en cours.Le corps du résultat dans la même réponse HTTP.
AsyncLe traitement doit continuer après la déconnexion de votre processus, ou vous téléchargez des médias.Un identifiant de tâche immédiatement ; l’état et les résultats se récupèrent séparément.
Cycle de vie d’une requête
Realtime  POST data.flashdata.dev/v1/queries/realtime → résultats
Async     POST data.flashdata.dev/v1/queries          → identifiant de tâche
          GET  api.flashdata.dev/v2/jobs/{id}         → état
          GET  api.flashdata.dev/v2/jobs/{id}/results → résultats

Envoyer une requête

Définissez FLASHDATA_API_KEY avec une clé autorisant google_search. Choisissez realtime ou async ; chaque soumission lance une recherche facturable. Conservez les scripts, reçus et résultats dans un même nouveau dossier de travail.

Les exemples Python utilisent Python 3.10+ et Requests. Chaque script s’exécute indépendamment et lit les fichiers enregistrés aux étapes précédentes. L’alternative cURL nécessite Bash, cURL 7.76+ et jq.

Python · installer une seule fois
python3 -m pip install requests

Realtime : recevoir le résultat immédiatement

POST /v1/queries/realtime renvoie status: done et un tableau results. Lisez result.json ; aucun suivi périodique de l’état n’est nécessaire.

Enregistrez le fichier sous le nom realtime.py, puis exécutez python3 realtime.py.

realtime.py
import json
import os
from pathlib import Path

import requests

response = requests.post(
    "https://data.flashdata.dev/v1/queries/realtime",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    json={"source": "google_search", "query": "battery recycling research", "params": {"num": 5}},
    timeout=120, allow_redirects=False,
)
response.raise_for_status()
result = response.json()
Path("result.json").write_text(json.dumps(result, indent=2), encoding="utf-8")
print(json.dumps(result, indent=2))

Async : enregistrer le reçu de la tâche

POST /v1/queries renvoie un reçu de tâche en attente, pas les résultats de recherche. Enregistrez submission.json, puis utilisez les requêtes d’état et de résultat ci-dessous.

Enregistrez le fichier sous le nom submit_async.py, puis exécutez python3 submit_async.py.

submit_async.py
import json
import os
from pathlib import Path

import requests

response = requests.post(
    "https://data.flashdata.dev/v1/queries",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    json={"source": "google_search", "query": "battery recycling research", "params": {"num": 5}},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
result = response.json()
Path("submission.json").write_text(json.dumps(result, indent=2), encoding="utf-8")
print(json.dumps(result, indent=2))
Champs du reçu · exemple abrégé
{
  "id": "job_EXAMPLE",
  "source": "google_search",
  "status": "pending"
}

Vérifier une tâche asynchrone

Lisez job.status avec l’identifiant de submission.json. Pour pending ou processing, respectez le délai Retry-After avant la prochaine vérification ; Python l’affiche et cURL l’enregistre dans status-headers.txt. Si aucun délai n’est fourni, espacez progressivement les appels. Une requête d’état réussie ne signifie pas que la tâche est terminée.

job.statusAction suivante
pending / processingAttendez, puis vérifiez à nouveau le même identifiant de tâche.
completedRécupérez le résultat enregistré.
failedLisez job.error. Corrigez la cause avant de soumettre une nouvelle tâche.

Enregistrez le fichier sous le nom job_status.py, puis exécutez python3 job_status.py.

job_status.py
import json
import os
from pathlib import Path

import requests

job_id = json.loads(Path("submission.json").read_text(encoding="utf-8"))["id"]
response = requests.get(
    f"https://api.flashdata.dev/v2/jobs/{job_id}",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
Path("job.json").write_text(json.dumps(response.json(), indent=2), encoding="utf-8")
print(json.dumps(response.json()["job"], indent=2))
print("Retry-After:", response.headers.get("Retry-After", "not provided"))

Récupérer le résultat d’une tâche terminée

Exécutez cette étape lorsque job.status vaut completed. Par défaut, la réponse des résultats est 302 : Location contient une URL de stockage signée. Les deux requêtes ci-dessous transmettent la clé API uniquement à FlashData et enregistrent le JSON d’origine dans result.json. Pour YouTube Download, ce JSON décrit le média livré dans votre stockage ; il ne contient pas le fichier vidéo ou audio.

Enregistrez le fichier sous le nom job_result.py, puis exécutez python3 job_result.py.

job_result.py
import json
import os
from pathlib import Path

import requests

receipt = json.loads(Path("submission.json").read_text(encoding="utf-8"))
job_id = receipt["id"]
response = requests.get(
    f"https://api.flashdata.dev/v2/jobs/{job_id}/results",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
if response.status_code != 302:
    raise RuntimeError(f"Expected a result redirect, got {response.status_code}")
url = response.headers["Location"]
if not url.startswith("https://"):
    raise ValueError("Expected an HTTPS storage URL")

# A separate request: no FlashData key is sent to storage.
result = requests.get(url, timeout=120)
result.raise_for_status()
data = result.json()  # Requests automatically decodes Content-Encoding: gzip.
Path("result.json").write_text(json.dumps(data, indent=2), encoding="utf-8")
print(json.dumps(data, indent=2))

Gérer les délais et les échecs

SituationAction
Délai d’attente dépassé à la soumissionUn POST a peut-être déjà été accepté. Vérifiez votre reçu enregistré et l’historique du compte avant de le renvoyer ; répéter un POST peut créer de nouvelles tâches facturables.
409 · result_not_readyContinuez à vérifier l’état périodiquement. Ne créez pas une autre tâche.
422 · result_not_readyLa tâche a échoué. Lisez job.error avant de réessayer.
429Respectez Retry-After ou retry_after ; réduisez la fréquence des soumissions lorsque la capacité de tâches en attente est atteinte.
410 · result_expiredLes résultats stockés expirent 24 heures après la fin du traitement. Utilisez votre copie enregistrée.