ابدء
هذه المستندات هي تطبيق Genius

استكشف نقاط نهاية API بشكل تفاعلي عن طريق ربط حسابك في Genius بهذه الصفحة. تعرف على كيفية وصول تطبيقك إلى محتوى Genius ومجتمعه بهذه السهولة أيضًا!
أضف التعليقات التوضيحية العبقرية إلى موقعك الخاص

بالإضافة إلى التفاعل مع تعليقات Genius التوضيحية من خلال واجهة برمجة التطبيقات (API)، من السهل جعل أي صفحة قابلة للتعليق وعرض التعليقات التوضيحية التي قمت بإنشائها عليها. فقط قم بإضافة علامة البرنامج النصي:

تسجيل التطبيق الخاص بك
أولاً، قم بزيارة صفحة إدارة Genius API Client وقم بإنشاء عميل API لتطبيقك. سيزودك هذا بمعرف_العميل وسر_العميل الذي ستستخدمه لتعريف تطبيقك لـ Genius. يتم استخدام redirect\_uri لمصادقة مستخدمي Genius مع تطبيقك. يمكنك تغييره لاحقا. سوف ينتمي عميل API إلى حساب المستخدم الذي تم تسجيل دخوله إلى Genius عند إنشائه.

تقديم الطلبات
تم إدراج نقاط النهاية المتوفرة أدناه في قسم الموارد، إلى جانب الأمثلة المضمنة التي توضح كيفية عملها وما الذي تعود به.

يستخدم Genius OAuth2 للمصادقة. يجب مصادقة جميع طلبات واجهة برمجة التطبيقات (API). هناك الكثير من المكتبات المتاحة للمساعدة في هذا الجزء من التكامل. يوجد أيضًا دليل تفصيلي أدناه إذا كنت ملتزمًا بتنفيذه بنفسك.

موارد
الشروح
التعليق التوضيحي هو جزء من المحتوى حول جزء من المستند. قد يكون المستند عبارة عن أغنية (مستضافة على Genius) أو صفحة ويب (مستضافة في أي مكان). يسمى جزء المستند الذي يتم إرفاق التعليق التوضيحي به بالمرجع.

تتضمن بيانات التعليق التوضيحي التي يتم إرجاعها من واجهة برمجة التطبيقات (API) كلاً من محتوى التعليق التوضيحي والمعلومات الضرورية لعرضه في سياقه الأصلي.

api.genius.com/
الشروحات/10225840
 التفويض: حامل
رمز وصول
راجع التفاصيل حول استخدام رمز الوصول في قسم المصادقة أدناه.
 
الحصول على /التعليقات التوضيحية/:id
بيانات لتعليق توضيحي محدد.

معرف معرف التعليق التوضيحي
10225840
text\_format تنسيق للنصوص ذات الصلة بالمستند. واحد أو أكثر من dom، عادي، وhtml، مفصولة بفواصل (افتراضيات dom). انظر تفاصيل كل خيار هنا
تنسيق النص
ما بعد / التعليقات التوضيحية
يتطلب النطاق: create\_annotation

إنشاء تعليق توضيحي جديد على صفحة ويب عامة. ستكون القيمة التي تم إرجاعها هي كائن التعليق التوضيحي الجديد، بنفس الشكل الذي سيتم إرجاعه بواسطة GET /annotation/:id بمعرف التعليق التوضيحي الجديد.

مثال الحمولة:
{
 "حاشية. ملاحظة": {
 "جسم": {
 "تخفيض السعر": "مرحبًا \*\*العالم!\*\*"
 }
 },
 "مرجع": {
 "raw\_annotatatable\_url": "http://seejohncode.com/2014/01/27/vim-commands-piping/",
 "جزء": "تنفيذ الأوامر"،
 "السياق\_للعرض\_العرض": {
 "before\_html": "ربما تعلم أنك تستطيع ذلك"،
 "after\_html": "من داخل vim، باستخدام أمر vim:"
 }
 },
 "صفحة على الإنترنت": {
 "canonical\_url": فارغ،
 "og\_url": فارغ،
 "العنوان": "سر المانا"
 }
}
حاشية. ملاحظة
إظهار معلمات الطفل
مرجع
إظهار معلمات الطفل
صفحة على الإنترنت
مطلوب واحد على الأقل
إظهار معلمات الطفل
وضع /التعليقات التوضيحية/:id
يتطلب النطاق: إدارة\_التعليق التوضيحي

