Parcourir la documentation
Référence API
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.
| Mode | Quand l’utiliser | Ce que vous recevez |
|---|---|---|
| Realtime | Le résultat de recherche est nécessaire pendant l’interaction en cours. | Le corps du résultat dans la même réponse HTTP. |
| Async | Le 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. |
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ésultatsEnvoyer 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.
python3 -m pip install requestsRealtime : 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.
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))curl --fail-with-body --silent --show-error \
'https://data.flashdata.dev/v1/queries/realtime' \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
--header 'Content-Type: application/json' \
--data '{"source":"google_search","query":"battery recycling research","params":{"num":5}}' \
--output result.json &&
jq '{source, status, results, usage}' result.jsonAsync : 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.
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)){
"id": "job_EXAMPLE",
"source": "google_search",
"status": "pending"
}curl --fail-with-body --silent --show-error \
'https://data.flashdata.dev/v1/queries' \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
--header 'Content-Type: application/json' \
--data '{"source":"google_search","query":"battery recycling research","params":{"num":5}}' \
--output submission.json &&
jq '{id, source, status, links}' submission.json{
"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.status | Action suivante |
|---|---|
| pending / processing | Attendez, puis vérifiez à nouveau le même identifiant de tâche. |
| completed | Récupérez le résultat enregistré. |
| failed | Lisez 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.
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"))JOB_ID=$(jq -er '.id' submission.json)
curl --fail-with-body --silent --show-error \
"https://api.flashdata.dev/v2/jobs/$JOB_ID" \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
--dump-header status-headers.txt --output job.json &&
jq '.job | {id, source, status, error}' job.jsonRé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.
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))JOB_ID=$(jq -er '.id' submission.json)
RESULT_URL=$(curl --fail-with-body --silent --show-error \
"https://api.flashdata.dev/v2/jobs/$JOB_ID/results" \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
--output /dev/null --write-out '%{redirect_url}') &&
curl --fail-with-body --silent --show-error --compressed --proto '=https' \
"${RESULT_URL:?Expected a signed result URL}" --output result.json &&
jq '{source, status, results, usage}' result.jsonGérer les délais et les échecs
| Situation | Action |
|---|---|
| Délai d’attente dépassé à la soumission | Un 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_ready | Continuez à vérifier l’état périodiquement. Ne créez pas une autre tâche. |
| 422 · result_not_ready | La tâche a échoué. Lisez job.error avant de réessayer. |
| 429 | Respectez Retry-After ou retry_after ; réduisez la fréquence des soumissions lorsque la capacité de tâches en attente est atteinte. |
| 410 · result_expired | Les résultats stockés expirent 24 heures après la fin du traitement. Utilisez votre copie enregistrée. |