Hide

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.

Contents

  1. Audience
  2. A quick example
  3. Identifying your application to Google
  4. Details

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

To acquire an API key:

  1. Go to the Google Developers Console.
  2. Select a project.
  3. In the sidebar on the left, select APIs & auth. In the list of APIs, make sure the status is ON for the Google Fonts Developer API.
  4. In the sidebar on the left, select Credentials.
  5. The API supports two types of credentials. Create whichever credentials are appropriate for your project:

    • OAuth 2.0: Your application must send an OAuth 2.0 token with any request that accesses private user data. Your application sends a client ID and, possibly, a client secret to obtain a token. You can generate OAuth 2.0 credentials for web applications, service accounts, or installed applications.

    • API keys: A request that does not provide an OAuth 2.0 token must send an API key. The key identifies your project and provides API access, quota, and reports.

      If the key type you need does not already exist, create an API key by selecting Create New Key and then selecting the appropriate key type. Then enter the additional data required for that key type.

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('//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: '//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)

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies.