Heute beliebt
Liest den neuesten stabilen Hot-Video-Snapshot.
GET
https://api.shortsmonkey.com/v1/rankings/hot-today?region=US&tier=all&limit=201 Credit pro tatsächlich zurückgegebenen 1–20 Einträgen
Heute beliebt#
Liest den neuesten stabilen Hot-Video-Snapshot.
Authentifizierung#
Sende Authorization: Bearer sm_live_.... Der vollständige Schlüssel gehört nicht in URLs, Cookies, Bodies, Logs oder Analytics.
Datenaktualität#
Ranglisten lesen nur stabile Worker-Snapshots. Öffentliche Leseanfragen starten nie einen YouTube-Refresh.
Anfrage#
| Element | Wert | Beschreibung |
|---|---|---|
| Methode | GET | HTTP-Anfragemethode |
| Vollständige URL | https://api.shortsmonkey.com/v1/rankings/hot-today?region=US&tier=all&limit=20 | Produktions-API-URL |
| Authentifizierung | Authorization: Bearer sm_live_... | Den vollständigen Schlüssel nur im Header senden |
| Inhaltstyp | Kein Request-Body | GET-Anfragen haben keinen Request-Body |
| Credits | 1 Credit pro tatsächlich zurückgegebenen 1–20 Einträgen | Fehlerantworten kosten 0 Credits |
Anfrageparameter#
| Name | Position | Typ | Erforderlich | Standard | Werte oder Grenzen | Beschreibung |
|---|---|---|---|---|---|---|
region | Query | string | Nein | Alle Regionen | 2–16 Zeichen | Regionscode wie US oder JP |
tier | Query | string | Nein | all | S / A / B / C / all | Hot-Tier-Filter |
limit | Query | integer | Nein | 20 | 1–50 | Maximale Anzahl von Einträgen auf dieser Seite |
all_cursor | Query | string | Nein | — | data.all_data.next_cursor | Nächste ungefilterte Seite abrufen |
filter_cursor | Query | string | Nein | — | data.filter_data.next_cursor | Nächste gefilterte Seite ohne Filteränderung abrufen |
cursor | Query | string | Nein | — | Veralteter Kompatibilitätsparameter | Alias für filter_cursor; nicht beide senden |
Felder der Erfolgsantwort#
all_data ist eine ungefilterte Seite des stabilen Snapshots; filter_data stammt aus demselben Snapshot nach Standard- und Anfragefiltern. Beide Ergebnisse werden unabhängig paginiert.
Punktnotation kennzeichnet verschachtelte Objekte und [] Array-Elemente. Unbekannte Abonnentenzahlen sind null. Eine Anfrage wird einmal nach der größeren Ergebnismenge berechnet, nie nach der Summe.
| Feldpfad | Typ | Nullable | Beschreibung |
|---|---|---|---|
data.all_data.items | array<object> | Nein | Ungefilterte Videoelemente der aktuellen Seite |
data.all_data.items[].video_id | string | Nein | YouTube-Video-ID |
data.all_data.items[].title | string | Nein | Videotitel |
data.all_data.items[].video_url | string | Nein | YouTube-Video-URL |
data.all_data.items[].channel.id | string | Ja | Kanal-ID |
data.all_data.items[].channel.title | string | Nein | Kanalname |
data.all_data.items[].channel.subscribers | integer | Ja | Abonnentenzahl; bei Ausblendung null |
data.all_data.items[].channel.subscriber_count_hidden | boolean | Nein | Ob die Abonnentenzahl ausgeblendet ist |
data.all_data.items[].views | integer | Nein | Aufruf-Snapshot |
data.all_data.items[].views_to_subscribers_ratio | number | Ja | Verhältnis Aufrufe zu Abonnenten |
data.all_data.items[].opportunity_score | number | Ja | Opportunity-Score |
data.all_data.items[].duration_seconds | integer | Nein | Videodauer in Sekunden |
data.all_data.items[].published_at | string(date-time) | Ja | Videoveröffentlichung in UTC ISO 8601 |
data.all_data.items[].snapshot_at | string(date-time) | Ja | Zeitpunkt der Datenerfassung |
data.all_data.items[].niche | string | Ja | Nische oder Kategorie |
data.all_data.items[].track | string | Ja | Datensatz-Track |
data.all_data.items[].region | string | Ja | Regionscode |
data.all_data.items[].reasons | array<string> | Nein | Rankinggründe |
data.all_data.items[].video_type | string | Nein | shorts oder long |
data.all_data.next_cursor | string | Ja | Cursor der nächsten Seite für dieses Ergebnis; am Ende null |
data.filter_data.items | array<object> | Nein | Videoelemente nach Standard- und Anfragefiltern |
data.filter_data.items[].video_id | string | Nein | YouTube-Video-ID |
data.filter_data.items[].title | string | Nein | Videotitel |
data.filter_data.items[].video_url | string | Nein | YouTube-Video-URL |
data.filter_data.items[].channel.id | string | Ja | Kanal-ID |
data.filter_data.items[].channel.title | string | Nein | Kanalname |
data.filter_data.items[].channel.subscribers | integer | Ja | Abonnentenzahl; bei Ausblendung null |
data.filter_data.items[].channel.subscriber_count_hidden | boolean | Nein | Ob die Abonnentenzahl ausgeblendet ist |
data.filter_data.items[].views | integer | Nein | Aufruf-Snapshot |
data.filter_data.items[].views_to_subscribers_ratio | number | Ja | Verhältnis Aufrufe zu Abonnenten |
data.filter_data.items[].opportunity_score | number | Ja | Opportunity-Score |
data.filter_data.items[].duration_seconds | integer | Nein | Videodauer in Sekunden |
data.filter_data.items[].published_at | string(date-time) | Ja | Videoveröffentlichung in UTC ISO 8601 |
data.filter_data.items[].snapshot_at | string(date-time) | Ja | Zeitpunkt der Datenerfassung |
data.filter_data.items[].niche | string | Ja | Nische oder Kategorie |
data.filter_data.items[].track | string | Ja | Datensatz-Track |
data.filter_data.items[].region | string | Ja | Regionscode |
data.filter_data.items[].reasons | array<string> | Nein | Rankinggründe |
data.filter_data.items[].video_type | string | Nein | shorts oder long |
data.filter_data.next_cursor | string | Ja | Cursor der nächsten Seite für dieses Ergebnis; am Ende null |
data.all_data.items[].tier | string | Nein | Hot-Tier S / A / B / C |
data.filter_data.items[].tier | string | Nein | Hot-Tier S / A / B / C |
meta.request_id | string | Nein | Anfrage-Trace-ID |
meta.snapshot_id | string | Nein | Stabile Snapshot-ID |
meta.snapshot_at | string(date-time) | Nein | Snapshot-Zeitpunkt |
meta.data_status | string | Nein | Datensatzstatus |
credits.cost | integer | Nein | Tatsächlich berechnete Credits |
credits.remaining | integer | Nein | Verbleibende Konto-Credits |
credits.period_ends_at | string(date-time) | Nein | Ende des aktuellen Credit-Zeitraums |
Cursor-Seiten#
all_data.next_cursor wird als all_cursor, filter_data.next_cursor als filter_cursor gesendet. Beide Cursor sind unabhängig, signiert, undurchsichtig und 24 Stunden gültig; cursor ist nur ein veralteter Alias für filter_cursor.
ETag#
Ranglisten unterstützen If-None-Match. HTTP 304 kostet 0 Credits.
Fehler und Limits#
Jeder Fehler enthält code, englische message, request_id und details. 4xx/5xx kosten 0 Credits.
| HTTP-Status | Code | Ursache | Empfehlung |
|---|---|---|---|
| 400 | INVALID_REQUEST | Ungültiges Parameterformat, Kombination oder Bereich | Parameter anhand von details.issues korrigieren |
| 401 | INVALID_API_KEY | Der Schlüssel ist ungültig oder inaktiv | Bearer-Header und Schlüsselstatus prüfen |
| 402 | SUBSCRIPTION_REQUIRED / CREDITS_EXHAUSTED | Abonnement oder Credits sind nicht verfügbar | Tarif, Guthaben und Schlüsselbudget prüfen |
| 429 | RATE_LIMITED | Rate- oder Parallelitätslimit überschritten | Nach Retry-After erneut versuchen |
| 503 | DATA_STALE / SERVICE_UNAVAILABLE | Daten oder Dienst sind vorübergehend nicht verfügbar | Später erneut versuchen und request_id aufbewahren |
curl -X GET "https://api.shortsmonkey.com/v1/rankings/hot-today?region=US&tier=all&limit=20" \
-H "Authorization: Bearer $SHORTSMONKEY_API_KEY"