Перейти к содержимому
RU
Ключ API
Обзор документации

Справочник API

YouTube Расширенный поиск API

Получите API-ключ

Восстановление до результатов поиска 700 YouTube по запросу с помощью видеоданных, миниатюр и фильтров поиска.

Создать запрос

Максимальное количество результатов поиска для возврата.

Дополнительные параметры
Возможности
POSThttps://data.flashdata.dev/v1/queries/realtime
Python 3 · requests
python3 -m pip install requests
import json

import requests

api_key = "YOUR_API_KEY"
payload = {
    "source": "youtube_search_extended",
    "query": "python",
    "params": {
        "max_results": 20,
    },
}

response = requests.post(
    "https://data.flashdata.dev/v1/queries/realtime",
    headers={"X-API-Key": api_key, "Accept": "application/json"},
    json=payload,
    timeout=120,
)
response.raise_for_status()
print(json.dumps(response.json(), ensure_ascii=False, indent=2))
Результаты ответа HTTPАутентификация X-API-Key

Параметры

Отправить source и query на высшем уровне. Варианты источника принадлежат params. Факультативные поля можно опустить.

Тело запроса

sourcestring / Обязательно
Настройка на youtube_search_extended.
querystring / Обязательно
Поисковый запрос.
1 то 2 000 персонажиПо умолчанию: Не установлен
paramsobject / Необязательно
Settings для этого запроса.
По умолчанию: {}
callback_urlstring · nullable / Необязательно
Async и пакетные. Публичный HTTPS завершает URL на порте 443, вплоть до символов 2,048. Никаких учетных данных пользователя или фрагмента URL. Omit, используйте null или пустую строку без уведомления. В партии, установите это на каждый запрос, вне парамов.
По умолчанию: Не установлен

Подсчет результатов

params.max_resultsinteger / Необязательно
Запрошенный результат подсчитан. Меньше результатов может быть доступно.
1 то 700, целые числаПо умолчанию: 20

Поисковые фильтры

params.filtersobject · nullable / Необязательно
Факультативная дата загрузки, тип результата, продолжительность, сортировка и фильтры функций. Выберите или используйте null без фильтров.
По умолчанию: Не установлен
params.filters.upload_datestring / Необязательно
Фильтр по дате загрузки.
1 то 2 000 персонажиЦенности: today / last_hour / this_week / this_month / this_yearПо умолчанию: Не установлен
params.filters.typestring / Необязательно
Фильтр по типу результата.
1 то 2 000 персонажиЦенности: video / channel / playlist / movieПо умолчанию: Не установлен
params.filters.durationstring / Необязательно
Фильтр по продолжительности видео в минутах.
1 то 2 000 персонажиЦенности: <4 / 4-20 / >20По умолчанию: Не установлен
params.filters.sort_bystring / Необязательно
Заказ результатов. Выполняйте заказ YouTube по умолчанию.
1 то 2 000 персонажиЦенности: rating / relevance / view_count / upload_dateПо умолчанию: Не установлен
params.filters.360boolean / Необязательно
Установите true, чтобы использовать функцию 360.
true или falseПо умолчанию: Не установлен
params.filters.3dboolean / Необязательно
Установите true, чтобы использовать функцию 3d.
true или falseПо умолчанию: Не установлен
params.filters.4kboolean / Необязательно
Настройте true, чтобы использовать функцию 4k.
true или falseПо умолчанию: Не установлен
params.filters.creative_commonsboolean / Необязательно
Установите true, чтобы потребовать функцию Creative Commons.
true или falseПо умолчанию: Не установлен
params.filters.hdboolean / Необязательно
Настройте true, чтобы использовать функцию hd.
true или falseПо умолчанию: Не установлен
params.filters.hdrboolean / Необязательно
Установите true, чтобы использовать функцию hdr.
true или falseПо умолчанию: Не установлен
params.filters.liveboolean / Необязательно
Настройте true, чтобы использовать функцию live.
true или falseПо умолчанию: Не установлен
params.filters.locationboolean / Необязательно
Настройте true, чтобы использовать функцию определения местоположения.
true или falseПо умолчанию: Не установлен
params.filters.purchasedboolean / Необязательно
Настройте true, чтобы потребовать приобретенную функцию.
true или falseПо умолчанию: Не установлен
params.filters.subtitlesboolean / Необязательно
Установите true, чтобы потребовать функцию субтитров.
true или falseПо умолчанию: Не установлен
params.filters.vr180boolean / Необязательно
Установите true, чтобы использовать функцию vr180.
true или falseПо умолчанию: Не установлен

Ответ

Realtime возвращается status: done. Прочитайте исходный текст на results[0].results; usage.credits Записывает обвинение.

Вывод поиска содержит запрос, totalResults и возвращенные элементы. totalResults подсчитывает элементы этого ответа; это не общее количество соответствующих видео на YouTube.

Прочитайте результат

Сохраните успешный ответ JSON как response.json. Сохраните это как read-response.py и запустите python read-response.py. Он использует только стандартную библиотеку Python и не делает никаких новых запросов.

read-response.py
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 по умолчанию выполняет 20 и принимает 1 к 700. Это один большой поисковый запрос, а не отдельные пакетные задания 700. Большие запросы могут занять больше времени; Async избегает сохранения соединения отправителя открытым.

Фильтры относятся к params.filters. Меньше результатов может быть доступно, а поля с богатыми предметами могут быть null или отсутствовать. Расширенный поиск имеет свой собственный уровень использования.

