دليل

API عدد مرات التشغيل على Spotify: إجمالي مرات تشغيل أي أغنية، بالمعرّف أو ISRC

لا يذكر Web API من Spotify أبدًا كم مرة شُغّلت أغنية. أقرب ما يصل إليه هو الشعبية (popularity)، وهي درجة من 0 إلى 100 يصفها مرجعه نفسه بأنها مبنية في معظمها على إجمالي مرات التشغيل، ويصنّفها قيد الإيقاف. تعيد هذه النقاط العدد نفسه: أغنية واحدة بمعرّف Spotify أو ISRC، أو ما يصل إلى ⁨50⁩ أغنية باستدعاء واحد.

بقلم ⁨Eduardo Airaudo⁩، مشرف API · حُدّث في ⁨22 أكتوبر 2026⁩

ما الذي يتركه كائن الأغنية الرسمي

تعيد ⁨GET /v1/tracks/{id}⁩ في Spotify Web API الألبوم والفنانين و⁨duration_ms⁩ و⁨explicit⁩ و⁨external_ids⁩ والاسم و⁨popularity⁩ وبضعة حقول أخرى. ولا يحصي أي منها مرات التشغيل. وأقربها الشعبية: يعطيها مرجع Spotify قيمةً من 0 إلى 100 تُحسب في معظمها من عدد مرات تشغيل الأغنية ومدى حداثتها، ويصنّفها قيد الإيقاف. وقد أزالتها تغييرات Spotify في فبراير 2026 من التطبيقات في وضع التطوير المنشأة اعتبارًا من 11 فبراير 2026.

لا تؤدي الدرجة ما يؤديه العدد. فهي نسبية، فلا تُجمع عبر ألبوم أو كتالوج، وتفضّل التشغيلات الحديثة — وينص المرجع نفسه على أن الأغاني الأكثر تشغيلًا الآن تنال درجة أعلى من الأغاني التي كثر تشغيلها في الماضي — فلا يمكنها أن تقول كم مرة شُغّلت أغنية على مدى تاريخها.

بحسب عبارة المواصفات، فإن مجموعة Partner في هذا API هي «⁨Spotify's internal (pathfinder) data, including play counts⁩». تعيد ⁨/partner/track/count⁩ إجمالي عدد مرات تشغيل أغنية واحدة، وتعيد ⁨/partner/tracks/count⁩ أعداد ما يصل إلى ⁨50⁩ أغنية دفعة واحدة، وتحمله ⁨/partner/track⁩ داخل سجل الأغنية الكامل.

ما الذي يعود

حقلًا حقلًا، كما تعرّفها مخططات الاستجابة في المواصفات. يسمّي استدعاء الأغنية الواحدة العدد ⁨streams⁩؛ وتسمّيه الدفعة ⁨playcount⁩.

أغنية واحدة

GET /partner/track/count

streams
إجمالي مرات التشغيل، كعدد صحيح (int64). يقبل القيمة الفارغة في المواصفات، وهو 0 للأغنية التي لها أقل من 1,000 مرة تشغيل.
spotify_track_id
معرّف الأغنية في Spotify.
isrc
رمز ISRC للأغنية. يقبل القيمة الفارغة في المواصفات.
result
⁨success⁩ أو ⁨error⁩، مع حقل ⁨message⁩ قصير بجانبه.

دفعة

GET /partner/tracks/count

tracks[]
عنصر لكل معرّف مطلوب، بترتيب الطلب.
tracks[].playcount
إجمالي مرات التشغيل (int64، يقبل الفارغ)؛ 0 لأغنية لها أقل من 1,000.
tracks[].status
⁨ok⁩ أو ⁨not_found⁩ أو ⁨error⁩، مع نص ⁨error⁩ عندما تكون الحالة ⁨error⁩.
tracks[].name
اسم الأغنية؛ و⁨null⁩ عند عدم العثور عليها.
tracks[].artists[]
⁨id⁩ و⁨name⁩ لكل فنان.
tracks[].releaseDate
تاريخ إصدار ألبوم الأغنية: YYYY-MM-DD، أو بدقة أقل.
missing[]
المعرّفات المطلوبة التي حالتها ليست ⁨ok⁩.

