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

get
/fonts/v1/{username}/{font}/{start}-{end}.pbf
fonts:read

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.

Required parametersDescription
usernameThe username of the account to which the font belongs.
fontThe name of the font. This endpoint supports queries with a maximum of 10 comma-separated font names.
startA multiple of 256 between 0 and 65280.
endThe number indicated by start, plus 255.

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"
Endpoint support

Mapbox wrapper libraries help you integrate Mapbox APIs into your existing application. The following SDK supports this endpoint:

See the SDK documentation for details and examples of how to use the relevant methods to query this endpoint.

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

get
/fonts/v1/{username}
fonts:list

Retrieve a list of fonts for a specific account.

Required parameterDescription
usernameThe username of the account to which the fonts belong.

Example request: List fonts

$ curl "https://api.mapbox.com/fonts/v1/{username}?access_token=
YOUR MAPBOX ACCESS TOKEN
"

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

post
/fonts/v1/{username}
fonts:write

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.

Required parameterDescription
usernameThe username of the account to which the new font will be added.

Example request: Add a font

curl -X POST "https://api.mapbox.com/fonts/v1/{username}/?access_token=
YOUR MAPBOX ACCESS TOKEN
"
\ --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
/fonts/v1/{username}/{font}
fonts:write

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!

Required parameterDescription
usernameThe username of the account from which the font will be deleted.
fontThe name of the font to delete.

Example request: Delete a font

curl -X DELETE "https://api.mapbox.com/fonts/v1/{username}/Custom Font Regular?access_token=
YOUR MAPBOX ACCESS TOKEN
"

Response: Delete a font

HTTP 204 No Content

Retrieve font metadata

get
/fonts/v1/{username}/{font}/metadata
fonts:read
Required parameterDescription
usernameThe username of the account for which the font metadata will be retrieved.
fontThe name of the font for which the metadata will be retrieved.

Example request: Retrieve font metadata

$ curl "https://api.mapbox.com/fonts/v1/{username}/Custom Font Regular/metadata?access_token=
YOUR MAPBOX ACCESS TOKEN
"

Response: Retrieve font metadata

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

Update font metadata

patch
/fonts/v1/{username}/{font}/metadata
fonts:write

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.

Required parameterDescription
usernameThe username of the account for which the font metadata will be updated.
fontThe name of the font for which the metadata will be updated.

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
"
-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

Response body messageHTTP status codeDescription
Invalid Range400Check the font glyph range. This error can also occur with empty fonts.
Maximum of 10 font faces permitted400Too many font faces in the query.
Not Authorized - No Token401No token was used in the query.
Not Authorized - Invalid Token401Check the access token you used in the query.
Forbidden403There may be an issue with your account. Check your Account page for more details.

In some cases, using an access tokens with URL restrictions can also result in a 403 error. For more information, see our Token management guide.
Not Found404Check the font name or names you used in the query.
Unprocessable Entity422Check the syntax of payload contents of the JSON in your request body when updating metadata.

Fonts API restrictions and limits

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