Обзор документации
Справочник API
YouTube Расширенный поиск API
Восстановление до результатов поиска 700 YouTube по запросу с помощью видеоданных, миниатюр и фильтров поиска.
Создать запрос
Максимальное количество результатов поиска для возврата.
Дополнительные параметры
https://data.flashdata.dev/v1/queries/realtimeПараметры
Отправить 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 и не делает никаких новых запросов.
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. Сохранить работу IDs
Держите поля запросов этого источника при переходе на Async. Для Batch поместите каждый запрос в массив запросов объекта JSON. Сохраните все возвращенные работы ID.
2. Проверьте статус
GET https://api.flashdata.dev/v2/jobs/{jobId}pending/processing: Опрос с задержкой и уважениемRetry-Afterкогда присутствует.completed: Принесите результаты.failed: Проверитьjob.error.Читайте job.status, а не статус квитанции о представлении.
Проверить статус: Python и cURL
Статус работы API ссылка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[].methodstring | GET. |
Восстановление ошибок
Если большой запрос в режиме реального времени отпадает, принятие может быть неопределенным. Проверяйте историю работы перед повторной отправкой. Для последующих больших поисков выберите асинхронизацию и отследите возвращенный ID.
Для аутентификации, баланса, сбоев формата запроса и ограничения скорости используйте общую ссылку на ошибку. Тайм-аут может все еще создать работу; проверьте существующую работу перед повторным использованием.
Ошибки и коды состояния · Когда повторно · Ограничения по ставкам
Пошаговое руководство: Планирование более крупного поиска кандидатов