ממשק API למפתחים

ממשק ה-API למפתחים מאפשר גישה למטא-נתונים של כל המשפחות שמוצגות ב-Google Fonts. היא מאפשרת לאפליקציות לשלוח שאילתות אל Google Fonts כדי לקבל את משפחות הגופנים הזמינות. ה-REST API מספק נתונים בפורמט JSON שכוללים את הסגנונות והסקריפטים (שנקראים קבוצות משנה ב-Google Fonts) בכל משפחה. ממשק ה-API יכול למיין את רשימת משפחות הגופנים בסדר אלפביתי, לפי תאריך ההוספה, לפי מספר הסגנונות, לפי מגמה או לפי פופולריות.

קהל

המסמך הזה מיועד למפתחי אתרים ואפליקציות. כדי להשתמש ב-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 בכל בקשה.

קבלת מפתח API ושימוש בו

להזמנת מפתח

אפשר גם ליצור מפתח חדש בדף Credentials.

אחרי שיש לכם מפתח API, האפליקציה יכולה להוסיף את פרמטר השאילתה key=yourAPIKey לכל כתובות ה-URL של הבקשות.

מפתח ה-API בטוח להטמעה בכתובות URL, ואין צורך בקידוד.

פרטים

תגובת ה-JSON (כפי שמוצג בדוגמה שלמעלה) מורכבת ממערך בשם items שמכיל אובייקטים עם מידע על כל משפחת גופנים.

אובייקט משפחה מורכב מהשדות הבאים:

• ‫kind: סוג האובייקט, אובייקט של גופן אינטרנט
• family: שם המשפחה
• קבוצות משנה: רשימה של סקריפטים שנתמכים על ידי המשפחה
• תפריט: כתובת URL של קבוצת המשנה המשפחתית, שכוללת רק את שם המשפחה.
• וריאציות: הסגנונות השונים שזמינים למשפחה
• ‫version: גרסת משפחת הגופנים.
• ‫axes: טווח הצירים, מופיע רק לפי בקשה (ראו בהמשך) עבור גופנים משתנים.
• lastModified: התאריך (בפורמט 'yyyy-MM-dd') שבו משפחת הגופנים שונתה בפעם האחרונה.
• ‫files: הקבצים של משפחת הגופנים (עם כל הסקריפטים הנתמכים) לכל אחד מהווריאנטים הזמינים.
• 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('');

[...]

מיון

כברירת מחדל, רשימת המשפחות לא מוחזרת בסדר מסוים. עם זאת, אפשר למיין את הרשימה באמצעות פרמטר המיון:

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 מוגדרת, השדה 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 של API

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

‫your_key: מפתח ה-API של המפתח.

‫family: שם של משפחת גופנים.

‫subset: שם של קבוצת משנה של גופן.

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

capability: VF | WOFF2.

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