Обзор документации
Справочник API
Получите результаты в ответ или отправьте работу и получите их позже. Выберите, как ваше приложение или агент ждет работы.
На этой странице
Выберите режим запроса
Google Search и YouTube Data поддерживают оба режима. YouTube Download требует асинхронизации, Batch или Bulk; он не поддерживает реального времени. Параметры источника остаются прежними при переходе из реального времени в асинхронизацию.
| Режим | использовать когда | Что вы получаете |
|---|---|---|
| Realtime | В текущем взаимодействии необходим результат поиска. | Тело результата в том же ответе HTTP. |
| Async | Работа должна продолжаться после того, как ваш процесс отключится, или вы загружаете носители. | Задание ID немедленно; получайте статус и результаты отдельно. |
Realtime POST data.flashdata.dev/v1/queries/realtime результаты
Async POST data.flashdata.dev/v1/queries — работа ID
GET api.flashdata.dev/v2/jobs/{id} статус
GET api.flashdata.dev/v2/jobs/{id}/results РезультатыОтправить запрос
Установите FLASHDATA_API_KEY на ключ, который позволяет использовать google_search. Выберите в режиме реального времени или асинхронизировать; каждый запрос выполняет один оплачиваемый поиск. Храните сценарии, квитанции и результаты в той же новой рабочей папке.
Примеры Python используют Python 3.10+ и Запросы. Каждый скрипт работает независимо и считывает сохраненные файлы с предыдущих шагов. Альтернатива cURL требует Bash, cURL 7.76+ и jq.
python3 -m pip install requestsRealtime: получить результат уже сейчас
POST /v1/queries/realtime возвращает status: done и массив результатов. Читайте 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 возвращает отложенную квитанцию о работе, а не результаты поиска. Сохраните 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"
}Проверить работу асинхрониста
Читайте job.status, используя ID в submission.json. Для ожидания или обработки дождитесь задержки Retry-After, прежде чем снова проверить; Python печатает его, а cURL сохраняет его в status-headers.txt. Используйте backoff, если нет возврата подсказки. Успешный запрос статуса не означает, что работа завершена.
| 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. Ответом на результаты по умолчанию является 302: местоположение указывает на подписанное хранилище URL. Два запроса ниже сохраняют ключ API на FlashData и сохраняют исходный JSON на result.json. Для YouTube Download этот 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 | Honor Retry-After или retry_after; уменьшайте скорость подачи, когда отложенная емкость заполнена. |
| 410 · result_expired | Срок хранения результатов 24 истекает через несколько часов после завершения. Используйте сохраненную копию. |