Saltar al contenido
ES
Obtener clave API
Explorar documentación

Referencia de la API

Tiempo real y modo asíncrono

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.

ModoUsar cuandoLo que recibes
RealtimeSe necesita un resultado de búsqueda en la interacción actual.El cuerpo resultado en la misma respuesta HTTP.
AsyncEl 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.
Solicitar ciclo de vida
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 → resultados

Enviar 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.

Python · instalar una vez
python3 -m pip install requests

Realtime: 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.

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: 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.

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))
Campos de recepción · ejemplo abreviado
{
  "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.statusSiguiente acción
pending / processingEspera, entonces compruebe el mismo trabajo ID otra vez.
completedRecuperar el resultado salvado.
failedLeer job.error. Arreglar la causa antes de enviar nuevo trabajo.

Guardar como job_status.py y ejecutar 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"))

Recuperar 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.

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))

Retrasos y fracasos de la mano

SituaciónQué hacer
Fecha límite de presentaciónUn 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_readyNo creas otro trabajo.
422 · result_not_readyEl trabajo falló. Lea job.error antes de volver a intentarlo.
429Honor Retry-After o retry_after; reducir la tasa de sumisión cuando la capacidad pendiente está llena.
410 · result_expiredLos resultados almacenados expiran las horas 24 después de la terminación. Utilice su copia guardada.