Poradnik

API odtworzeń Spotify: łączna liczba odtworzeń dowolnego utworu, po ID lub ISRC

Web API Spotify nigdy nie podaje, ile razy utwór został odtworzony. Najbliżej jest popularność — wynik od 0 do 100, który według własnej dokumentacji Spotify opiera się głównie na łącznej liczbie odtworzeń i jest oznaczony jako przestarzały. Te endpointy zwracają samą liczbę: jeden utwór po ID Spotify lub ISRC albo wiele utworów w jednym wywołaniu (limit: 50).

Autor: Eduardo Airaudo, opiekun API · Aktualizacja: 22 października 2026

Czego brakuje w oficjalnym obiekcie utworu

GET /v1/tracks/{id} w Web API Spotify zwraca album, wykonawców, duration_ms, explicit, external_ids, nazwę, popularity i kilka innych pól. Żadne z nich nie liczy odtworzeń. Najbliżej jest popularność: dokumentacja Spotify podaje ją jako wartość od 0 do 100, obliczaną głównie na podstawie liczby odtworzeń utworu i ich świeżości, i oznacza jako przestarzałą. Zmiany Spotify z lutego 2026 usunęły ją dla aplikacji w trybie deweloperskim utworzonych od 11 lutego 2026.

Wynik nie zastąpi liczby. Jest względny, więc nie sumuje się w obrębie albumu ani katalogu, i faworyzuje świeże odtworzenia — ta sama dokumentacja mówi, że utwory często odtwarzane teraz dostają wyższy wynik niż utwory często odtwarzane dawniej — więc nie powie, ile razy utwór był odtworzony w sumie.

Według specyfikacji grupa Partner tego API to „Spotify's internal (pathfinder) data, including play counts”. /partner/track/count zwraca łączną liczbę odtworzeń jednego utworu, /partner/tracks/count — wielu utworów naraz (limit: 50), a /partner/track zawiera ją w pełnym rekordzie utworu.

Co wraca w odpowiedzi

Pole po polu, tak jak definiują je schematy odpowiedzi w specyfikacji. Wywołanie pojedynczego utworu nazywa liczbę streams; wsadowe — playcount.

Jeden utwór

GET /partner/track/count

streams
Łączna liczba odtworzeń jako liczba całkowita (int64). W specyfikacji nullable; 0 dla utworu poniżej 1 000 odtworzeń.
spotify_track_id
ID Spotify utworu.
isrc
ISRC utworu. W specyfikacji nullable.
result
success lub error, z krótkim message obok.

Wywołanie wsadowe

GET /partner/tracks/count

tracks[]
Jeden wpis na każde żądane ID, w kolejności zapytania.
tracks[].playcount
Łączna liczba odtworzeń (int64, nullable); 0 dla utworu poniżej 1 000.
tracks[].status
ok, not_found lub error, z tekstem error, gdy status to error.
tracks[].name
Nazwa utworu; null, gdy nie znaleziono.
tracks[].artists[]
id i name każdego wykonawcy.
tracks[].releaseDate
Data wydania albumu utworu: YYYY-MM-DD lub mniej precyzyjna.
missing[]
Żądane ID, których status nie jest ok.

0 oznacza poniżej 1 000, a nie „nigdy nie odtworzono”. Według specyfikacji Spotify podaje 0 dla utworów z mniej niż 1 000 odtworzeń, więc 0 należy zapisywać jako „poniżej 1 000”, a nie jako liczbę.

Zapisana próbka · zarejestrowano: 2026-10-22

GET /partner/track/count

Wiersze: 6 — cała zapisana odpowiedź.

Zapisana próbka · zarejestrowano: 2026-10-22

GET /partner/tracks/count

Wiersze: 18 — cała zapisana odpowiedź.

