Explorar documentação
Referência da API
Obter resultados na resposta, ou enviar um trabalho e recuperá-los mais tarde. Escolha como sua aplicação ou agente espera pelo trabalho.
Nesta página
Escolha um modo de solicitação
Google Search e YouTube Data suportam ambos os modos. YouTube Download requer assincronia, Batch ou Bulk; não suporta em tempo real. Os parâmetros de origem permanecem os mesmos ao mudar de tempo real para assincronia.
| Modo | Use quando | O que você recebe |
|---|---|---|
| Realtime | Um resultado de busca é necessário na interação atual. | O corpo do resultado na mesma resposta HTTP. |
| Async | O trabalho deve continuar após o processo desligar, ou você está baixando a mídia. | Um trabalho ID imediatamente, buscar status e resultados separadamente. |
Realtime POST data.flashdata.dev/v1/queries/realtime → resultados
Async POST data.flashdata.dev/v1/queries → trabalho ID
GET api.flashdata.dev/v2/jobs/{id} → status
GET api.flashdata.dev/v2/jobs/{id}/results → resultadosEnvie um pedido
Coloque FLASHDATA_API_KEY em uma chave que permite google_search. Escolha em tempo real ou assincronia, cada submissão faz uma busca. Mantenha scripts, recibos e resultados na mesma pasta de trabalho.
Exemplos Python usam Python 3.10+ e Pedidos. Cada script é executado independentemente e lê arquivos salvos de passos anteriores. A alternativa cURL precisa de Bash, cURL 7.76+ e jq.
python3 -m pip install requestsRealtime: obter o resultado agora
POST /v1/queries/realtime retorna status: done e uma matriz de resultados. Leia result.json, nenhuma votação é necessária.
Salve como realtime.py e execute 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.jsonAsyncEconomize um recibo de trabalho
POST /v1/queries retorna um recibo de trabalho pendente, não os resultados da busca. Salve o submission.json e continue com os pedidos de status e resultado abaixo.
Salve como submit_async.py e execute 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"
}verificação um trabalho assincronizado
Leia job.status usando ID em submission.json. Para aguardar ou processar, espere pelo atraso do Retry-After antes de verificar novamente; Python imprime e cURL salva em status-headers.txt. Use o backoff se nenhuma dica for devolvida. Um pedido de status bem sucedido não significa que o trabalho tenha terminado.
| job.status | Próxima ação |
|---|---|
| pending / processing | Espere, então verifique o mesmo trabalho ID novamente. |
| completed | Recupere o resultado salvo. |
| failed | Leia job.error. Conserte a causa antes de enviar um novo trabalho. |
Salve como job_status.py e execute 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.jsonRecupere o resultado finalizado
Execute isso depois que job.status estiver concluído. A resposta padrão dos resultados é 302: localização aponta para um armazenamento assinado URL. Os dois pedidos abaixo mantêm sua chave API no FlashData e salvam o JSON original no result.json. Para YouTube Download, este JSON descreve a mídia entregue em seu armazenamento, não é o arquivo de vídeo ou áudio.
Salve como job_result.py e execute 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.jsonLidar com atrasos e falhas
| Situação | O que fazer |
|---|---|
| Tempo de envio esgotado | Um POST pode já ter sido aceito. verificação seu recibo e histórico de contas antes de reenviar, os POSTs repetidos podem criar novos trabalhos. |
| 409 · result_not_ready | Continue com o status de pesquisa. Não crie outro trabalho. |
| 422 · result_not_ready | O trabalho falhou. Leia job.error antes de tentar novamente. |
| 429 | Honrar Retry-After ou retry_after, reduzir a taxa de submissão quando a capacidade pendente estiver cheia. |
| 410 · result_expired | Resultados armazenados expiram 24 horas após a conclusão. Use sua cópia guardada. |