Przejdź do treści
PL
Uzyskaj klucz API
Przeglądaj dokumentację

Dokumentacja API

YouTube Rozszerzone wyszukiwanie API

Uzyskaj klucz API

Pobieraj do 700 YouTube wyniki wyszukiwania na życzenie, ze szczegółami wideo, miniaturkami i filtrami wyszukiwania.

Utwórz żądanie

Maksymalna liczba wyników wyszukiwania do zwrotu.

Parametry zaawansowane
Funkcje
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))
Wyniki w odpowiedzi na HTTPUwierzytelnianie X-API-Key

Parametry

Wyślij source oraz query na najwyższym poziomie. Opcje źródłowe należą do params. Można pominąć pola opcjonalne.

Treść żądania

sourcestring / Wymagane
Ustaw na youtube_search_extended.
querystring / Wymagane
Wyszukaj pytanie.
1 do 2000 znakiDomyślnie: Nieustawione
paramsobject / Opcjonalne
Settings dla tego wniosku.
Domyślnie: {}
callback_urlstring · nullable / Opcjonalne
Async i tylko partia. Publiczne ukończenie HTTPS URL na porcie 443, do znaków 2,048. Brak danych uwierzytelniających użytkownika lub fragmentu URL. Omit, użyj null lub pustego łańcucha bez powiadomienia. W partii, ustawić to na każdym zapytaniu, na zewnątrz params.
Domyślnie: Nieustawione

Liczba wyników

params.max_resultsinteger / Opcjonalne
Wymagana liczba wyników. Może być mniej wyników.
1 do 700, liczby całkowiteDomyślnie: 20

Filtry wyszukiwania

params.filtersobject · nullable / Opcjonalne
Opcjonalnie data wysłania, typ rezultatu, czas trwania, sortowanie i filtry funkcji. Pomiń lub użyj null bez filtrów.
Domyślnie: Nieustawione
params.filters.upload_datestring / Opcjonalne
Filtruj przez datę wysłania.
1 do 2000 znakiWartości: today / last_hour / this_week / this_month / this_yearDomyślnie: Nieustawione
params.filters.typestring / Opcjonalne
Filtruj według typu wyniku.
1 do 2000 znakiWartości: video / channel / playlist / movieDomyślnie: Nieustawione
params.filters.durationstring / Opcjonalne
Filtruj według czasu trwania wideo w minutach.
1 do 2000 znakiWartości: <4 / 4-20 / >20Domyślnie: Nieustawione
params.filters.sort_bystring / Opcjonalne
Rezultat zamówienia. Pomiń użycie domyślnego zamówienia YouTube.
1 do 2000 znakiWartości: rating / relevance / view_count / upload_dateDomyślnie: Nieustawione
params.filters.360boolean / Opcjonalne
Ustaw true, aby wymagać funkcji 360.
true lub falseDomyślnie: Nieustawione
params.filters.3dboolean / Opcjonalne
Ustaw true, aby wymagać funkcji 3d.
true lub falseDomyślnie: Nieustawione
params.filters.4kboolean / Opcjonalne
Ustaw true, aby wymagał funkcji 4k.
true lub falseDomyślnie: Nieustawione
params.filters.creative_commonsboolean / Opcjonalne
Ustaw true, aby wymagać funkcji twórczych commons.
true lub falseDomyślnie: Nieustawione
params.filters.hdboolean / Opcjonalne
Ustaw true, aby wymagać funkcji hd.
true lub falseDomyślnie: Nieustawione
params.filters.hdrboolean / Opcjonalne
Ustaw true, aby wymagać funkcji hdr.
true lub falseDomyślnie: Nieustawione
params.filters.liveboolean / Opcjonalne
Ustaw true, aby wymagała funkcji live.
true lub falseDomyślnie: Nieustawione
params.filters.locationboolean / Opcjonalne
Ustaw true, aby wymagać funkcji lokalizacji.
true lub falseDomyślnie: Nieustawione
params.filters.purchasedboolean / Opcjonalne
Ustaw true, aby wymagać zakupionej funkcji.
true lub falseDomyślnie: Nieustawione
params.filters.subtitlesboolean / Opcjonalne
Ustaw true, aby wymagać funkcji napisy.
true lub falseDomyślnie: Nieustawione
params.filters.vr180boolean / Opcjonalne
Ustaw true, aby wymagać funkcji vr180.
true lub falseDomyślnie: Nieustawione

