واجهة برمجة التطبيقات لمطوّري البرامج

تتيح واجهة برمجة التطبيقات للمطوّرين الوصول إلى البيانات الوصفية لجميع مجموعات الخطوط التي توفّرها Google Fonts. ويسمح للتطبيقات بالبحث في Google Fonts عن مجموعات الخطوط المتاحة. توفّر واجهة برمجة التطبيقات REST بيانات بتنسيق JSON تتضمّن الأنماط والبرامج النصية (المعروفة باسم المجموعات الفرعية في Google Fonts) في كل عائلة خطوط. يمكن لواجهة برمجة التطبيقات ترتيب قائمة العائلات أبجديًا أو حسب تاريخ الإضافة أو عدد الأنماط أو الرواج أو مدى الاستخدام.

الجمهور

هذا المستند مخصّص لمطوّري الويب والتطبيقات. يتطلّب استخدام Developer API معرفة بلغة JavaScript.

مثال سريع

لاسترداد القائمة الديناميكية للخطوط التي تقدّمها خدمة Google Fonts، أرسِل الطلب التالي:

https://www.googleapis.com/webfonts/v1/webfonts?key=YOUR-API-KEY

في ما يلي عيّنة من النتيجة:

{
 "kind": "webfonts#webfontList",
 "items": [
  [...]
  {
    "family": "Anonymous Pro",
    "variants": [
      "regular",
      "italic",
      "700",
      "700italic"
    ],
    "subsets": [
      "cyrillic",
      "greek",
      "latin",
      "latin-ext"
    ],
    "version": "v21",
    "lastModified": "2022-09-22",
    "files": {
      "regular": "http://fonts.gstatic.com/s/anonymouspro/v21/rP2Bp2a15UIB7Un-bOeISG3pLlw89CH98Ko.ttf",
      "italic": "http://fonts.gstatic.com/s/anonymouspro/v21/rP2fp2a15UIB7Un-bOeISG3pHl428AP44Kqr2Q.ttf",
      "700": "http://fonts.gstatic.com/s/anonymouspro/v21/rP2cp2a15UIB7Un-bOeISG3pFuAT0CnW7KOywKo.ttf",
      "700italic": "http://fonts.gstatic.com/s/anonymouspro/v21/rP2ap2a15UIB7Un-bOeISG3pHl4OTCzc6IG30KqB9Q.ttf"
    },
    "category": "monospace",
    "kind": "webfonts#webfont",
    "menu": "http://fonts.gstatic.com/s/anonymouspro/v21/rP2Bp2a15UIB7Un-bOeISG3pHl028A.ttf"
  },
  {
    "family": "Antic",
    "variants": [
      "regular"
    ],
    "subsets": [
      "latin"
    ],
    "version": "v19",
    "lastModified": "2022-09-22",
    "files": {
      "regular": "http://fonts.gstatic.com/s/antic/v19/TuGfUVB8XY5DRaZLodgzydtk.ttf"
    },
    "category": "sans-serif",
    "kind": "webfonts#webfont",
    "menu": "http://fonts.gstatic.com/s/antic/v19/TuGfUVB8XY5DRZZKq9w.ttf"
  },
  [...]
 ]
}

تحديد تطبيقك لدى Google

يجب أن يحدّد تطبيقك هويته في كل مرة يرسل فيها طلبًا إلى Google Fonts Developer API، وذلك من خلال تضمين مفتاح API مع كل طلب.

الحصول على مفتاح واجهة برمجة التطبيقات واستخدامه

الحصول على مفتاح

أو أنشئ واحدًا في صفحة بيانات الاعتماد.

بعد الحصول على مفتاح واجهة برمجة التطبيقات، يمكن لتطبيقك إضافة مَعلمة طلب البحث key=yourAPIKey إلى جميع عناوين URL الخاصة بالطلبات.

مفتاح واجهة برمجة التطبيقات آمن للتضمين في عناوين URL، ولا يحتاج إلى أي ترميز.

