Developer API

The Developer API gives access to the metadata available for all families served by Google Fonts. It allows the creation of dynamic apps by being able to query Google Fonts and get an accurate list of the families currently available. The REST API gives access to the data in the JSON format and includes for each family a list of the styles available as well as a list of scripts (called subsets in Google Fonts) supported. The API gives an option to sort the list of families alphabetically, by date added, by number of styles, by trend or by popularity. More data might be added over time.

Audience

This document is intended for web and application developers; using the Developer API requires knowledge of JavaScript.

A quick example

To retrieve the dynamic list of fonts offered by the Google Fonts service, send the following request:

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

A sample of the result would look like this:

{
 "kind": "webfonts#webfontList",
 "items": [

[...]

{ "kind": "webfonts#webfont", "family": "Anonymous Pro", "variants": [ "regular", "italic", "700", "700italic" ], "subsets": [ "greek", "greek-ext", "cyrillic-ext", "latin-ext", "latin", "cyrillic" ], "version": "v3", "lastModified": "2012-07-25", "files": { "regular": "http://themes.googleusercontent.com/static/fonts/anonymouspro/v3/Zhfjj_gat3waL4JSju74E-V_5zh5b-_HiooIRUBwn1A.ttf", "italic": "http://themes.googleusercontent.com/static/fonts/anonymouspro/v3/q0u6LFHwttnT_69euiDbWKwIsuKDCXG0NQm7BvAgx-c.ttf", "700": "http://themes.googleusercontent.com/static/fonts/anonymouspro/v3/WDf5lZYgdmmKhO8E1AQud--Cz_5MeePnXDAcLNWyBME.ttf", "700italic": "http://themes.googleusercontent.com/static/fonts/anonymouspro/v3/_fVr_XGln-cetWSUc-JpfA1LL9bfs7wyIp6F8OC9RxA.ttf" } }, { "kind": "webfonts#webfont", "family": "Antic", "variants": [ "regular" ], "subsets": [ "latin" ], "version": "v4", "lastModified": "2012-07-25", "files": { "regular": "http://themes.googleusercontent.com/static/fonts/antic/v4/hEa8XCNM7tXGzD0Uk0AipA.ttf" } },

[...]

] }

Identifying your application to Google

Your application needs to identify itself every time it sends a request to the Google Fonts Developer API, by including an API key with each request.

Acquiring and using an API key

Get a Key

Or create one in the Credentials page.

After you have an API key, your application can append the query parameter key=yourAPIKey to all request URLs.

The API key is safe for embedding in URLs; it doesn't need any encoding.

Details

The JSON response (refer to sample above) is composed of an array named "items" which contains objects with information about each font family.

A family object is composed of 4 fields:

  • kind: The kind of object, a webfont object
  • family: The name of the family
  • subsets: A list of scripts supported by the family
  • variants: The different styles available for the family
  • version: The font family version.
  • lastModified: The date (format "yyyy-MM-dd") the font family was modified for the last time.
  • files: The font family files (with all supported scripts) for each one of the available variants.

By combining the information for each family it is easy to create a Fonts API request. For example assuming we have a reference to the family object for 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('');

[...]

The list of families is returned in no particular order by default. It is possible however to sort the list using the sort parameter:

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

The possible sorting values are:

  • alpha: Sort the list alphabetically
  • date: Sort the list by date added (most recent font added or updated first)
  • popularity: Sort the list by popularity (most popular family first)
  • style: Sort the list by number of styles available (family with most styles first)
  • trending: Sort the list by families seeing growth in usage (family seeing the most growth first)