mapbox-gl-js

Trouble Adding Mapbox Sprite Assets via API vs Studio


I am trying to create a sprite via Mapbox using Sprite API endpoints and can do so successfully via the following endpoint:

PUT https://api.mapbox.com/styles/v1/{{username}}/{{style_id}}/sprite/pin-blue?access_token={{secret_token}}

I understand it may take a few minutes to utilize the new image in the sprite due to caching. However, after well over an hour, I still cannot load the new image on my map (I'm using Mapbox JS GL). I verified that it's in the JSON response and can see it in the sprite image. I have triple-checked the style ID to make sure I'm loading the right one.

https://api.mapbox.com/styles/v1/{{username}}/{{style_id}}/sprite?access_token={{token}}

https://api.mapbox.com/styles/v1/{{username}}/{{style_id}}/sprite.png?access_token={{token}}

Interestingly, if I view the "Images" dropdown in Mapbox Studio, I see a different custom image I uploaded via Studio and can load that image into my map, but I don't see it in the sprite sheet or API responses above (see attached)!

Image shown after uploading via Mapbox Studio

From the documentation (see quoted section below, emphasis mine), it sounds as if I could use either method (API or Upload via Studio) and that the two would reconcile.

  1. Is my assumption that you can use either method incorrect?
  2. How long should I wait to use the new images? The documentation vaguely states that it may take "at least 15 minutes"

You can create a Mapbox-hosted style using Mapbox Studio or the Styles API, which will automatically set your style's sprite property to the correct URL template. You can then upload custom SVG images to your style using Studio or the Styles API single image or batch image endpoints. Any Mapbox APIs that reference a Mapbox-hosted style will build and provide the sprite files automatically.


Solution

  • I was almost there, but I missed a crucial step; you must also submit an update to the style.

    After you have uploaded your sprite images using the Add new image to sprite endpoint or the Add multiple new images to sprite endpoint, make a request to update your style. The response payload for the style update will contain the unique sprite URL on the sprite payload.

    So, quite simply:

    1. Request the configuration of your style and save the resulting JSON to a file:

    https://api.mapbox.com/styles/v1/{{username}}/{{style_id}}?access_token={{token}}

    1. Remove the created and modified fields from the JSON file.

    2. Update your style with the resulting JSON file from Step 2.

    curl -X PATCH "https://api.mapbox.com/styles/v1/{{username}}/{style_id}?access_token={{token}}" \
      --data @updated-json.json \
      --header "Content-Type:application/json"
    

    This will regenerate the path to the sprite and you can verify that it updated via:

    https://api.mapbox.com/styles/v1/{{username}}/{{style_id}}/{{sprite_id_from_response_in_3}}/sprite.png?access_token={{access_token}}