Odpowiedź

Realtime zwraca status: done. Odczytaj wyjście źródłowe w results[0].results; usage.credits Zapisuje zarzuty.

Wyjście wyszukiwania zawiera zapytanie, totalResults i zwrócone elementy. totalResults liczy te pozycje odpowiedzi; nie jest to całkowita liczba pasujących filmów na YouTube.

Przeczytaj wynik

Zapisz udane odpowiedzi JSON jako response.json. Zapisz to jako read-response.py i uruchom python read-response.py. Wykorzystuje tylko standardową bibliotekę Python i nie składa nowego wniosku.

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 domyślnie obsługuje 20 i akceptuje 1 do 700. Jest to jeden większy wniosek wyszukiwania, a nie 700 oddzielne zadania wsadowe. Większe żądania mogą trwać dłużej; async unika utrzymywania otwartego połączenia składającego.

Filtry należą do params.filters. Mniej wyników może być dostępnych, a bogate pola elementów mogą być null lub nieobecny. Rozszerzone Wyszukiwarka ma swój własny wskaźnik wykorzystania.

Wszystkie pola odpowiedzi
PoleOpis
sourcestringŻądane źródło API.
statusstringzrobić, gdy realtime wniosek się powiedzie.
created_atstringCzas tworzenia odpowiedzi w formacie ISO 8601.
usage.creditsnumberZasługi naliczane za wniosek, w oparciu o twój plan.
results[0].querystringZapytanie o wyszukiwanie.
results[0].totalResultsintegerLiczba zwróconych wyników.
results[0].resultsarrayWyniki wyszukiwania w ich zwróconym porządku.
results[0].results[].videoIdstringYouTube wideo ID.
results[0].results[].titlestringTytuł wideo.
results[0].results[].channelstringNazwa kanału.
results[0].results[].channelIdstring · nullableKanał ID, gdy jest dostępny.
results[0].results[].channelUrlstring · nullableKanał URL, gdy jest dostępny.
results[0].results[].durationnumber · nullableCzas trwania filmu w sekundach.
results[0].results[].durationStringstring · nullableFormatowany czas trwania wideo, o ile jest dostępny.
results[0].results[].viewCountnumber · nullableWyświetl licznik, gdy jest dostępny.
results[0].results[].uploadDatestring · nullableData wysłania, gdy jest dostępna.
results[0].results[].descriptionstring · nullableWyciąg z opisu, do znaków 500, lub null, jeśli jest niedostępny.
results[0].results[].thumbnailsarrayMiniaturka URLs i wymiary.

Powyższe pola opisują domyślną odpowiedź JSON. Formaty JSON, proste teksty i Markdown.

Async zwraca jeden pokwitowanie zadania; partia zwraca jeden na zapytanie. Sprawdź status każdego zadania i odzyskaj jego wyniki za pomocą zwróconych linków.

Async i cykl życia serii

Składanie zwraca pokwitowanie, nie wyniki. Async tworzy jedno zadanie; wsadowe zwraca osobne zadanie w queries[] dla każdego akceptowanego zapytania. Śledź i odzyskaj każdą pracę niezależnie.

