مرجع API
نقطة نهاية واحدة وعدة أزرار تحكم وطريقتا مصادقة.
هل تحتاج إلى مسار ترحيل قبل المرجع؟
ابدأ بـ دليل بديل Clearbit أو دليل مشتري logo API.
يكشف ClearLogo عن نقطة نهاية HTTP واحدة،
GET /logo/{domain}، التي تُرجع صورة PNG (أو WebP/JPEG) لشعار المجال بنسبة ثابتة على خلفية معتمة تتناسب مع الخلفية (بيضاء للوضع الفاتح، ومحايدة داكنة للوضع الداكن). الاستخدام المجهول يعمل للاختبار منخفض الحجم؛ تستخدم حركة الإنتاج مفتاح متصفح (عميل) أو مفتاح خادم (خلفية).
نقطة النهاية
GET https://api.clearlogo.dev/logo/:domain
:domain هو اسم مضيف بدون مخطط أو مسار، على سبيل المثال github.com. تُرجع API صورة image/png بشكل افتراضي.
معاملات الاستعلام
| الاسم | النوع | القيمة الافتراضية | ملاحظات |
|---|---|---|---|
size | number | 128 | بُعد النتيجة بالبكسل. مربع فقط. القيم المسموح بها: 16, 32, 48, 64, 96, 128, 192, 256, 512, 1024. |
frame | fill, original | fill | fill يملأ اللوحة (مطروحاً منها الهوامش) بالمحتوى المرئي للشعار، متجاهلاً المساحة البيضاء المصدر. original يحافظ على الإطار والنسب الأصلية للأيقونة المصدر. |
padding | number | 10 | الهامش من كل جانب حول المحتوى المؤطر، كنسبة مئوية من اللوحة (0–20، خطوة 5). |
shape | square, circle | square | square هو التأطير القياسي. circle يضع الشعار داخل دائرة محاطة بمربع حتى لا يُقص في الصور الرمزية الدائرية — المخرجات لا تزال صورة مربعة بدون قناع شفافية. |
part | full, logo, text | full | يحدد أي جزء من الشعار يتم تقديمه — full (الشعار كاملاً)، أو logo (الأيقونة/العلامة)، أو text (الكلمة التجارية) — للمجالات التي تم تقسيم شعارها. إذا لم يكن الجزء المطلوب متاحاً، يتراجع تلقائياً إلى الشعار الكامل (أو يُرجع صورة شفافة للشعارات المُدارة كأجزاء منفصلة). قد تكون الأجزاء نقطية (PNG) وتُعرض بألوانها الحقيقية. |
format | png | webp | jpeg | png | صيغة الإخراج. يُتفاوض تلقائياً من خلال رأس Accept — تتلقى المتصفحات الحديثة WebP تلقائياً عبر <img>. |
theme | light | dark | light | يُرجع المتغير الداكن عند توفره، وإلا يُرجع الفاتح. يضبط أيضاً الخلفية المعتمة: بيضاء لـ light، ومحايدة داكنة لـ dark. |
token | string | — | مفتاح المتصفح المستخدم من كود العميل. يجب أن يطابق Origin أو Referer مجالاً مسموحًا في المفتاح. |
طلب نموذجي باستخدام معاملات الضبط الرئيسية:
GET https://api.clearlogo.dev/logo/github.com?size=128&frame=fill&padding=10&shape=square
طلب أيقونة/علامة فقط لشعار مقسّم باستخدام part:
GET https://api.clearlogo.dev/logo/github.com?size=128&part=logo
المصادقة
تعمل الطلبات المجهولة لاختبار منخفض الحجم. لحركة الإنتاج استخدم مفتاح متصفح (عميل) أو مفتاح خادم (خلفية):
المتصفح
<img
src="https://api.clearlogo.dev/logo/example.com?token=YOUR_BROWSER_KEY"
alt="" />
الخادم
curl \
-H "Authorization: Bearer YOUR_SERVER_KEY" \
"https://api.clearlogo.dev/logo/example.com"
تحديد المعدل
يتم إرجاع حدود لكل مفتاح في رؤوس X-RateLimit-*. عند تجاوزها يرد API برمز 429 ويتضمن تلميح Retry-After.
الأسئلة الشائعة
كيف أحصل على شعار لمجال؟
أرسل طلب GET إلى https://api.clearlogo.dev/logo/{domain} حيث {domain} هو اسم مضيف مثل github.com. لا يلزم تسجيل الدخول لاختبار منخفض الحجم. الاستجابة هي PNG افتراضياً وتعمل مباشرة في علامات <img>.
ما الفرق بين مفتاح المتصفح ومفتاح الخادم؟
مفتاح المتصفح آمن للنشر في كود الواجهة الأمامية وعلامات <img>؛ يتم التحقق من الطلبات مقابل المجالات المسموح بها التي تكوّنها في المفتاح. مفتاح الخادم يُصادق عبر رأس Authorization: Bearer من خلفيتك ويجب ألا يصل أبداً إلى المتصفح.
ما صيغ الإخراج المدعومة؟
png (افتراضي)، webp، و jpeg. عند حذف معامل format، يتفاوض ClearLogo على المحتوى من رأس طلب Accept — تتلقى المتصفحات الحديثة WebP تلقائياً عند تحميل API عبر علامة <img>.
ما تحديدات المعدل؟
تُعاد حدود كل مفتاح في رؤوس الاستجابة X-RateLimit-Limit و X-RateLimit-Remaining و X-RateLimit-Reset. تجاوز الحد يُرجع HTTP 429 مع تلميح Retry-After يشير إلى عدد الثواني للانتظار قبل إعادة المحاولة.
هل يمكنني الحصول على خلفية شفافة أو قصاصة مربعة؟
المخرجات دائماً صورة مربعة معتمة — لا يوجد متغير شفاف. تتطابق الخلفية مع theme: بيضاء لـ light ومحايدة داكنة لـ dark. داخل هذه اللوحة المربعة تتحكم في التأطير: frame (fill, original) يختار بين ملء اللوحة بمحتوى الشعار أو الحفاظ على نسب الأيقونة المصدر الأصلية، padding (0–20، خطوة 5) يضبط الهامش من كل جانب، و shape (square, circle) يضع الشعار داخل دائرة محاطة بمربع عند الضبط على circle (لا تزال تُعرض على صورة مربعة). استخدم size (المسموح: 16, 32, 48, 64, 96, 128, 192, 256, 512, 1024) للبُعد الدقيق بالبكسل. للمجالات التي تم تقسيم شعارها، يُتيح part (full, logo, text) اختيار الشعار كاملاً (full، الافتراضي)، أو الأيقونة/العلامة (logo)، أو الكلمة التجارية (text)، مع التراجع إلى الشعار الكامل عند عدم توفر الجزء المطلوب (أو إرجاع صورة شفافة للشعارات المُدارة كأجزاء منفصلة).