Explorar documentação
Referência da API
YouTube Busca Extendida API
Recupere até 700 YouTube resultados de busca por solicitação, com detalhes de vídeo, miniaturas e filtros de pesquisa.
Monte uma requisição
Número máximo de resultados de pesquisa a retornar.
Parâmetros avançados
https://data.flashdata.dev/v1/queries/realtimeParâmetros
Enviar source e.. query no nível superior. As opções de origem pertencem a params. Campos opcionais podem ser omitidos.
Corpo da requisição
sourcestring / Obrigatório- Preparar para youtube_search_extended.
querystring / Obrigatório- Pesquisando.1 para 2.000 personagensPredefinição:
Não está pronto paramsobject / Opcional- Settings para este pedido.Predefinição:
{} callback_urlstring · nullable / Opcional- Async e apenas lote. HTTPS conclusão URL na porta 443, até caracteres 2,048. Sem credenciais de usuário ou fragmento URL. Omit, use null ou uma string vazia para nenhuma notificação. Em um lote, coloque isso em cada consulta, fora dos parâmetros.Predefinição:
Não está pronto
Contagem de resultados
params.max_resultsinteger / Opcional- Número de resultados solicitados. Menos resultados podem estar disponíveis.1 para 700, números inteirosPredefinição:
20
Filtros de busca
params.filtersobject · nullable / Opcional- Opcional data de envio, tipo de resultado, duração, triagem e filtros de recursos. Omitir ou usar null sem filtros.Predefinição:
Não está pronto params.filters.upload_datestring / Opcional- Filtrar pela data de envio.1 para 2.000 personagensValores:
today / last_hour / this_week / this_month / this_yearPredefinição:Não está pronto params.filters.typestring / Opcional- Filtrar pelo tipo de resultado.1 para 2.000 personagensValores:
video / channel / playlist / moviePredefinição:Não está pronto params.filters.durationstring / Opcional- Filtrar pela duração do vídeo em minutos.1 para 2.000 personagensValores:
<4 / 4-20 / >20Predefinição:Não está pronto params.filters.sort_bystring / Opcional- Ordenação do resultado. Omita usar a ordem padrão do YouTube.1 para 2.000 personagensValores:
rating / relevance / view_count / upload_datePredefinição:Não está pronto params.filters.360boolean / Opcional- Defina o verdadeiro para exigir o recurso 360.
trueoufalsePredefinição:Não está pronto params.filters.3dboolean / Opcional- Configure para exigir o recurso 3D.
trueoufalsePredefinição:Não está pronto params.filters.4kboolean / Opcional- Configure para exigir o recurso 4k.
trueoufalsePredefinição:Não está pronto params.filters.creative_commonsboolean / Opcional- Definam o que é preciso para o recurso comum criativo.
trueoufalsePredefinição:Não está pronto params.filters.hdboolean / Opcional- Configure para exigir o recurso HD.
trueoufalsePredefinição:Não está pronto params.filters.hdrboolean / Opcional- Configure para exigir o recurso HDR.
trueoufalsePredefinição:Não está pronto params.filters.liveboolean / Opcional- É verdade que precisa de um recurso ao vivo.
trueoufalsePredefinição:Não está pronto params.filters.locationboolean / Opcional- Configure para exigir o recurso de localização.
trueoufalsePredefinição:Não está pronto params.filters.purchasedboolean / Opcional- Defina o verdadeiro para exigir o recurso comprado.
trueoufalsePredefinição:Não está pronto params.filters.subtitlesboolean / Opcional- Defina o verdadeiro para exigir o recurso de legendas.
trueoufalsePredefinição:Não está pronto params.filters.vr180boolean / Opcional- Defina para exigir o recurso vr180.
trueoufalsePredefinição:Não está pronto
Resposta
Realtime retorna status: done. Leia a saída da fonte em results[0].results; usage.credits Registra a acusação.
A saída da pesquisa contém consulta, totalResults e os itens devolvidos. totalResults Conta os itens dessa resposta, não é o número total de vídeos correspondentes. YouTube.
Leia o resultado
Salve a resposta JSON bem sucedida como response.json. Guarde isso como read-response.py e execute python read-response.py. Ele usa apenas a biblioteca padrão do Python e não faz nenhum novo pedido.
import json
from pathlib import Path
response = json.loads(Path("response.json").read_text(encoding="utf-8-sig"))
if response.get("status") not in ("done", "completed") or not isinstance(response.get("results"), list):
raise SystemExit("Expected completed result JSON; inspect the response or job status.")
if not response["results"]:
print("[]")
raise SystemExit(0)
result = response["results"][0]
output = [
{"videoId": item.get("videoId"), "title": item.get("title"), "channel": item.get("channel")}
for item in result.get("results", [])
]
print(json.dumps(output, ensure_ascii=False, indent=2))max_results é padrão para 20 e aceita 1 para 700. Este é um pedido de busca maior, não 700 trabalhos em lote separados. Pedidos maiores podem levar mais tempo, assincronia evita manter a conexão do submisso aberto.
Os filtros pertencem ao params.filters. Menos resultados podem estar disponíveis, e campos de itens ricos podem ser null ou ausentes. A busca estendida tem sua própria taxa de uso.
Todos os campos de resposta
| Campo | Descrição |
|---|---|
sourcestring | A fonte API solicitada. |
statusstring | Feito quando o pedido em tempo real for bem sucedido. |
created_atstring | Tempo de criação de resposta no formato ISO 8601. |
usage.creditsnumber | Créditos cobrados pelo pedido, baseado no seu plano. |
results[0].querystring | A busca. |
results[0].totalResultsinteger | Número de resultados retornados. |
results[0].resultsarray | Resultados da pesquisa em sua ordem de retorno. |
results[0].results[].videoIdstring | YouTube vídeo ID. |
results[0].results[].titlestring | Título do vídeo. |
results[0].results[].channelstring | Nome do canal. |
results[0].results[].channelIdstring · nullable | Canal ID quando disponível. |
results[0].results[].channelUrlstring · nullable | Canal URL quando disponível. |
results[0].results[].durationnumber · nullable | Duração do vídeo em segundos. |
results[0].results[].durationStringstring · nullable | Duração de vídeo formatada quando disponível. |
results[0].results[].viewCountnumber · nullable | Veja a contagem quando disponível. |
results[0].results[].uploadDatestring · nullable | Data de envio quando disponível. |
results[0].results[].descriptionstring · nullable | Excerto de descrição, até caracteres 500, ou nulo quando não está disponível. |
results[0].results[].thumbnailsarray | Thumbnail URLs e dimensões. |
Os campos acima descrevem a resposta padrão JSON. JSON, texto simples e formatos Markdown.
Async retorna um recibo de trabalho; lote retorna um por Consulta. Verifique o status de cada trabalho e recupere seus resultados usando os links devolvidos.
Async & ciclo de vida em lote
A submissão devolve um recibo, não resultados. Async cria um trabalho; lote retorna um trabalho separado em queries[] para cada consulta aceita. Rastreie e recupere cada trabalho independentemente.
Submeta-se a data.flashdata.dev; ler status de trabalho e resultados de api.flashdata.dev com o mesmo X-API-Key. Os exemplos básicos do API ligados usam Python e cURL.
1. Salve o trabalho IDs
Mantenha os campos de solicitação desta fonte ao mudar para Async. Para Batch, coloque cada pedido dentro da matriz de consultas de um objeto JSON. Salve todos os trabalhos devolvidos ID.
2. Verifique o status
GET https://api.flashdata.dev/v2/jobs/{jobId}pending/processing: pesquisa com um atraso e respeitoRetry-Afterquando presente.completed: obter resultados.failed: Inspecionejob.error.Leia job.status, não o status do recibo de submissão.
Verifique o status de Python e cURL
Situação do trabalho referência API3. Recupere os resultados
GET https://api.flashdata.dev/v2/jobs/{jobId}/resultsApós a conclusão, autentique o resultado lido, e depois vá buscar o 302 de armazenamento URL sem sua chave API. Salve o JSON dentro de 24 horas de conclusão.
Obter resultados · Python e cURL · Formatos de resposta
Resultado do download da referência API
Pesquisando e buscando resultados existentes não consomem créditos de consulta. Um tempo de votação não cancela o trabalho: mantenha seu ID em vez de enviar duplicado trabalho billable. Códigos de erro e comportamento de repetição.
Webhooks de conclusão
Inscreva-se por consulta
Preparar callback_url no nível superior de um pedido de assincronização, ou dentro de cada consulta em um lote, fora params. Não é necessário nenhum pedido de registro separado. Pedidos Realtime não enviam chamadas de volta.
Use um HTTPS URL público no porto 443. FlashData POSTS uma notificação para cada trabalho chegando completed ou failed; O evento contém links, não o resultado em si.
Reconheça e verifique
Retorne 2xx depois de aceitar o evento. Deduplicar por delivery_id, também enviado como X-Delivery-Id. Redirecionamentos não são seguidos.
Entregas falhadas tentam novamente com retrocesso exponencial, até 8 tenta total e no máximo 24 horas após a conclusão. Continue pesquisando como um retrocesso.
As chamadas não foram assinadas. Confirme o trabalho ID, fonte e status terminal através do Endpoint de status autenticado Antes de processar a notificação. A entrega ID é para deduplicação, não prova de autenticidade.
Exemplo de eventos webhook e campos
{
"delivery_id": "completion:job_example0001",
"id": "job_example0001",
"source": "youtube_search_extended",
"status": "completed",
"links": [
{
"rel": "self",
"href": "https://api.flashdata.dev/v2/jobs/job_example0001",
"method": "GET"
},
{
"rel": "results",
"href": "https://api.flashdata.dev/v2/jobs/job_example0001/results",
"method": "GET"
}
]
}| Campo | Descrição |
|---|---|
delivery_idstring | Identificador de entrega estável. Deduplicar notificações usando este valor; também é enviado no cabeçalho X-Delivery-Id. |
idstring | Trabalho ID. |
sourcestring | Solicitamos fonte de dados. |
statusstring | completo ou fracassado. |
linksarray | Status e links de resultados. Notificações não incluem conteúdo de resultado ou uma chave API. |
links[].relstring | auto ou resultados. |
links[].hrefstring | Gestão absoluta API URL, autentice com sua chave API. |
links[].methodstring | GET. |
Recuperação de erros
Se um grande pedido em tempo real acabar, a aceitação pode ser incerta. Verifique o histórico de trabalho antes de reenviar. Para buscas maiores subsequentes, escolha assincronia e rastreie o ID devolvido.
Para autenticação, equilíbrio, formatação de pedidos e falhas de taxa, use a referência de erro compartilhado. Um intervalo de submissão ainda pode ter criado um trabalho, verificar o trabalho existente antes de tentar novamente.
Erros e códigos de status · Quando tentar novamente · Limites de taxa
Guia passo-a-passo: Planeje uma busca por candidatos maiores