メインコンテンツまでスキップ

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

get
https://api.mapbox.com/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 parametersTypeDescription
usernamestringThe username of the account to which the font belongs.
fontstringThe name of the font. This endpoint supports queries with a maximum of 10 comma-separated font names.
startintegerA multiple of 256 between 0 and 65280.
endintegerThe 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"
Endpoint support

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

get
https://api.mapbox.com/fonts/v1/{username}
fonts:list

Retrieve a list of fonts for a specific account.

Required parameterTypeDescription
usernamestringThe 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

post
https://api.mapbox.com/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 parameterTypeDescription
usernamestringThe 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
https://api.mapbox.com/fonts/v1/{username}/{font}
fonts:write

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 parameterTypeDescription
usernamestringThe username of the account from which the font will be deleted.
fontstringThe 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

get
https://api.mapbox.com/fonts/v1/{username}/{font}/metadata
fonts:read
Required parameterTypeDescription
usernamestringThe username of the account for which the font metadata will be retrieved.
fontstringThe 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

patch
https://api.mapbox.com/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 parameterTypeDescription
usernamestringThe username of the account for which the font metadata will be updated.
fontstringThe 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 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.
  • 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.
このpageは役に立ちましたか?