يقوم بتحديث التعليق التوضيحي الذي أنشأه المستخدم الذي تمت مصادقته. يقبل نفس المعلمات مثل POST /annotation أعلاه.

حذف /التعليقات التوضيحية/:id
يتطلب النطاق: إدارة\_التعليق التوضيحي

يحذف التعليق التوضيحي الذي أنشأه المستخدم المصادق عليه.

PUT /annotations/:id/upvote
يتطلب النطاق: التصويت

يصوت بشكل إيجابي للتعليق التوضيحي نيابة عن المستخدم المصادق عليه.

PUT /annotations/:id/downvote
يتطلب النطاق: التصويت

التصويت سلبيًا للتعليق التوضيحي نيابةً عن المستخدم المصادق عليه.

PUT /annotations/:id/unvote
يتطلب النطاق: التصويت

إزالة تصويت المستخدم المصادق عليه (لأعلى أو لأسفل) للتعليق التوضيحي.

المراجع
المراجع هي أقسام جزء من المحتوى التي يتم إرفاق التعليقات التوضيحية بها. يرتبط كل مرجع بصفحة ويب أو أغنية وقد يحتوي على تعليق توضيحي واحد أو أكثر. يمكن البحث عن المراجع من خلال المستند المرفق بها أو من خلال المستخدم الذي قام بإنشائها.

عند إنشاء تعليق توضيحي جديد، يتم إنشاء مرجع معه أو يتم إرفاق هذا التعليق التوضيحي بمرجع موجود.

api.genius.com/
المراجع؟web\_page\_id=10347
 التفويض: حامل
رمز وصول
راجع التفاصيل حول استخدام رمز الوصول في قسم المصادقة أدناه.
 
الحصول على / المراجع
المراجع حسب عنصر المحتوى أو المستخدم المسؤول عن التعليق التوضيحي المضمن.

يمكنك تمرير معرف واحد فقط من الأغنية\_id وweb\_page\_id، وليس كليهما.

معرف\_by\_id الذي تم إنشاؤه للمستخدم للحصول على مراجع له
معرف المستخدم
معرف الأغنية\_id للأغنية للحصول على مراجع لها
معرف الأغنية
معرف web\_page\_id لصفحة الويب للحصول على مراجع لها
10347
text\_format تنسيق للنصوص ذات الصلة بالمستند. واحد أو أكثر من dom، عادي، وhtml، مفصولة بفواصل (افتراضيات dom). انظر تفاصيل كل خيار هنا
تنسيق النص
لكل\_صفحة عدد النتائج المراد إرجاعها لكل طلب
لكل صفحة
إزاحة الصفحة المرقّمة، (على سبيل المثال، per\_page=5&page=3 تقوم بإرجاع الأغاني من 11 إلى 15)
صفحة
أغاني
الأغنية هي مستند مستضاف على Genius. انها عادة كلمات الموسيقى.

تتضمن بيانات الأغنية تفاصيل حول المستند نفسه ومعلومات حول جميع المراجع المرفقة به، بما في ذلك النص الذي تشير إليه.

api.genius.com/
الأغاني/378195
 التفويض: حامل
رمز وصول
راجع التفاصيل حول استخدام رمز الوصول في قسم المصادقة أدناه.
 
الحصول على / الأغاني /: معرف
بيانات لأغنية معينة.

معرف معرف الأغنية
378195
text\_format تنسيق للنصوص ذات الصلة بالمستند. واحد أو أكثر من dom، عادي، وhtml، مفصولة بفواصل (افتراضيات dom). انظر تفاصيل كل خيار هنا
تنسيق النص
الفنانين
الفنان هو الطريقة التي يمثل بها Genius منشئ أغنية واحدة أو أكثر (أو المستندات الأخرى المستضافة على Genius). عادة ما يكون موسيقيًا أو مجموعة من الموسيقيين.

api.genius.com/
الفنانين/16775
 التفويض: حامل
رمز وصول
راجع التفاصيل حول استخدام رمز الوصول في قسم المصادقة أدناه.
 
