Google Fonts
Catalog of ~2,000 open-source font families served by Google Fonts. One read endpoint returns the entire catalog with metadata for each family: variants, scripts, file URLs, variable-font axes, and semantic tags. Use filters to narrow before sorting, and ask for capability flags when you need richer metadata than the defaults.
Data Model
- Family — top-level unit. Identified by family name (e.g. Roboto, Noto Sans JP). Names are case-sensitive and human-formatted.
- Variants — per-family styles. regular, italic, plus numeric weights (100..900) and weight+italic combos (700italic). Variable-font families collapse all of these into a single file when capability=VF is requested.
- Subsets — Unicode script coverage tags (latin, latin-ext, cyrillic, cyrillic-ext, greek, vietnamese, arabic, hebrew, devanagari, thai, chinese-simplified, japanese, korean, …). Always filter by subset before recommending a family for non-Latin text — many popular Latin families have zero Cyrillic or CJK coverage.
- Category — coarse classification: serif | sans-serif | monospace | display | handwriting. Display and handwriting are decorative; body text should come from serif/sans-serif/monospace.
- Files — direct .ttf (or .woff2 with capability=WOFF2) URLs keyed by variant. Hosted on Google's static font CDN.
- Axes (present only with capability=VF) — variable-font axis ranges. Common tags: wght (weight 100–900), wdth (width 62.5–125), slnt (slant), ital (italic), opsz (optical size).
- Tags (present only with capability=FAMILY_TAGS) — hand-curated semantic taxonomy. Examples: Sans Humanist, Sans Geometric, Serif Transitional, Expressive Business, Expressive Playful, Calligraphy Brush. Each tag carries a 0–100 weight indicating fit strength. This is the only way the catalog answers "find a font that feels X".
Sort Modes
- popularity — current usage volume (Open Sans, Roboto, Inter dominate).
- trending — recent growth rate (often surfaces brand-new Noto language coverage and Playwrite handwriting variants).
- date — newest-added first.
- style — most variants first (good for picking a family with a full weight ramp).
- alpha — alphabetical.
- Default (no sort) — unspecified order.
Filtering Patterns
- Pick a code font: category=monospace + sort=popularity then take the first few results (JetBrains Mono, Inconsolata, Source Code Pro, Roboto Mono).
- Cover a non-Latin script: subset=cyrillic (or arabic, devanagari, …) + sort=popularity. Pair with category if the design constraint matters.
- One specific family: family=Inter — returns a single item. A name the catalog does not carry does not come back empty: it reports available: false with reason google_webfonts_family_not_found. Treat that as "search instead" and re-call without family.
- Semantic / mood selection: capability=FAMILY_TAGS + browse the tags array on returned families. There is no server-side filter on tag value; do the matching client-side after the call.
- Variable fonts only: capability=VF — every returned family will carry an axes array and a single variable file per variant group.
Embedding in web pages
The Developer catalog returns metadata and download URLs. To embed in a webpage, build a stylesheet link to Google's separate CSS font service — it does not use this catalog key.
URL grammar for CSS links:
- Spaces in family names become + (Noto Sans JP → Noto+Sans+JP).
- Pin weights with :wght@400;700 for static, :wght@100..900 for variable.
- Italic/upright pairs use the ital,wght@0,400;1,400 form.
- Append &display=swap to avoid invisible-text flash during font load.
If a downstream task only needs the CSS URL, build it from the family and variants fields — no further catalog call required.
Gotchas
- Catalog size: the unfiltered endpoint returns ~1.5 MB of JSON. Use limit + summary_only while browsing, then drop both once you've picked a family and need files.
- No pagination: filters reduce the result set, but there is no offset / page_token. Sort + limit is the only way to get "top N".
- Family name exactness: family= requires the canonical form, including capitalisation and spacing. Roboto Mono works; Roboto-Mono, roboto-mono, and inter all report available: false rather than matching loosely.
- Only open-source families exist here: licensed faces (Avenir Next, Helvetica Neue, Proxima Nova, SF Pro) are not in the catalog at any capitalisation. When a user names one, search by category + sort=popularity for a substitute instead of retrying the name.
- Variants vs. files: variants is a flat list of style identifiers; files is the keyed download URL map. Use files[variant] to download, variants to list options to a user.
- axes is empty without capability=VF: even for genuinely variable families like Inter or Recursive, you only see the axis ranges when you ask for them.
- tags is empty without capability=FAMILY_TAGS: same opt-in pattern.
- Color fonts: color_capabilities lists supported color formats (COLRv0, COLRv1, SVG) on a small subset of families (e.g. emoji, decorative). Treat absence as "monochrome".
- License: every catalog family is open-source (Open Font License, Apache 2.0, or Ubuntu Font License). Commercial embedding is permitted; attribution is encouraged, not required by the catalog surface.