Все поля ответов
ПолеОписание
sourcestringЗапрошенный источник API.
statusstringДелается, когда запрос в режиме реального времени успешен.
created_atstringВремя создания ответов в формате ISO 8601.
usage.creditsnumberКредиты, взимаемые за запрос, исходя из вашего плана.
results[0].querystringПоисковый запрос.
results[0].totalResultsintegerКоличество возвращенных результатов.
results[0].resultsarrayРезультаты поиска в возвращенном порядке.
results[0].results[].videoIdstringВидео YouTube видео ID.
results[0].results[].titlestringНазвание видео.
results[0].results[].channelstringИмя канала.
results[0].results[].channelIdstring · nullableКанал ID, когда он доступен.
results[0].results[].channelUrlstring · nullableКанал URL, когда он доступен.
results[0].results[].durationnumber · nullableПродолжительность видео в секундах.
results[0].results[].durationStringstring · nullableФорматируемая продолжительность видео при наличии.
results[0].results[].viewCountnumber · nullableПодсчет просмотров при наличии.
results[0].results[].uploadDatestring · nullableДата загрузки, когда она доступна.
results[0].results[].descriptionstring · nullableВыдержка из описания, до символов 500 или null, когда они недоступны.
results[0].results[].thumbnailsarrayМиниатюра URLs и размеры.

Вышеприведенные поля описывают ответ JSON по умолчанию. JSON, простой текст и форматы Markdown.

Async возвращает одну квитанцию о приеме на работу; партия возвращает одну за одну работу запрос. Проверяйте статус каждой работы и извлекайте ее результаты, используя возвращенные ссылки.

Async и пакетный жизненный цикл

Подача возвращает квитанцию, а не результаты. Async создает одну работу; партия возвращает отдельную работу в queries[] на каждый принятый запрос. Отслеживайте и извлекайте каждую работу самостоятельно.

Представить data.flashdata.dev; читать статус работы и результаты api.flashdata.dev С тем же X-API-Key. Связанные базовые примеры API используют Python и cURL.

  1. 1. Сохранить работу IDs

    Держите поля запросов этого источника при переходе на Async. Для Batch поместите каждый запрос в массив запросов объекта JSON. Сохраните все возвращенные работы ID.

    Запрос и получение Async · Batch запросить

  2. 2. Проверьте статус

    GET https://api.flashdata.dev/v2/jobs/{jobId}

    pending / processing: Опрос с задержкой и уважением Retry-After когда присутствует. completed: Принесите результаты. failed: Проверить job.error.

    Читайте job.status, а не статус квитанции о представлении.

    Проверить статус: Python и cURL

    Статус работы API ссылка
  3. 3. Получить результаты

    GET https://api.flashdata.dev/v2/jobs/{jobId}/results

    После завершения аутентификации считывайте результат, а затем возьмите хранилище 302 URL без ключа API. Сохраните JSON в течение часов завершения 24.

    Результаты поиска: Python и cURL · Форматы ответов

    Результат скачивания ссылки API

Опросы и получение существующих результатов не потребляют кредиты запросов. Тайм-аут для голосования не отменяет работу: сохраняйте свой ID вместо того, чтобы подавать дубликат оплачиваемой работы. Коды ошибок и поведение retry.

Вебхуки завершения

Подписаться на запрос

Настройка callback_url на верхнем уровне асинхронного запроса, или Внутри каждого запроса в партии, снаружи params. Отдельного запроса на регистрацию webhook не требуется. Запросы Realtime не отправляют обратные вызовы.

Используйте общедоступный HTTPS URL на порту 443. FlashData POST - уведомление для каждой работы completed или failed; Событие содержит ссылки, а не сам результат.

Признать и проверить

Возвращение 2xx После того, как он принял это событие. Дублировать через delivery_id, Также посланный как X-Delivery-Id. Переадресации не выполняются.

Неудачные поставки с экспоненциальным обратным откатом, вплоть до 8 - полная версия и в большинстве 24 часов после завершения. Продолжайте опросы как запасной вариант.

Обратные звонки не подписаны. Подтвердить работу ID, исходный и терминальный статус через аутентифицированная конечная точка статуса перед обработкой уведомления. Поставка ID предназначена для дедупликации, а не для подтверждения подлинности.

Пример события web-cook и полей
Иллюстративное уведомление о завершении
{
  "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"
    }
  ]
}
ПолеОписание
delivery_idstringСтабильный идентификатор доставки. Дублировать уведомления с использованием этого значения; он также отправляется в заголовке X-Delivery-Id.
idstringРаботать ID.
sourcestringЗапрошенный источник данных.
statusstringзавершены или не выполнены.
linksarrayСтатус и результат ссылки. Уведомления не включают контент результата или ключ API.
links[].relstringсебя или результаты.
links[].hrefstringАбсолютный менеджмент API URL; аутентифицируйтесь с помощью ключа API.
links[].methodstringGET.

Контракт на полный веб-хук и ограничения URL

Восстановление ошибок

Если большой запрос в режиме реального времени отпадает, принятие может быть неопределенным. Проверяйте историю работы перед повторной отправкой. Для последующих больших поисков выберите асинхронизацию и отследите возвращенный ID.

Для аутентификации, баланса, сбоев формата запроса и ограничения скорости используйте общую ссылку на ошибку. Тайм-аут может все еще создать работу; проверьте существующую работу перед повторным использованием.

Ошибки и коды состояния · Когда повторно · Ограничения по ставкам

Пошаговое руководство: Планирование более крупного поиска кандидатов

Цены

Текущие цены и лимиты плана