Jeden utwór albo wsad w jednym wywołaniu (limit: 50)

  • GET /partner/track/countTrack play count

    Lifetime play count of one track, by Spotify id (spotify_track_id, or its alias id) or by isrc. Spotify reports 0 for tracks with fewer than 1,000 plays. Play counts are cached for 1 hour; for many tracks use /partner/tracks/count.

    Parametryspotify_track_id, id, isrc, cache

  • GET /partner/tracks/countTrack play counts (batch)

    Lifetime play counts for up to 50 tracks in one call. Entries come back in request order with status ok, not_found or error; ids without a play count are also listed in missing. Each id is cached for 1 hour.

    Parametryids, cache

  • GET /partner/trackPartner track data

    Track with its play count (data.trackUnion.playcount), album, artists and content ratings. Add slim=1 to keep only {id, uri, profile.name, visuals.avatarImage} of each artist (the full payload embeds the first artist's discography and is ~100 KB).

    Parametryid, slim, cache

/partner/tracks/count przyjmuje ID oddzielone przecinkami (limit: 50) i odpowiada w kolejności wysłania, więc paczka o rozmiarze 50 kosztuje jedno zapytanie zamiast 50.

Pobieranie odtworzeń

Jeden utwór, po ID Spotify

ID to 22-znakowy ciąg po /track/ w dowolnym adresie URL Spotify. Aby znaleźć utwór po ISRC, należy wysłać isrc= zamiast id=.

Utwory w jednym wywołaniu (limit: 50)

Przed liczbą należy sprawdzić pole status każdego wpisu. Wpisy wracają w kolejności ID; wpis bez liczby odtworzeń jest oznaczony jako not_found lub error i wymieniony ponownie w missing.

Odtworzenia bez kodu

Jeśli liczby mają trafić do arkusza, a nie do własnego kodu, dwa Actory Apify od tego samego opiekuna zwracają je jako zbiór danych. Uruchomienie wymaga konta Apify, ale nie klucza API: wystarczy wkleić linki i pobrać JSON lub CSV.

Oba rozliczają za wynik, według cen z dnia : $0.001 za wiersz w darmowym planie Apify, aż do $0.0006 od planu Gold wzwyż. Kiedy uruchomienie wygrywa z kluczem, a kiedy nie, opisuje poradnik o scraperze.

Już prowadzona historia: spotify-most-streamed-songs (opens in a new tab) on GitHub has daily play counts and daily streams for 1,000 of the most-streamed songs, as CSV and JSON history.

Użycie z asystenta AI (MCP): wystarczy zapytać Claude, Cursor lub VS Code o odtworzenia utworu, a narzędzie get_track_play_count serwera MCP Spotify zwraca łączną liczbę odtworzeń z tego API. Konfiguracja serwera MCP.

Pytania

Czy Web API Spotify zwraca liczbę odtworzeń?

Nie. Obiekt utworu w dokumentacji Web API nie ma pola z liczbą odtworzeń. Najbliższe pole, popularność, to wynik od 0 do 100, który Spotify oblicza głównie na podstawie łącznej liczby odtworzeń i ich świeżości; dokumentacja oznacza je jako przestarzałe, a zmiany Spotify z lutego 2026 usunęły je dla aplikacji w trybie deweloperskim utworzonych od 11 lutego 2026.

Dlaczego utwór ma 0 odtworzeń?

Bo ma ich mniej niż 1 000. Według specyfikacji Spotify podaje 0 dla utworów z mniej niż 1 000 odtworzeń, więc 0 oznacza poniżej 1 000, a nie „nigdy nie odtworzono”.

Czy można pobrać odtworzenia wielu utworów naraz?

Tak. GET /partner/tracks/count przyjmuje ID utworów oddzielone przecinkami (limit: 50) i odpowiada w kolejności zapytania, a każdy wpis ma status ok, not_found lub error; ID bez liczby odtworzeń są też wymienione w missing. Paczka o rozmiarze 50 kosztuje jedno zapytanie zamiast 50.

Czy można znaleźć utwór po ISRC?

Tak. GET /partner/track/count przyjmuje isrc zamiast ID Spotify, więc katalog oparty na ISRC nie potrzebuje wcześniejszego wyszukiwania ID.

Jak aktualna jest ta liczba?

Odtworzenia są buforowane przez godzinę, więc liczba jest zwykle co najwyżej tak stara. Wartość X-Cache zaczynająca się od STALE lub FALLBACK oznacza, że podano starszą kopię, bo pobranie na żywo było wolne albo się nie udało; X-Cache-Stale-Age podaje jej wiek w sekundach. Parametr cache=false wymusza świeże pobranie. Przyciski Uruchom na tej stronie przechodzą też przez własną pamięć podręczną dema, więc liczba może być tam starsza.

Czy można uzyskać odtworzenia bez pisania kodu?

Tak, na Apify: uruchomienie wymaga konta Apify, ale nie klucza API. Spotify Play Count Scraper (eduair94/spotify-play-count-scraper) przyjmuje linki do utworów, albumów, wykonawców lub playlist i zwraca jeden wiersz na utwór z liczbą odtworzeń; Spotify Scraper (eduair94/spotify-scraper) ma kategorie odtworzeń: 5, spośród wszystkich: 61. Oba rozliczają za wynik.

Jaki plan jest potrzebny?

Dowolny. Oba endpointy odtworzeń są w każdym planie, zarówno w RapidAPI, jak i w portalu bezpośrednim, a plany różnią się miesięcznym wolumenem. Każdy plan RapidAPI: zapytania na sekundę: 5, każdy klucz bezpośredni: 10. Darmowy plan RapidAPI: zapytania miesięcznie: 1000.

Źródła

More guides

What changed in the API and on these pages, and when: What's new.

Uzyskaj klucz i pobierz pierwszą liczbę odtworzeń

Oba endpointy odtworzeń są w każdym planie, zarówno w RapidAPI, jak i w portalu bezpośrednim; na Apify dwa Actory powyżej zwracają te same liczby jako wiersze zbioru danych, rozliczane za wynik. Darmowy plan RapidAPI: zapytania miesięcznie: 1000; przy limicie utworów na wywołanie (50) można pobrać liczby odtworzeń dla maksymalnie takiej liczby utworów: 50 000.

RapidAPI Apify Portal bezpośredni

Jeszcze nie pora na zakup? Uzyskaj darmowy klucz próbny: zapytania: 500, okres: 7 dni, bez karty.