التفاصيل

يتألف ردّ JSON (يُرجى الرجوع إلى النموذج أعلاه) من مصفوفة باسم "items" تحتوي على عناصر تتضمّن معلومات حول كل مجموعة خطوط.

يتألف عنصر العائلة من الحقول التالية:

• kind: نوع العنصر، وهو عنصر خط ويب
• family: اسم العائلة
• المجموعات الفرعية: قائمة بالبرامج النصية التي تتوافق مع العائلة
• القائمة: عنوان URL لمجموعة فرعية من العائلة لا تتضمّن سوى اسم العائلة
• الخيارات: الأنماط المختلفة المتاحة للعائلة
• الإصدار: إصدار مجموعة الخطوط.
• المحاور: نطاق المحور، يتم عرضه عند الطلب فقط (راجِع أدناه) للخطوط المتغيرة.
• lastModified: يشير إلى تاريخ آخر تعديل لمجموعة الخطوط (بالتنسيق "yyyy-MM-dd").
• الملفات: ملفات مجموعة الخطوط (مع جميع النصوص البرمجية المتوافقة) لكل صيغة من الصيغ المتاحة.
• ‫color_capabilities: تنسيقات الألوان التي تتوافق مع هذه السلسلة، إن وُجدت
• العلامات: العلامات التي تنطبق على مساحة التصميم بأكملها لهذه العائلات. يتم عرضها فقط عند الطلب (راجِع أدناه).

من خلال الجمع بين المعلومات الخاصة بكل عائلة، يصبح من السهل إنشاء طلب Fonts API. على سبيل المثال، لنفترض أنّ لدينا مرجعًا إلى كائن العائلة الخاص بـ Anonymous Pro:

[...]

var apiUrl = [];
apiUrl.push('https://fonts.googleapis.com/css?family=');
apiUrl.push(anonymousPro.family.replace(/ /g, '+'));
if (contains('italic', anonymousPro.variants)) {
  apiUrl.push(':');
  apiUrl.push('italic');
}
if (contains('greek', anonymousPro.subsets)) {
  apiUrl.push('&subset=');
  apiUrl.push('greek');
}

// url: 'https://fonts.googleapis.com/css?family=Anonymous+Pro:italic&subset=greek'
var url = apiUrl.join('');

[...]

ترتيب

لا يتم عرض قائمة العائلات بترتيب معيّن تلقائيًا. ومع ذلك، يمكن ترتيب القائمة باستخدام المَعلمة sort:

https://www.googleapis.com/webfonts/v1/webfonts?sort=popularity

قيم الترتيب المحتملة هي:

• alpha: ترتيب القائمة أبجديًا
• التاريخ: لترتيب القائمة حسب تاريخ الإضافة (يظهر الخط الأحدث إضافةً أو تعديلاً أولاً)
• الشهرة: لترتيب القائمة حسب الشهرة (تظهر العائلة الأكثر شهرة أولاً)
• النمط: ترتيب القائمة حسب عدد الأنماط المتاحة (العائلة التي تتضمّن أكبر عدد من الأنماط أولاً)
• الأكثر رواجًا: ترتيب القائمة حسب العائلات التي تشهد زيادة في الاستخدام (العائلة التي تشهد أكبر زيادة أولاً)

الفلترة

طلب معلومات عن عائلة معيّنة

https://www.googleapis.com/webfonts/v1/webfonts?family=family_name

جميع العائلات التي تتوافق مع مجموعة فرعية من اللغة اليونانية

https://www.googleapis.com/webfonts/v1/webfonts?subset=subset_name

الفلترة حسب فئة الخط

https://www.googleapis.com/webfonts/v1/webfonts?category=category_name

التحسين

لاسترداد ملفات الخطوط المضغوطة بتنسيق woff2

https://www.googleapis.com/webfonts/v1/webfonts?capability=WOFF2

الخطوط المتغيّرة