Prześlij do data.flashdata.dev; odczyt statusu pracy i wyniki api.flashdata.dev z tym samym X-API-Key. API podstawowe przykłady używać Python i cURL.

  1. 1. Zapisz zadanie IDs

    Podczas przełączania na Async należy zachować pola żądania tego źródła. Dla Batch, umieścić każde żądanie wewnątrz tablicy zapytań obiektu JSON. Zapisz każdą zwróconą pracę ID.

    Async wniosek i odbiór · Organ wnioskujący Batch

  2. 2. Sprawdź status

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

    pending / processing: ankieta z opóźnieniem i szacunkiem Retry-After gdy jest obecny. completed: pobrać wyniki. failed: Kontrola job.error.

    Przeczytaj job.status, a nie status potwierdzenia zgłoszenia.

    Sprawdź status · Python i cURL

    Status zatrudnienia API
  3. 3. Wyniki pobierania

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

    Po zakończeniu, uwierzytelnić wynik odczytywany, a następnie pobrać 302 pamięci URL bez klucza API. Zapisać JSON w ciągu 24 godzin po zakończeniu.

    Wyniki pobierania · Python i cURL · Formaty odpowiedzi

    Wynik pobrania API reference

Sondaże i pobieranie istniejących wyników nie zużywają kredytów zapytania. Czas ankiety nie anuluje zadania: zachować ID zamiast przedkładania duplikatu pracy billable. Kody błędów i powtarzanie zachowania.

Webhooki zakończenia

Subskrybuj na zapytanie

Ustaw callback_url na najwyższym poziomie żądania async, lub wewnątrz każdego zapytania w partii, na zewnątrz params. Nie jest wymagany oddzielny wniosek o rejestrację webhook- rejestracji. Żądania Realtime nie wysyłają zwrotów.

Użyj publicznego HTTPS URL na porcie 443. FlashData POST powiadomienie dla każdego zadania osiągającego completed lub failed; zdarzenie zawiera linki, a nie sam wynik.

Potwierdzenie i weryfikacja

Powrót 2xx po trwałym przyjęciu wydarzenia. Kopiowanie według delivery_id, również wysłane jako X-Delivery-Id. Przekierowanie nie jest przestrzegane.

Nieudane dostawy ponownie spróbować z wykładniczym backupu, aż do 8 próbuje w sumie i co najwyżej 24 godziny po zakończeniu. Kontynuuj sondaże jako zapas.

Przekazy są niepodpisane. Potwierdź zadanie ID, źródło i status terminala poprzez Uwierzytelniony punkt końcowy stanu przed rozpatrzeniem powiadomienia. Dostawa ID jest dla dedukcji, a nie dowód autentyczności.

Przykład zdarzenia i pól haka webowego
Ilustracyjne powiadomienie o zakończeniu
{
  "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"
    }
  ]
}
PoleOpis
delivery_idstringStabilny identyfikator dostawy. Notyfikacje kopiujące przy użyciu tej wartości; jest również wysyłane w nagłówku X-Delivery-Id.
idstringJob ID.
sourcestringWymagane źródło danych.
statusstringukończone lub nie.
linksarrayPowiązania stanu i wyników. Powiadomienia nie zawierają treści wyników ani klucza API.
links[].relstringsiebie lub wyników.
links[].hrefstringAbsolute Management API URL; uwierzytelniaj kluczykiem API.
links[].methodstringGET.

Pełna umowa na haczyk i ograniczenia URL

Błąd przy odzyskiwaniu

Jeżeli duży czas oczekiwania w czasie rzeczywistym się kończy, akceptacja może być niepewna. Sprawdź historię pracy przed wznowieniem. Dla kolejnych dużych wyszukiwań wybierz async i śledź zwrócony ID.

W przypadku błędów w uwierzytelnianiu, równowadze, formacie request- format i limicie rate- limit, użyj współdzielonego odniesienia błędu. Czas składania może jeszcze utworzyć pracę; sprawdzić istniejącą pracę przed ponownym uruchomieniem.

Błędy i kody statusu · Kiedy spróbować ponownie · Limity stóp procentowych

Przewodnik po krokach: Zaplanuj większe poszukiwania kandydatów

Cennik

Ceny bieżące i limity dotyczące planów