Fonts API
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.
| Required parameters | Type | Description |
|---|---|---|
username | string | The username of the account to which the font belongs. |
font | string | The name of the font. This endpoint supports queries with a maximum of 10 comma-separated font names. |
start | integer | A multiple of 256 between 0 and 65280. |
end | integer | The number indicated by start, plus 255. |
Example request: Retrieve font glyph ranges
$ curl "https://api.mapbox.com/fonts/v1/YOUR_MAPBOX_USERNAME/Arial%20Unicode%20MS%20Regular/0-255.pbf?access_token=YOUR_MAPBOX_ACCESS_TOKEN"
Mapbox wrapper libraries help you integrate Mapbox APIs into your existing application. The following SDK supports this endpoint:- Mapbox JavaScript SDKSee 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
Retrieve a list of fonts for a specific account.
| Required parameter | Type | Description |
|---|---|---|
username | string | The username of the account to which the fonts belong. |
Example request: List fonts
$ curl "https://api.mapbox.com/fonts/v1/YOUR_MAPBOX_USERNAME?access_token=YOUR_SECRET_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
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 parameter | Type | Description |
|---|---|---|
username | string | The 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/YOUR_MAPBOX_USERNAME/?access_token=YOUR_SECRET_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": "YOUR_MAPBOX_USERNAME",
"visibility": "private"
}
Delete a font
Delete a font from your account. WARNING: If you delete a font that's used by a map style, it may break your map!
| Required parameter | Type | Description |
|---|---|---|
username | string | The username of the account from which the font will be deleted. |
font | string | The name of the font to delete. |
Example request: Delete a font
curl -X DELETE "https://api.mapbox.com/fonts/v1/YOUR_MAPBOX_USERNAME/Custom Font Regular?access_token=YOUR_SECRET_MAPBOX_ACCESS_TOKEN"
Response: Delete a font
HTTP 204 No Content
Retrieve font metadata
| Required parameter | Type | Description |
|---|---|---|
username | string | The username of the account for which the font metadata will be retrieved. |
font | string | The name of the font for which the metadata will be retrieved. |
Example request: Retrieve font metadata
$ curl "https://api.mapbox.com/fonts/v1/YOUR_MAPBOX_USERNAME/Custom Font Regular/metadata?access_token=YOUR_SECRET_MAPBOX_ACCESS_TOKEN"
Response: Retrieve font metadata
{
"family_name": "Custom Font",
"style_name": "Regular",
"owner": "YOUR_MAPBOX_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.
| Required parameter | Type | Description |
|---|---|---|
username | string | The username of the account for which the font metadata will be updated. |
font | string | The 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/YOUR_MAPBOX_USERNAME/Custom Font Regular/metadata?access_token=YOUR_SECRET_MAPBOX_ACCESS_TOKEN" -H "Content-Type: application/json" -d '{"visibility": "public"}'
Response: Update font metadata
{
"family_name": "Custom Font",
"style_name": "Regular",
"owner": "YOUR_MAPBOX_USERNAME",
"visibility": "public"
}
Fonts API errors
Response body message | HTTP status code | Description |
|---|---|---|
Invalid Range | 400 | Check the font glyph range. This error can also occur with empty fonts. |
Maximum of 10 font faces permitted | 400 | Too many font faces in the query. |
Not Authorized - No Token | 401 | No token was used in the query. |
Not Authorized - Invalid Token | 401 | Check the access token you used in the query. |
Forbidden | 403 | There 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 Found | 404 | Check the font name or names you used in the query. |
Unprocessable Entity | 422 | Check 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.
- Responses from the Fonts API set both the device and CDN TTLs to 10 days.
- For general information on caching, see the Maps APIs caching troubleshooting guide.