Lewati ke isi
ID
Dapatkan kunci API
Jelajahi dokumentasi

Referensi API

Realtime dan async

Dapatkan hasil dalam respon, atau mengirimkan pekerjaan dan mengambil mereka nanti. Pilih bagaimana aplikasi atau agenmu menunggu untuk bekerja.

Di halaman ini

Pilih sebuah mode permintaan

Google Search dan YouTube Data mendukung kedua mode tersebut. YouTube Download membutuhkan async, Batch atau Bulk; tidak mendukung realtime. Parameter sumber tetap sama ketika beralih dari real time ke async.

ModeGunakan ketikaApa yang Anda terima
RealtimeHasil pencarian diperlukan dalam interaksi saat ini.Hasil tubuh dalam respon HTTP yang sama.
AsyncPekerjaan harus terus berlanjut setelah proses Anda terputus, atau Anda mengunduh media.Pekerjaan ID segera; mengambil status dan hasil terpisah.
Meminta lifecycle
Realtime POST data.flashdata.dev/v1/queries/realtime hasil
Async     POST data.flashdata.dev/v1/queries          Pekerjaan. ID
          GET  api.flashdata.dev/v2/jobs/{id}         Status ghanbe-type
          GET  api.flashdata.dev/v2/jobs/{id}/results Hasil tersembunyi

Kirim permintaan

Set FLASHDATA_API_KEY ke kunci yang memungkinkan google_search. Pilih realtime atau async; setiap penyerahan menjalankan satu pencarian yang dapat dihitung. Simpan skrip, penerimaan, dan hasil pada folder kerja yang sama.

Python contoh memakai Python 3.10 + dan Permintaan. Setiap skrip berjalan secara independen dan membaca berkas tersimpan dari langkah sebelumnya. The cURL kebutuhan alternatif Bash, cURL 7.76+ dan jq.

Python sekali
python3 -m pip install requests

Realtime: mendapatkan hasilnya sekarang

POST /v1/queries/realtime mengembalikan status: done dan menghasilkan array. Baca result.json; tidak ada polling yang diperlukan.

Simpan sebagai realtime.py dan jalankan 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: simpan tanda terima pekerjaan

POST /v1/queries mengembalikan pekerjaan yang tertunda, bukan hasil pencarian. Simpan submission.json dan lanjutkan dengan status dan permintaan hasil di bawah ini.

Simpan sebagai submit_async.py dan jalankan 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))
Ayat-ayat berikut ini adalah:
{
  "id": "job_EXAMPLE",
  "source": "google_search",
  "status": "pending"
}

Periksa suatu pekerjaan async

Baca job.status menggunakan ID dalam submission.json. Untuk menunda atau memproses, tunggu penundaan Retry-After sebelum memeriksa lagi; Python dan cURL menyimpannya di status-headers.txt. Gunakan backoff jika tidak ada petunjuk yang dikembalikan. Permintaan status yang sukses tidak berarti pekerjaan telah selesai.

job.statusAksi berikutnya
pending / processingTunggu, kemudian periksa pekerjaan yang sama ID lagi.
completedAmbil hasil yang disimpan.
failedBaca job.error. Perbaiki penyebabnya sebelum mengirimkan pekerjaan baru.

Simpan sebagai job_status.py dan jalankan 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"))

Ambil hasil yang komplit

Jalankan ini setelah job.status selesai. Respon hasil baku adalah 302: Lokasi menunjuk ke penyimpanan yang ditandatangani URL. Kedua permintaan di bawah ini menjaga kunci API Anda pada FlashData asli dan menyimpan JSON asli ke result.json. Untuk YouTube Download, ini JSON menggambarkan media dikirim ke penyimpanan Anda; ini bukan video atau berkas audio.

Simpan sebagai job_result.py dan jalankan 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))

Menangani penundaan dan kegagalan

SituasiYang perlu dilakukan
Waktu submisi habisSebuah POST mungkin sudah diterima. Periksa tanda terima dan riwayat akun Anda sebelum mengajukan kembali; POST berulang dapat membuat pekerjaan yang dapat ditagih kembali.
409 · result_not_readyTetap polling status. Jangan membuat pekerjaan lain.
422 · result_not_readyPekerjaan gagal. Baca job.error sebelum mencoba kembali.
429Kehormatan Retry-After atau retry_after; kurangi tingkat pengajuan ketika kapasitas tertunda penuh.
410 · result_expiredHasil tersimpan kadaluarsa 24 jam setelah selesai. Gunakan salinan disimpan Anda.