Spotify Search API: صيغة الاستعلام والحدود وتغييرات 2026

واجهة البحث في Spotify نقطة واحدة، GET https://api.spotify.com/v1/search، تأخذ نص استعلام وتعيد ما يطابقه من مقاطع أو فنانين أو ألبومات أو قوائم تشغيل أو برامج أو حلقات أو كتب صوتية. ولا تزال تعمل كما تصفها أغلب الشروحات، لكن 2026 غيّرت الأرقام: صارت تطبيقات وضع التطوير تحصل على 10 نتائج كحدّ أقصى في الصفحة، وتحتاج إلى حساب Premium، ولا يمكن أن يكون لها أكثر من 5 مستخدمين. يشرح هذا الدليل صيغة الاستعلام، والمصادقة، والمعرّفات، والحدود، والتغييرات التي تعطّل الشيفرات القديمة.

كيف تعمل نقطة البحث في Spotify؟

هناك مُعاملان إلزاميان: q، نص البحث، وtype، قائمة مفصولة بفواصل بما تريد البحث عنه. والباقي اختياري. بحسب مرجع البحث:

تحتوي الاستجابة على كائن ترقيم صفحات لكل نوع طلبته (tracks وartists وغيرهما)، وفي كل منها items وnext وlimit وoffset وtotal.

كيف تكتب استعلام بحث في Spotify؟

الكلمات العادية تُطابَق في أي مكان. ولتضييق البحث، أضف مرشّحات حقول إلى q. وكل مرشّح لا ينطبق إلا على بعض الأنواع:

تُجمع المرشّحات مع النص العادي: q=airbag artist:radiohead year:1997 مع type=track يجد تلك الأغنية بعينها. والبحث بـ isrc: هو أوثق طريقة لمطابقة مقطع تعرفه مسبقًا من مصدر آخر، لأن ISRC يعرّف التسجيل نفسه.

كيف تتم المصادقة؟

لا يقرأ البحث أي بيانات للمستخدم، لذا يكفي مسار client credentials: استبدل معرّف العميل والسرّ الخاصين بتطبيقك برمز وصول، ثم أرسله كرمز bearer. تدوم الرموز 3,600 ثانية، فخزّن رمزًا واحدًا وأعد استخدامه.

TOKEN=$(curl -s -X POST "https://accounts.spotify.com/api/token" \
  -u "$SPOTIFY_CLIENT_ID:$SPOTIFY_CLIENT_SECRET" \
  -d "grant_type=client_credentials" | jq -r .access_token)

curl -G "https://api.spotify.com/v1/search" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "q=airbag artist:radiohead" \
  --data-urlencode "type=track" \
  --data-urlencode "market=GB" \
  --data-urlencode "limit=10"

الاستدعاء نفسه بلغة Python:

import os
import requests

token = requests.post(
    "https://accounts.spotify.com/api/token",
    auth=(os.environ["SPOTIFY_CLIENT_ID"], os.environ["SPOTIFY_CLIENT_SECRET"]),
    data={"grant_type": "client_credentials"},
).json()["access_token"]

res = requests.get(
    "https://api.spotify.com/v1/search",
    headers={"Authorization": f"Bearer {token}"},
    params={"q": "airbag artist:radiohead", "type": "track", "market": "GB", "limit": 10},
)
for track in res.json()["tracks"]["items"]:
    print(track["id"], track["name"], track["artists"][0]["name"])

ما معرّف Spotify وURI والرابط؟

تحمل كل نتيجة حقل id. وتعرّف صفحة المعرّفات وURI في Spotify المعرّف بأنه السلسلة المرمّزة بـ base-62 في نهاية Spotify URI. ويبلغ طول معرّفات المقاطع والفنانين والألبومات وقوائم التشغيل عادةً 22 حرفًا. ويظهر العنصر نفسه بثلاثة أشكال:

لتحويل رابط ملصوق إلى معرّف، خذ مقطع المسار الذي يلي /track/ أو /artist/ أو /album/ واحذف أي سلسلة استعلام ?si=. وليس كل معرّف في Spotify بطول 22 حرفًا: معرّفات المستخدمين ومعرّفات الفئات سلاسل نصية عادية، فلا تعتمد على الطول وحده للتحقق.

ما حدود واجهة البحث في Spotify؟

تحسب Spotify الطلبات على نافذة متحركة مدتها 30 ثانية ولا تنشر الأرقام. وإذا تجاوزت الحدّ تحصل على HTTP 429 مع ترويسة Retry-After بالثواني، فانتظر تلك المدة قبل إعادة المحاولة. ومنذ يوليو 2026 تُحسب حصة وضع التطوير لكل حساب مطوّر بدلًا من كل تطبيق، ويحمل خطأ الحصة "reason": "QUOTA_EXCEEDED".

أما الحدود الأكبر فتتعلق بمن يحقّ له استخدام الواجهة أصلًا:

• وضع التطوير صار الآن للتعلّم والتجارب والمشاريع الشخصية غير التجارية. ومنذ فبراير 2026 يحتاج مالك التطبيق إلى Spotify Premium، ويمكن أن يكون لكل تطبيق 5 مستخدمين مصرّح لهم.
• وضع الحصة الموسّعة، المخصّص للإنتاج، متاح للمؤسسات فقط منذ مايو 2025: شركة مسجّلة لديها خدمة مُطلقة و250,000 مستخدم نشط شهريًا على الأقل، وقد تستغرق المراجعة ستة أسابيع.

ما الذي تغيّر في Spotify Web API بين 2024 و2026؟

إذا فشلت شيفرة من أحد الشروحات، فالأرجح أنها كُتبت قبل أحد هذه التغييرات:

كما أزال دليل الترحيل الصادر في فبراير 2026 عمليات الجلب المجمّعة مثل GET /tracks?ids=، وأشهر مقاطع الفنان، ونقاط browse، وأوقف حقولًا منها popularity وgenres وfollowers. والشيفرة التي ترتّب نتائج البحث حسب الشعبية تحتاج إلى مؤشر آخر.

البحث في Spotify إلى جانب منصات أخرى

إذا كانت Spotify واحدة من عدة مصادر تبحث فيها، كأن تبحث عن فنان على Spotify وSoundCloud وApple Music معًا، فإن crawlfeed يوفّر البحث والاستعلام في Spotify بمفتاح API نفسه وبنية الاستجابة نفسها اللذين يستخدمهما مع منصاته الأخرى البالغة 26:

يكلّف البحث الواحد رصيد واحد، ويعود الفنانون ككائنات Profile، وهو النوع نفسه لفنان على SoundCloud أو Apple Music. وتنطبق شروط المطوّرين من Spotify على محتوى Spotify أيًّا كانت طريقة جلبه: فهي تمنع إدخاله في نماذج الذكاء الاصطناعي وبناء قواعد بيانات تتجاوز حاجة تطبيقك، لذا يستثني crawlfeed منصة Spotify من الإثراء بالذكاء الاصطناعي ومن الأرشيف الخام. راجع مرجع Spotify لكل المُعاملات، أو دليل SoundCloud API لمصدر الموسيقى الكبير الآخر.

الخلاصة

استدعِ GET https://api.spotify.com/v1/search مع q وtype ورمز وصول من مسار client credentials. وضيّق النتائج بمرشّحات مثل artist: وyear: وisrc:، وتنقّل بين الصفحات باستخدام offset حتى 1,000. في وضع التطوير تحصل على 10 نتائج كحدّ أقصى في الصفحة، وتحتاج إلى Premium، ولا يتجاوز مستخدموك 5، أما الوصول للإنتاج فمقصور على الشركات التي لديها 250,000 مستخدم شهريًا. والمعرّفات سلاسل بترميز base-62، طولها عادةً 22 حرفًا، وتجدها في نهاية كل Spotify URI ورابط.