浏览文档
API 参考
直接从响应获取结果,或提交任务后再获取。为应用或智能体选择等待任务的方式。
本页内容
选择请求模式
Google 搜索与 YouTube 数据支持两种模式。YouTube 下载需要 Async、Batch 或 Bulk,不支持 Realtime。从 Realtime 切换到 Async 时,来源参数保持一致。
| 模式 | 适用场景 | 返回内容 |
|---|---|---|
| Realtime | 需要在当前交互中获取搜索结果。 | 当前 HTTP 响应中的完整结果。 |
| Async | 需要在进程断开后继续工作,或需要下载媒体。 | 立即返回任务 ID;分别获取状态与结果。 |
Realtime POST data.flashdata.dev/v1/queries/realtime → results
Async POST data.flashdata.dev/v1/queries → job ID
GET api.flashdata.dev/v2/jobs/{id} → status
GET api.flashdata.dev/v2/jobs/{id}/results → results发送请求
将 FLASHDATA_API_KEY 设为具备 google_search 权限的密钥。选择 Realtime 或 Async,每次提交执行一次计费搜索。在同一个新工作目录中保存脚本、回执与结果。
Python 示例使用 Python 3.10+ 与 Requests。各脚本独立运行,读取前面步骤保存的文件。cURL 版本需要 Bash、cURL 7.76+ 和 jq。
python3 -m pip install requestsRealtime:直接获取结果
POST /v1/queries/realtime 返回 status: done 和 results 数组。直接读取 result.json,无需轮询。
保存为 realtime.py,运行 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:保存任务回执
POST /v1/queries 返回 pending 任务回执,不包含搜索结果。保存 submission.json,然后按下文检查状态并获取结果。
保存为 submit_async.py,运行 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"
}检查 Async 任务
用 submission.json 中的 ID 读取 job.status。对于 pending 或 processing,按 Retry-After 延迟后再查;Python 会打印该值,cURL 将其保存到 status-headers.txt。没有提示时使用退避。状态请求成功不代表任务已完成。
| job.status | 下一步 |
|---|---|
| pending / processing | 等待后再检查同一个任务 ID。 |
| completed | 获取已保存的结果。 |
| failed | 读取 job.error,修正原因后再提交新任务。 |
保存为 job_status.py,运行 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.json获取已完成的结果
在 job.status 为 completed 后运行。默认结果响应为 302,Location 指向签名存储 URL。下方两个请求仅向 FlashData 发送 API Key,并将原始 JSON 保存至 result.json。对于 YouTube 下载,这份 JSON 描述已交付到你的存储的媒体,不是视频或音频文件。
保存为 job_result.py,运行 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.json处理延迟与失败
| 情况 | 处理方式 |
|---|---|
| 提交超时 | POST 可能已被接纳。重新提交前检查回执与账户历史;重复 POST 可能创建新的计费任务。 |
| 409 · result_not_ready | 继续检查状态,不要创建另一个任务。 |
| 422 · result_not_ready | 任务失败。重试前读取 job.error。 |
| 429 | 遵守 Retry-After 或 retry_after;等待容量已满时降低提交速率。 |
| 410 · result_expired | 存储结果在完成 24 小时后过期,请使用已保存的副本。 |