القيمة 0 تعني أقل من 1,000، لا أنها لم تُشغَّل قط. تنص المواصفات على أن Spotify يعيد 0 للأغاني التي لها أقل من 1,000 مرة تشغيل، فخزّن القيمة 0 على أنها «أقل من 1,000» لا على أنها عدد.

عيّنة مسجّلة · التُقطت في ⁨2026-10-22⁩

GET /partner/track/count

⁨6⁩ سطر — كامل الجسم المسجّل.

عيّنة مسجّلة · التُقطت في ⁨2026-10-22⁩

GET /partner/tracks/count

⁨18⁩ سطر — كامل الجسم المسجّل.

أغنية واحدة، أو ⁨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.

    المعاملاتspotify_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.

    المعاملاتids, 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).

    المعاملاتid, slim, cache

تأخذ ⁨/partner/tracks/count⁩ ما يصل إلى ⁨50⁩ معرّف مفصولة بفواصل وتجيب بالترتيب الذي أرسلتها به، فتكلّف ⁨50⁩ أغنية طلبًا واحدًا لا ⁨50⁩ طلب.

اجلب أعداد مرات التشغيل

أغنية واحدة، بمعرّف Spotify

المعرّف هو السلسلة المكوّنة من 22 حرفًا بعد ⁨/track/⁩ في أي رابط Spotify. وللبحث عن أغنية بـ ISRC الخاص بها، أرسل ⁨isrc=⁩ بدل ⁨id=⁩.

ما يصل إلى ⁨50⁩ أغنية في استدعاء واحد

اقرأ ⁨status⁩ لكل عنصر قبل عدده. تعود العناصر بترتيب المعرّفات؛ وما لا عدد تشغيل له يوسَم بـ⁨not_found⁩ أو ⁨error⁩ مكانه، ويُدرج مرة أخرى في ⁨missing⁩.

أعداد التشغيل بلا كود

إذا كانت الأعداد لجدول بيانات لا لكودك الخاص، فهناك Actors اثنان على Apify من المشرف نفسه يعيدانها كمجموعة بيانات. يحتاج التشغيل إلى حساب Apify ولا يحتاج إلى مفتاح API: تلصق الروابط وتنزّل JSON أو CSV.

  • Spotify Play Count Scraper (يفتح في تبويب جديد)eduair94/spotify-play-count-scraper

    الصق روابط أو URIs أو معرّفات أغانٍ أو ألبومات أو فنانين أو قوائم تشغيل؛ يعيد صفًا لكل أغنية مع عدد تشغيلها — أبرز أغاني فنان أو أعماله كلها، وكل أغنية في ألبوم أو قائمة تشغيل — وعند الطلب صفًا بالمستمعين الشهريين للفنان.

  • Spotify Scraper (يفتح في تبويب جديد)eduair94/spotify-scraper

    الـ Actor العام: ⁨61⁩ فئة، منها ⁨5⁩ لمرات التشغيل (⁨track_play_count, album_play_counts, artist_play_counts, artist_discography_play_counts, playlist_play_counts⁩)، و⁨isrc⁩ الذي يجد أغنية بـ ISRC الخاص بها مع عدد تشغيلها.

كلاهما يحاسب لكل نتيجة، بالأسعار المدرجة بتاريخ ⁨⁩: ⁨$0.001⁩ للصف في خطة Apify المجانية، وصولًا إلى ⁨$0.0006⁩ ابتداءً من Gold فما فوق. ومتى يتفوق التشغيل على المفتاح ومتى لا، في ⁨دليل أداة الاستخراج⁩.

سجل محفوظ بالفعل: 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.

استخدمه من مساعد ذكاء اصطناعي (MCP): اسأل Claude أو Cursor أو VS Code عن عدد تشغيل أغنية، فتعيد أداة ⁨get_track_play_count⁩ في خادم Spotify MCP إجمالي مرات التشغيل من هذا API. ⁨إعداد خادم MCP⁩.

أسئلة

هل يعيد Spotify Web API أعداد مرات التشغيل؟

لا. ليس في كائن الأغنية في مرجع Web API حقل لعدد مرات التشغيل. وأقرب حقوله، وهو popularity، درجة من 0 إلى 100 يحسبها Spotify في معظمها من إجمالي مرات التشغيل ومدى حداثتها؛ ويصنّفها المرجع قيد الإيقاف، وقد أزالتها تغييرات Spotify في فبراير 2026 من التطبيقات في وضع التطوير المنشأة اعتبارًا من 11 فبراير 2026.