الحصول على / الفنانين /: معرف
بيانات لفنان معين.

معرف الفنان
16775
text\_format تنسيق للنصوص ذات الصلة بالمستند. واحد أو أكثر من dom، عادي، وhtml، مفصولة بفواصل (افتراضيات dom). انظر تفاصيل كل خيار هنا
تنسيق النص
api.genius.com/
فنانين/16775/أغاني
 التفويض: حامل
رمز وصول
راجع التفاصيل حول استخدام رمز الوصول في قسم المصادقة أدناه.
 
احصل على /فنانين/:id/songs
المستندات (الأغاني) للفنان المحدد. بشكل افتراضي، يتم إرجاع 20 عنصرًا لكل طلب.

معرف الفنان.
16775
فرز العنوان (الافتراضي) أو الشعبية
نوع
لكل\_صفحة عدد النتائج المراد إرجاعها لكل طلب
لكل صفحة
إزاحة الصفحة المرقّمة، (على سبيل المثال، per\_page=5&page=3 تقوم بإرجاع الأغاني من 11 إلى 15)
صفحة
صفحات الانترنت
صفحة الويب هي صفحة واحدة يمكن الوصول إليها بشكل عام ويمكن إرفاق التعليقات التوضيحية بها. تقوم صفحات الويب بتعيين 1 إلى 1 باستخدام عناوين URL الأساسية الفريدة.

api.genius.com/
web\_pages/lookup?raw\_annotatable\_url=https%3A%2F%2Fdocs.genius.com
 التفويض: حامل
رمز وصول
راجع التفاصيل حول استخدام رمز الوصول في قسم المصادقة أدناه.
 
الحصول على /web\_pages/lookup
معلومات حول صفحة ويب تم استردادها بواسطة عنوان URL الكامل للصفحة (بما في ذلك البروتوكول). تتضمن البيانات التي تم إرجاعها معرف Genius للصفحة، والذي يمكن استخدامه للبحث عن المراجع المرتبطة بنقطة النهاية /references.

البيانات متاحة فقط للصفحات التي تحتوي بالفعل على تعليق توضيحي واحد على الأقل.

قم بتوفير أكبر عدد ممكن من المتغيرات التالية لعنوان URL:

Raw\_annotatatable\_url عنوان URL كما يظهر في المتصفح
https://docs.genius.com
canonical\_url عنوان URL كما هو محدد بواسطة علامة <link> المناسبة في <head> بالصفحة
عنوان URL الأساسي
og\_url عنوان URL كما هو محدد بواسطة علامة og:url <meta> في <head> بالصفحة
عنوان URL لـ OG
يبحث
تغطي إمكانية البحث جميع المحتويات المستضافة على Genius (جميع الأغاني).

api.genius.com/
search?q=كيندريك%20لامار
 التفويض: حامل
رمز وصول
راجع التفاصيل حول استخدام رمز الوصول في قسم المصادقة أدناه.
 
الحصول على / البحث
ابحث في المستندات المستضافة على Genius.

ف المصطلح المراد البحث عنه
كندريك لامار
حساب
تتضمن معلومات الحساب معلومات اتصال عامة وتفاصيل خاصة بـ Genius حول المستخدم.

api.genius.com/
حساب
 التفويض: حامل
رمز وصول
راجع التفاصيل حول استخدام رمز الوصول في قسم المصادقة أدناه.
 
الحصول على /الحساب
يتطلب النطاق: أنا

معلومات الحساب للمستخدم المصادق عليه حاليا.

text\_format تنسيق للنصوص ذات الصلة بالمستند. واحد أو أكثر من dom، عادي، وhtml، مفصولة بفواصل (افتراضيات dom). انظر تفاصيل كل خيار هنا
تنسيق النص
المصادقة
الوصول إلى التطبيقات بدون مستخدمين
إذا كان تطبيقك لا يتضمن سلوكيات خاصة بالمستخدم، فيمكنك استخدام رمز وصول العميل المرتبط بواجهة برمجة التطبيقات الخاصة بك بدلاً من الرموز المميزة للمستخدمين المصادق عليهم. هذه الرموز المميزة صالحة فقط لنقاط النهاية للقراءة فقط غير المقيدة بالنطاق المطلوب.