توفّر الخطوط المتغيرة نطاقات مستمرة من الأنماط. يتم تلقائيًا عرض مجموعة من ملفات الخطوط الثابتة للخطوط المتغيرة التي تم إنشاؤها في مواضع عادية. في حال ضبط capability=VF، يتم عرض ملف الخط المتغير بدلاً من الملفات الثابتة مع البيانات الوصفية لنطاق المحاور المتاح. مثال:

https://www.googleapis.com/webfonts/v1/webfonts?capability=VF

نموذج الردّ:

{
 "kind": "webfonts#webfontList",
 "items": [
  [...]
  {
    "family": "Noto Sans Display",
    "variants": [
      "regular",
      "italic"
    ],
    "subsets": [
      "cyrillic",
      "cyrillic-ext",
      "greek",
      "greek-ext",
      "latin",
      "latin-ext",
      "vietnamese"
    ],
    "version": "v20",
    "lastModified": "2022-09-22",
    "files": {
      "regular": "http://fonts.gstatic.com/s/notosansdisplay/v20/RLplK4fy6r6tOBEJg0IAKzqdFZVZxokvfn_BDLxR.ttf",
      "italic": "http://fonts.gstatic.com/s/notosansdisplay/v20/RLpjK4fy6r6tOBEJg0IAKzqdFZVZxrktdHvjCaxRgew.ttf"
    },
    "category": "sans-serif",
    "kind": "webfonts#webfont",
    "menu": "http://fonts.gstatic.com/s/notosansdisplay/v20/RLpbK4fy6r6tOBEJg0IAKzqdFZVZxpMkXJMhnB9XjO1o90LuV-PT4Doq_AKp_3cKZTCa3g.ttf",
    "axes": [
      {
        "tag": "wdth",
        "start": 62.5,
        "end": 100
      },
      {
        "tag": "wght",
        "start": 100,
        "end": 900
      }
    ]
  },
  [...]
 ]
}

العلامات

في حال ضبط capability=FAMILY_TAGS، سيتم ملء حقل العلامات بجميع العلامات ذات الصلة بمساحة التصميم الكاملة للعائلة.

مثال على النموذج:

{
 "kind": "webfonts#webfontList",
 "items": [
  [...]
  {
    "family": "Noto Sans Display",
    "variants": [
      "regular",
      "italic"
    ],
    "subsets": [
      "cyrillic",
      "cyrillic-ext",
      "greek",
      "greek-ext",
      "latin",
      "latin-ext",
      "vietnamese"
    ],
    "version": "v20",
    "lastModified": "2022-09-22",
    "files": {
      "regular": "http://fonts.gstatic.com/s/notosansdisplay/v20/RLplK4fy6r6tOBEJg0IAKzqdFZVZxokvfn_BDLxR.ttf",
      "italic": "http://fonts.gstatic.com/s/notosansdisplay/v20/RLpjK4fy6r6tOBEJg0IAKzqdFZVZxrktdHvjCaxRgew.ttf"
    },
    "category": "sans-serif",
    "kind": "webfonts#webfont",
    "menu": "http://fonts.gstatic.com/s/notosansdisplay/v20/RLpbK4fy6r6tOBEJg0IAKzqdFZVZxpMkXJMhnB9XjO1o90LuV-PT4Doq_AKp_3cKZTCa3g.ttf",
    "tags": [
      {
        "name": "/Expressive/Business",
        "weight": 58
      },
      {
        "tag": "/Sans/Humanist",
        "weight": 100,
      }
    ]
  },
  [...]
 ]
}

مواصفات عنوان URL لواجهة برمجة التطبيقات

webfonts?key=<your_key>[&family=<family>][&subset=<subset>][&capability=<capability>...][&sort=<sort>]

your_key: مفتاح واجهة برمجة التطبيقات الخاص بالمطوّر.

family: اسم مجموعة خطوط

subset: اسم مجموعة فرعية من الخطوط

category: serif | sans-serif | monospace | display | handwriting

capability: VF | WOFF2.

sort: alpha | date | popularity | style | trending.