借助 Developer API,您可以访问 Google Fonts 提供的所有字体系列的元数据。它允许应用查询 Google Fonts 以获取可用的字体系列。REST API 以 JSON 格式提供数据,其中包含每个字体系列中的样式和脚本(在 Google Fonts 中称为子集)。该 API 可以按字母顺序、添加日期、样式数量、趋势或热门程度对系列列表进行排序。
受众群体
本文档面向 Web 和应用开发者。使用开发者 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 密钥
或在“凭据”页面中创建一个 OAuth 客户端 ID。
在您获得 API 密钥后,您的应用便可在所有请求网址后附加查询参数 key=yourAPIKey
。
API 密钥可以安全地嵌入网址中;不需要进行任何编码。
详细信息
JSON 响应(请参阅上面的示例)由一个名为“items”的数组组成,其中包含包含每个字体系列的相关信息的对象。
家庭对象由以下字段组成:
- kind:对象的类型,Web 字体对象
- family:系列的名称
- 子集:该系列支持的脚本列表
- menu:指向仅包含家族名称的家族子集的网址。
- 变体:系列可用的不同款式
- version:字体系列版本。
- axes:轴范围,仅在有请求时(见下文)才会显示可变字体。
- lastModified:字体系列上次修改的日期(格式为“yyyy-MM-dd”)。
- files:每个可用变体的字体系列文件(包含所有受支持的脚本)。
通过组合每个字体系列的信息,您可以轻松创建 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:按字母顺序对列表进行排序
- date:按添加日期对列表进行排序(先显示最近添加或更新的字体)
- popularity:按热门程度排序(最热门的家庭优先)
- style:按可用样式数量对列表进行排序(样式数量最多的系列排在前面)
- 趋势:按使用量增长的家庭对列表进行排序(使用量增长最快的家庭排在前面)
过滤
查询特定家庭
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 } ] }, [...] ] }
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
。