يمكنك الحصول على رمز وصول العميل بالنقر فوق "إنشاء رمز وصول" في صفحة إدارة عميل API.

يستخدم Genius معيار OAuth2 لإجراء مكالمات API نيابة عن المستخدمين الفرديين. تتم مصادقة الطلبات باستخدام رمز وصول مرسل في رأس HTTP (أو كمعلمة طلب إذا لزم الأمر).

يجب أن يتم كل التفاعل مع واجهة برمجة التطبيقات (API) عبر HTTPS.

سيبدو طلب المثال كما يلي:

https://api.genius.com/oauth/authorize?
Client\_id=YOUR\_CLIENT\_ID&
إعادة التوجيه\_uri=YOUR\_REDIRECT\_URI&
النطاق=مطلوب\_SCOPE&
الحالة=SOME\_STATE\_VALUE&
استجابة\_نوع=رمز
الحصول على رمز الوصول
ابدأ بتوجيه مستخدم تطبيقك إلى صفحة مصادقة Genius على https://api.genius.com/oauth/authorize باستخدام معلمات الاستعلام التالية:

Client\_id: معرف عميل التطبيق الخاص بك، كما هو مدرج في صفحة إدارة عميل API
redirect\_uri: سيقوم URI Genius بإعادة توجيه المستخدم إلى بعد أن يأذن لتطبيقك؛ ويجب أن يكون هو نفسه الذي تم تعيينه لعميل واجهة برمجة التطبيقات (API) على صفحة الإدارة
النطاق: الأذونات التي يطلبها تطبيقك كقائمة مفصولة بمسافات (انظر النطاقات المتاحة أدناه)
الحالة: القيمة التي سيتم إرجاعها مع إعادة توجيه التعليمات البرمجية للحفاظ على الحالة التعسفية من خلال عملية التفويض
استجابة\_نوع: دائمًا "رمز"
المزيد عن الدولة
أحد الاستخدامات المهمة لهذه القيمة هو زيادة الأمان - من خلال تضمين قيمة فريدة يصعب تخمينها (على سبيل المثال، تجزئة قيمة جلسة المستخدم)، يمكن منع المهاجمين المحتملين من إرسال عمليات إعادة توجيه زائفة إلى تطبيقك.

في صفحة المصادقة، يمكن للمستخدم اختيار السماح لتطبيقك بالوصول إلى Genius نيابةً عنه. سيُطلب منهم تسجيل الدخول (أو، إذا لزم الأمر، إنشاء حساب) أولاً. ثم تتم إعادة توجيه المستخدم إلى https://YOUR\_REDIRECT\_URI/?code=CODE&state=SOME\_STATE\_VALUE.

يمكن لتطبيقك تبادل معلمة استعلام التعليمات البرمجية من إعادة التوجيه لرمز وصول عن طريق تقديم طلب POST إلى https://api.genius.com/oauth/token مع بيانات نص الطلب التالية:

{
 "code": "الكود\_من\_إعادة التوجيه"،
 "client\_id": "YOUR\_CLIENT\_ID"،
 "client\_secret": "YOUR\_CLIENT\_SECRET",
 "redirect\_uri": "YOUR\_REDIRECT\_URI",
 "نوع_الاستجابة": "الكود",
 "نوع\_المنحة": "رمز_التفويض"
}
الكود: معلمة استعلام الكود من إعادة التوجيه إلى إعادة التوجيه\_uri الخاصة بك
Client\_secret: سر العميل الخاص بالتطبيق الخاص بك، كما هو مدرج في صفحة إدارة عميل API
Grant\_type: "رمز_التفويض" بعيدًا
معرف_العميل: كما هو مذكور أعلاه
إعادة التوجيه\_uri: كما هو مذكور أعلاه
استجابة\_نوع: كما هو مذكور أعلاه
معظم هذه هي نفس القيم المستخدمة في الطلب الأولي.

{
 "access\_token": "ACCESS\_TOKEN"
}
سيكون نص الاستجابة عبارة عن كائن يحتوي على الرمز المميز كقيمة لمفتاح الوصول\_token. احفظ الرمز المميز واستخدمه لتقديم طلبات نيابة عن المستخدم المعتمد.

النطاقات المتاحة
لا يمكن استخدام رموز الوصول إلا للموارد التي تغطيها النطاقات المتوفرة عند إنشائها. هذه هي النطاقات المتاحة ونقاط النهاية التي يمنحون الإذن لها:

نقاط النهاية للنطاق
لي الحصول على /الحساب
إنشاء\_annotation POST /annotations
إدارة\_التعليق التوضيحي PUT /annotations/:id
حذف /التعليقات التوضيحية/:id
التصويت PUT /annotations/:id/upvote
PUT /annotations/:id/downvote
PUT /annotations/:id/unvote
باستخدام رمز الوصول
احصل على /some-endpoint HTTP/1.1
وكيل المستخدم: CompuServe Classic/1.22
قبول: التطبيق/json
المضيف: api.genius.com
التفويض: وصول حامل\_TOKEN
لإجراء طلبات مصادق عليها باستخدام رمز وصول، قم بتضمينه في رأس تفويض HTTP مسبوقًا بكلمة "Bearer" ومسافة. على سبيل المثال، يمكن أن تكون قيمة الرأس هي Bearer 1234tokentokentoken.

يعد تمرير الرمز المميز في رأس التفويض هو الطريقة المفضلة لمصادقة طلبات واجهة برمجة التطبيقات. ومع ذلك، تدعم واجهة برمجة التطبيقات (API) أيضًا توفير الرمز المميز كمعلمة استعلام Access\_token لطلب GET أو عنصر من نص POST.

تنسيق الاستجابة
احصل على https://api.genius.com/web\_pages/lookup?canonical\_url=http://example.com
{
 "ميتا": {
 "الحالة": 200
 },
 "إجابة": {
 "صفحة على الإنترنت": {
 "التعليق التوضيحي\_العدد":7،
 "المعرف": 1480،
 ...
 }
 }
}
جميع استجابات Genius API هي JSON. تحتوي كل استجابة JSON على حقل تعريف بقيمة حالة تمثل عددًا صحيحًا لرمز حالة HTTP للاستجابة.

بالنسبة للطلبات الناجحة، يوجد أيضًا حقل استجابة عالي المستوى والذي سيكون كائنًا متداخلاً. على سبيل المثال، طلب للحصول على تفاصيل حول التعليقات التوضيحية على صفحة ويب:

أخطاء
احصل على https://api.genius.com/apples
{
 "ميتا": {
 "الحالة": 404،
 "الرسالة غير موجودة"
 }
}
في حالة فشل الطلب أو حدوث أخطاء (أي أن تكون قيم الحالة 4xx أو 5xx). سيحتوي حقل التعريف أيضًا على قيمة رسالة عبارة عن سلسلة تحتوي على تفاصيل حول الخطأ. على سبيل المثال، طلب إلى نقطة نهاية API غير موجودة:

تنسيق النص (خيار تنسيق النص\_)
{
 "عادي": "كلمة مضحكة!"،
 "html": "<p>كلمة مضحكة!</p>",
 "دوم": {
 "العلامة": "الجذر"،
 "أطفال": [ {
 "العلامة": "ص"،
 "الأطفال": ["كلمة مضحكة!" ]
 } ]
 }
}
تقبل العديد من طلبات API معلمة استعلام text\_format التي يمكن استخدامها لتحديد كيفية تنسيق محتوى النص. يجب أن تكون قيمة المعلمة واحدة أو أكثر من القيمة plain وhtml وdom. ستكون القيمة التي يتم إرجاعها عبارة عن كائن يحتوي على أزواج من التنسيقات والنتائج ذات القيمة الرئيسية:

عادي هو مجرد نص عادي، لا العلامات
html عبارة عن سلسلة من HTML غير قابلة للإلغاء ومناسبة للعرض بواسطة المتصفح
dom هو كائن متداخل يمثل التسلسل الهرمي لـ HTML DOM والذي يمكن استخدامه لتقديم محتوى منظم برمجيًا

----

اكتب لي تدفق مصادقة NodeJS لواجهة برمجة التطبيقات هذه باستخدام ExpressJS
{"evolved_from": null, "kind": "human", "source": "ewof/sharegpt-instruct-unfiltered-deduped"}