لماذا تظهر أغنية بـ 0 مرة تشغيل؟

لأن لها أقل من 1,000. تنص المواصفات على أن Spotify يعيد 0 للأغاني التي لها أقل من 1,000 مرة تشغيل، فالقيمة 0 تعني أقل من 1,000، لا أنها لم تُشغَّل قط.

هل يمكنني الحصول على أعداد التشغيل لأغانٍ كثيرة دفعة واحدة؟

نعم. تأخذ ⁨GET /partner/tracks/count⁩ ما يصل إلى ⁨50⁩ معرّف أغنية مفصولة بفواصل وتجيب بترتيب الطلب، وكل عنصر بحالة ⁨ok⁩ أو ⁨not_found⁩ أو ⁨error⁩؛ وتُدرج المعرّفات التي لا عدد تشغيل لها في ⁨missing⁩ أيضًا. تكلّف ⁨50⁩ أغنية طلبًا واحدًا لا ⁨50⁩ طلب.

هل يمكنني البحث عن أغنية بـ ISRC؟

نعم. تأخذ ⁨GET /partner/track/count⁩ المعامل ⁨isrc⁩ بدل معرّف Spotify، فالكتالوج المفهرس بـ ISRC لا يحتاج إلى البحث عن المعرّف أولًا.

ما مدى حداثة الرقم؟

تُخزَّن أعداد التشغيل مؤقتًا لمدة ساعة، فعمر العدد عادةً ساعة على الأكثر. وتعني قيمة ⁨X-Cache⁩ التي تبدأ بـ⁨STALE⁩ أو ⁨FALLBACK⁩ أن نسخة أقدم قُدّمت لأن الجلب المباشر كان بطيئًا أو فشل؛ ويعطي ⁨X-Cache-Stale-Age⁩ عمرها بالثواني. أضف ⁨cache=false⁩ لجلب نسخة جديدة. وتمر أزرار التشغيل في هذا الموقع بذاكرة العرض التجريبي المؤقتة أيضًا، فقد يكون الرقم هناك أقدم.

هل يمكنني الحصول على أعداد التشغيل دون كتابة كود؟

نعم، على Apify: يحتاج التشغيل إلى حساب Apify ولا يحتاج إلى مفتاح API. يأخذ ⁨Spotify Play Count Scraper⁩ (⁨eduair94/spotify-play-count-scraper⁩) روابط أغانٍ أو ألبومات أو فنانين أو قوائم تشغيل ويعيد صفًا لكل أغنية مع عدد تشغيلها؛ وفي ⁨Spotify Scraper⁩ (⁨eduair94/spotify-scraper⁩) ⁨5⁩ فئات لأعداد التشغيل من بين ⁨61⁩. كلاهما يحاسب لكل نتيجة.

أي خطة أحتاج؟

أي خطة. نقطتا نهاية أعداد التشغيل موجودتان في كل خطة، في RapidAPI والبوابة المباشرة على السواء، وتختلف الخطط بالحجم الشهري. تتيح كل خطة RapidAPI ⁨5⁩ طلبات في الثانية، ويشمل كل مفتاح مباشر ⁨10⁩. وتتيح خطة RapidAPI المجانية ⁨1,000⁩ طلب شهريًا.

المصادر

More guides

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

احصل على مفتاح واسحب أول عدد تشغيل

نقطتا نهاية أعداد التشغيل موجودتان في كل خطة، في RapidAPI والبوابة المباشرة على السواء؛ وعلى Apify يعيد الـ Actorان المذكوران أعلاه الأعداد نفسها كصفوف مجموعة بيانات، تُحاسب لكل نتيجة. والطبقة المجانية في RapidAPI هي ⁨1,000⁩ طلب شهريًا: وبما يصل إلى ⁨50⁩ أغنية في الاستدعاء، يبلغ ذلك حتى ⁨50,000⁩ عدد تشغيل.

RapidAPI Apify البوابة المباشرة

لم تقرر الشراء بعد؟ ⁨احصل على مفتاح تجريبي مجاني⁩: ⁨500⁩ طلب خلال ⁨7⁩ أيام، بلا بطاقة.