Fonts

The Mapbox Fonts API accepts fonts as raw binary data, allows those fonts to be deleted, and generates encoded letters for map renderers. Two types of fonts are supported: TrueType fonts, usually with .ttf file extensions, and OpenType fonts, with .otf extensions.

Fonts are managed on a per-account basis. Styles can use any font from the same account.

Retrieve font glyph ranges

While glyph ranges are usually not of interest unless you're building a map renderer, this is the endpoint you can use to access them.

Font glyph ranges are protocol buffer-encoded signed distance fields. They can be used to show fonts at a variety of scales and rotations. One glyph is used at all scales.

Example request: Retrieve font glyph ranges

$ curl "https://api.mapbox.com/fonts/v1/{username}/Arial%20Unicode%20MS%20Regular/0-255.pbf?access_token=YOUR_MAPBOX_ACCESS_TOKEN"

Response: Retrieve font glyph ranges

A successful request will return HTTP 200 Success. The response body will be a buffer of the glyphs with Content-Type: application/x-protobuf.

Note: For historical reasons, this API will ignore the 'Accept-Encoding' header, and always encode the response with gzip.

List fonts

Retrieve a list of fonts for a specific account.

Example request: List fonts

$ curl "https://api.mapbox.com/fonts/v1/{username}?access_token=
YOUR_MAPBOX_ACCESS_TOKEN
This endpoint requires a token with fonts:list scope.
"

Response: List fonts

This endpoint returns an array of font names.

Example response: List fonts

["Custom Font Regular","Custom Font Italic","Custom Font Bold"]

Add a font

Adds a font to your account. The posted font must conform to the True Type Font (.ttf) or Open Type Font (.otf) file type. Invalid files will produce a descriptive validation error.

Example request: Add a font

curl -X POST "https://api.mapbox.com/fonts/v1/{username}/?access_token=
YOUR_MAPBOX_ACCESS_TOKEN
This endpoint requires a token with fonts:write scope.
" \
  --data-binary @PermanentMarker-Regular.ttf

Response: Add a font

The response will contain metadata about the font including family_name, style_name, owner, and visibility.

Example response: Add a font

{
  "family_name": "Permanent Marker",
  "style_name": "Regular",
  "owner": "{username}",
  "visibility": "private"
}

Delete a font

Delete a font from your account. WARNING: If you delete a font that's currently used by a map style, it may break your map!

Example request: Delete a font

curl -X DELETE "https://api.mapbox.com/fonts/v1/{username}/Custom Font Regular?access_token=
YOUR_MAPBOX_ACCESS_TOKEN
This endpoint requires a token with fonts:write scope.
"

Response: Delete a font

HTTP 204 No Content

Retrieve font metadata

Example request: Retrieve font metadata

$ curl "https://api.mapbox.com/fonts/v1/{username}/Custom Font Regular/metadata?access_token=
YOUR_MAPBOX_ACCESS_TOKEN
This endpoint requires a token with fonts:read scope.
"

Response: Retrieve font metadata

{
  "family_name": "Custom Font",
  "style_name": "Regular",
  "owner": "{username}",
  "visibility": "public"
}

Update font metadata

Update the visibility property of font metadata. Although the metadata contains a few properties, only visibility can be changed. The only valid values for visibility are public and private.

Example request: Update font metadata

$ curl -X PATCH "https://api.mapbox.com/fonts/v1/{username}/Custom Font Regular/metadata?access_token=
YOUR_MAPBOX_ACCESS_TOKEN
This endpoint requires a token with fonts:write scope.
" -H "Content-Type: application/json" -d '{"visibility": "public"}'

Response: Update font metadata

{
  "family_name": "Custom Font",
  "style_name": "Regular",
  "owner": "{username}",
  "visibility": "public"
}

Fonts API errors

Fonts API restrictions and limits

• Fonts must be smaller than 30 MB.
• Accounts are limited to 100 fonts.