API Hop

الوثائق

وثائق API Hop

SimilarwebAPI

>-

توفر SimilarwebAPI عددًا قدره 27 نقطة نهاية للبيانات للقراءة فقط تحت /v1/similarweb. استخدم الحساب ومفتاح API والرصيد وسجل الاستخدام نفسها المستخدمة مع واجهات API Hop الأخرى. يعتمد التوفر على تفعيل البوابة وصلاحيات مفتاح API؛ ولا تؤكد الوثائق توفر الخدمة في بيئة الإنتاج.

المصادقة

أرسل مفتاح API الخاص بك في API Hop، وليس بيانات اعتماد جهة خارجية:

http
Authorization: Bearer YOUR_API_KEY

مثال طلب

تستخدم جميع العمليات العامة GET مع معاملات استعلام ودون نص طلب. حافظ على حالة الأحرف في المسارات والمعاملات كما وردت في الوثائق تمامًا.

تُدعم البيانات العالمية فقط (country=999). تُحوَّل قيم البلدان الأخرى الصالحة إلى 999 قبل إرسال الطلب إلى المزوّد، وتعيد بيانات عالمية لا بيانات خاصة ببلد معين.

في نقاط النهاية التي تقبل التواريخ، تكون الأولوية لنطاق from/to الصريح والكامل والصالح. وفي نقاط النهاية التي تقبل latest، يجب أن تجتاز القيمة المقدّمة التحقق المعتاد من التنسيق والقواعد الخاصة بنقطة النهاية، لكن تُتجاهل عند اختيار النطاق ولا تُرسل إلى Similarweb؛ ولا تُضاف قيمة افتراضية لـ latest. دون نطاق صريح، لا يتغير سلوك latest والقيم الافتراضية والنوافذ الزمنية المعتاد. تظل قيود السجل سارية، وتظل نقاط النهاية التي لا تقبل latest ترفضه.

bash
curl --get "https://api.apihop.ai/v1/similarweb/websites/incoming-referrals" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "key=example.com" \
  --data-urlencode "country=999" \
  --data-urlencode "page=1"

تستخدم الإحالات الواردة اسم مضيف واحدًا في key بالأحرف الصغيرة، وليس keys. يُعد key هذا معامل استعلام وظيفيًا للموقع المستهدف، وليس بيانات اعتماد API؛ ويُسمح به فقط في مسارات Similarweb GET المدرجة صراحةً في قائمة السماح. تظل مصادقة API تستخدم Authorization، وتظل حقول بيانات الاعتماد الأخرى في الاستعلام محظورة. تُعاد الصفوف في Records وليس Data. راجع مرجع نقاط النهاية الكامل لمعرفة الحقول الدقيقة لكل عملية.

نطاق التغطية

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

الاستجابات

تحافظ الاستجابات الناجحة على نص JSON الأصلي دون غلاف success/data جديد. وتبقى أسماء الحقول والحقول غير المعروفة والمصفوفات الفارغة والدقة العددية دون تغيير. قد تعيد نقاط النهاية المختلفة Data أو Records أو تنسيقًا أصليًا آخر؛ فلا تفترض وجود حقل موحد للصفوف.

لا تعني النتيجة الناجحة الفارغة أن النطاق لا يستقبل زيارات. يجب ألا تُعامل الطلبات الفاشلة كبيانات فارغة. احتفظ بـ X-Request-Id ووقت الطلب لاستكشاف المشكلات.

الفوترة وتقسيم الصفحات

السعر القياسي هو $0.0005 لكل طلب ناجح، أو $0.50 لكل 1,000 طلب، عبر نقاط النهاية الـ 27 كلها. تكون الفوترة لكل طلب وليس لكل صف؛ وتُحتسب النتيجة الناجحة الفارغة طلبًا واحدًا أيضًا. كل صفحة لاحقة طلب مستقل. تكون الأولوية للتسعير الخاص بالحساب عند إعداده. لا تُنفَّذ الطلبات ذات المعاملات غير الصالحة أو التفويض المفقود أو الرصيد غير الكافي بوصفها استدعاءات ناجحة قابلة للفوترة. ولا تُفرض رسوم على الطلبات الفاشلة لدى المزوّد.

يجب أن يتوفر في حسابك $0.10 على الأقل قبل الاستدعاء، وفق سياسة الحد الأدنى للرصيد في المنصة. وتظل الرسوم القياسية $0.0005 لكل طلب ناجح.

استخدم فقط حقول تقسيم الصفحات الموثقة لنقطة النهاية المختارة. يبدأ ترقيم الصفحات عادةً من 1؛ وتستخدم الروابط الخلفية Page وPageSize، بينما قد تستخدم جداول أخرى page أو pageSize أو rowsPerPage. لا ترسل حقول حجم صفحات غير مدعومة.

الأخطاء

تستخدم أخطاء المنصة التنسيق التالي؛ ويمثل code رمزًا وظيفيًا خاصًا بالمنصة، وليس حالة HTTP:

json
{"success":false,"error":{"code":10000,"message":"Invalid request parameters"},"requestId":"..."}

تشمل حالات HTTP الشائعة 400 لاستعلام غير صالح، و401 لمفتاح API غير صالح، و402 لرصيد غير كافٍ، و403 لرفض الوصول إلى البوابة، و429 لبلوغ حد المعدل، و5xx لإخفاق مؤقت لدى المزوّد أو الخدمة. لا تعاود إرسال الطلبات غير الصحيحة دون تعديل.