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.
| 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/{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:
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
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/{username}?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/{username}/?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 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 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/{username}/Custom Font Regular?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/{username}/Custom Font Regular/metadata?access_token="
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.
| 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/{username}/Custom Font Regular/metadata?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 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, please see the Maps APIs caching troubleshooting guide.