Explorar documentación
Referencia de la API
Recibe los resultados en la respuesta o envía un trabajo para recuperarlos después. Elige cómo espera tu aplicación o agente a que termine el trabajo.
En esta página
Elija un modo de solicitud
Google Search y YouTube Los datos soportan ambos modos. YouTube Download requiere async, Batch o Bulk; no soporta en tiempo real. Los parámetros de origen permanecen iguales al cambiar de tiempo real a async.
| Modo | Usar cuando | Lo que recibes |
|---|---|---|
| Realtime | Se necesita un resultado de búsqueda en la interacción actual. | El cuerpo resultado en la misma respuesta HTTP. |
| Async | El trabajo debe continuar después de que su proceso se desconecte, o usted está descargando medios. | Un trabajo ID inmediatamente; buscar estado y resultados por separado. |
Realtime POST data.flashdata.dev/v1/queries/realtime → resultados
Async POST data.flashdata.dev/v1/queries → trabajo ID
GET api.flashdata.dev/v2/jobs/{id} → status
GET api.flashdata.dev/v2/jobs/{id}/results → resultadosEnviar solicitud
Establecer FLASHDATA_API_KEY a una tecla que permite google_search. Elige en tiempo real o asinc; cada presentación ejecuta una búsqueda facturable. Mantenga scripts, recibos y resultados en la misma nueva carpeta de trabajo.
Los ejemplos Python usan Python 3.10+ y las peticiones. Cada script funciona de forma independiente y lee archivos guardados desde pasos anteriores. La alternativa cURL necesita Bash, cURL 7.76+ y jq.
python3 -m pip install requestsRealtime: obtener el resultado ahora
POST /v1/queries/realtime devuelve status: done y un array de resultados. Lea result.json; no se necesita votación.
Guardar como realtime.py y ejecutar 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: guardar un recibo de trabajo
POST /v1/queries devuelve un recibo de trabajo pendiente, no los resultados de la búsqueda. Guardar submission.json y continuar con las solicitudes de estado y resultados a continuación.
Guardar como submit_async.py y ejecutar 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"
}Compruebe un trabajo asinc
Lea job.status usando el ID en submission.json. Para pendiente o procesamiento, espere el retraso Retry-After antes de comprobar de nuevo; Python lo imprime y cURL lo guarda en status-headers.txt. Use backoff si no hay indicio. Una solicitud de estado exitoso no significa que el trabajo haya completado.
| job.status | Siguiente acción |
|---|---|
| pending / processing | Espera, entonces compruebe el mismo trabajo ID otra vez. |
| completed | Recuperar el resultado salvado. |
| failed | Leer job.error. Arreglar la causa antes de enviar nuevo trabajo. |
Guardar como job_status.py y ejecutar 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.jsonRecuperar el resultado terminado
Corre esto después job.status se completa. La respuesta de los resultados predeterminados es 302: Puntos de ubicación a un almacenamiento firmado URL. Las dos solicitudes que figuran a continuación guardan sus API clave en FlashData y guardar el original JSON a result.json. Para YouTube Descargar, esto JSON describe los medios entregados a su almacenamiento; no es el archivo de vídeo o audio.
Guardar como job_result.py y ejecutar 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.jsonRetrasos y fracasos de la mano
| Situación | Qué hacer |
|---|---|
| Fecha límite de presentación | Un POST puede que ya haya sido aceptado. Compruebe su recibo guardado y historial de cuenta antes de volver a presentar; POST repetidos pueden crear nuevos empleos facturables. |
| 409 · result_not_ready | No creas otro trabajo. |
| 422 · result_not_ready | El trabajo falló. Lea job.error antes de volver a intentarlo. |
| 429 | Honor Retry-After o retry_after; reducir la tasa de sumisión cuando la capacidad pendiente está llena. |
| 410 · result_expired | Los resultados almacenados expiran las horas 24 después de la terminación. Utilice su copia guardada. |