Forem: Mapbox

A GUI editor for Mapbox Color Themes

Chris Whong — Tue, 03 Mar 2026 17:38:03 +0000

Introducing a browser-based prototype tool for iterating on custom Mapbox Standard Style themes in real time — no terminal required.

tl;dr: Open the Mapbox Standard Style Theme Editor →

Maps are a visual medium, and color is one of the most powerful tools in a cartographer's toolkit. Whether you're building a dark-mode experience for a nighttime delivery app, a muted editorial look for a data visualization, or a vivid branded style for a consumer product, the color of your basemap sets the entire tone.

Mapbox Standard — Mapbox's premier basemap style — supports deep color customization through a mechanism called Lookup Tables (LUTs). Most developers haven't encountered LUTs before. They're more at home in film post-production than web development. But once you understand how they work, they're an elegant and powerful way to retheme a map.

This post explains what LUTs are, how Mapbox Standard uses them, and introduces a prototype web tool I built for experimenting with custom color themes in real time: the Mapbox Standard Style Theme Editor.

The Mapbox Standard Style

Mapbox Standard is Mapbox's flagship basemap. It features 3D buildings, photorealistic landmarks, dynamic lighting, and a set of built-in configuration options that make it easy to adapt for a wide range of use cases.

For many applications, the quickest path to a custom look is the lightPreset option, which controls ambient and directional lighting to simulate different times of day — dawn, day, dusk, or night. Combined with predefined theme options like faded, and monochrome, you can achieve a lot without writing much code.

Below you can see Mapbox Standard with its default color theme and daytime light as compared to the night lighting preset and monochrome theme, creating a subdued dark basemap:

You can also control some colors in Mapbox Standard via the configuration options, such as colorWater, colorLand, colorGreenSpace, etc, so a Lookup Table is not required to start customizing colors on the map.

You can try out the preset themes and individual color config options in the Mapbox Standard Style Playground.

But for those who want event more control over the color palette, Mapbox Standard supports setting theme to custom and supplying your own Lookup Table.

What Exactly Is a LUT?

A Lookup Table — or LUT — is a data structure that maps input color values to output color values. In image and video processing, a LUT is typically encoded as a small image (sometimes called a "HALD CLUT" or "color cube") where each pixel's position in the image encodes an input RGB value, and its color encodes the corresponding output.

Think of it as a complete color transformation recipe. Every possible input color has a predetermined output, and the LUT defines that mapping across the entire visible spectrum at once. Apply the LUT to any image, and every pixel is remapped accordingly.

This image shows the "identity LUT", with no colors modified. It's a png with a repeating set of "squares" laid out horizontally. Each square shows red values along the x-axis, and green values along the y-axis. If you can mentally stack the squares, they become a cube, with blue values along the z-axis. The cube represents all possible color values and is used to map any input color to a corresponding output color.

In video production, LUTs create consistent "looks" — film emulation, color grading, log-to-linear conversions. In photography, they power the one-click preset packs ubiquitous in Lightroom marketplaces. In Mapbox Standard, they're the engine behind custom color themes.

The key insight is that the LUT doesn't know or care what it's being applied to. It just says: "If you see this color, output that color." Mapbox Standard renders the map to an intermediate image, applies your LUT, and out comes a fully rethemed map — buildings, roads, labels, land, water — all transformed consistently.

Here is a custom LUT that applies a 15-degree hue rotation and increased saturation.

At first glance it looks the same as the identity LUT above, but look closely and you'll see subtle differences. You can see it applied to both a standalone image (from wikimedia commons), and to the Mapbox Standard Style below:

Try this handy LUT tool by Tony Gratzer to see how different LUTs affect an input image.

Where Do LUTs Come From?

Download one

There's a whole ecosystem of pre-made LUTs available online — similar to stock photography. Sites like Fixthephoto and RocketStock offer free and paid collections. Searching for "free HALD CLUT" will surface many more.

Build one in Photoshop

Photoshop's color grading tools — Curves, Hue/Saturation, Color Balance — can be applied to a standard identity LUT image and then exported. If you're working with a designer, this is a natural fit. Mapbox has a step-by-step tutorial here: Create a custom color theme with Photoshop.

Build one in the browser

Several web-based tools let you create LUTs without any desktop software. LUT Maker by o-l-l-i provides sliders for hue rotation, saturation, brightness, contrast, and more, and exports the result as a PNG.

The Challenge: Iterating on Custom Themes in a Mapbox Map

When I set out to learn custom theming in Mapbox Standard, I arrived at what felt like the natural iteration loop:

Open a browser-based LUT editor and adjust the sliders
Export the LUT as a PNG
Base64-encode it in the terminal: base64 -i my-lut.png | pbcopy
Open the Mapbox Standard Style Playground
Paste the string into the theme field
Look at the result on the map
Go back to step 1

This worked. But it was tedious. Each iteration meant downloading a file, switching to the terminal, running a command, switching windows, and pasting a very long string — just to preview one change. For something as tactile and visual as color grading, that friction destroys creative momentum.

The fix was obvious: put the LUT editor and the map in the same window.

That's exactly what the Mapbox GL Theme Editor does.

Introducing the Mapbox GL Theme Editor

→ Try it now

The tool is a single-page web app pairing a LUT generation UI with a live Mapbox Standard map. It's open source and hosted on GitHub Pages.

Global controls

The main panel applies broad color adjustments across the entire palette:

Hue rotation — shifts all colors around the color wheel
Saturation — makes colors more vivid or more muted
Brightness — lightens or darkens the overall output
Contrast — expands or compresses the tonal range
Temperature — pushes the palette warmer (golden) or cooler (blue)

Drag any slider and the LUT preview in the sidebar updates instantly — and so does the map.

Targeted color corrections

For more surgical edits, the tool includes a color correction mode. An eyedropper lets you select a specific color on the map — the blue of the water, the tan of building facades, the green of parks — and remap it to a different hue. A tolerance slider controls how broadly neighboring colors are pulled along.

This is the right tool when you want to make precise changes: darken just the water, push the buildings to a warmer gray, or give vegetation a more stylized tint — without affecting anything else. The image below shows a targeted color correction changing water from light blue to light violet with low tolerance.

Warning: The Mapbox Standard Style is in active development and default colors could change in the future. An LUT with targeted color corrections may not apply as expected if the input color changes in a future release of Mapbox Standard.

Using Your Theme

You can use the LUT you create in the theme editor in your real-world map development:

In Mapbox Studio

In Mapbox Studio, apply a custom LUT by navigating to the Standard style's theme settings, setting the theme to "Custom" and uploading your LUT as an image file.

In the Standard Style Playground

You can also test directly in the Mapbox Standard Style Playground by setting the theme to custom and pasting in the base64 encoded string for your LUT. You can combine your custom theme with other Standard configuration options — toggling 3D buildings, point-of-interest labels, light presets — and see how they interact.

The Standard Style Playground also provides handy code snippets for applying your theme at runtime in Mapbox GL JS or the Mapbox Mobile Maps SDKs.

In your frontend code

You can use the base64 encoded string in your frontend code when using Mapbox GL JS or the Maps SDKs for iOS and Android along with the theme and theme-data Mapbox Standard Style config properties.

Here's an example of how to instantiate a web map using the Mapbox Standard Style and a custom theme in a web project:

const map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/standard',
  config: {
    basemap: {
      theme: 'custom',
      'theme-data': YOUR_LUT_STRING
    }
  },
  center: [-73.99059, 40.74012],
  zoom: 11.50
});

Why Build a Custom Tool?

Beyond solving the iteration problem, there was an educational motivation for building this.

LUTs are unfamiliar territory for most web and mobile developers. The best way to build intuition for how they work is to play with one — to drag a hue slider and immediately see every green park on the map turn magenta, or to pick the water with an eyedropper and watch the rivers shift from steel blue to teal. The tool makes an abstract concept concrete in a way that documentation simply can't.

It also demystifies the pipeline. When the LUT preview image updates in the same window as the map, you can see exactly what a LUT is and what it does. You start to understand why cranking contrast makes building shadows punch harder, or why rotating the hue by 180 degrees turns a daylight city into something that looks like a photo negative. That understanding makes you a more intentional user of the feature.

On the practical side, the faster loop changes the quality of the work. Color choices that used to require five minutes of file-downloading and clipboard gymnastics now take five seconds of slider dragging. That's not just a time savings — it's the difference between exploring ten variations and exploring a hundred.

What's Next?

This is a prototype. It works and it's fun to use, but there's room to grow. The repo is open source at github.com/chriswhong/mapboxgl-theme-editor. Issues and pull requests are welcome. And there's a conversation worth having about whether this kind of functionality should eventually live inside Mapbox Studio or the Standard Style Playground — or whether the complexity of a dedicated theming workflow makes it better as its own tool.

Give It a Try

The best way to understand LUTs and custom theming in Mapbox Standard is to open the tool and start dragging sliders. It takes about thirty seconds before you're looking at a map that doesn't look like any map you've seen before.

Open the Mapbox Standard Style Theme Editor →

When you find a look you like, grab the base64 string and drop it into your project — or share a screenshot and tell me what you made.

How Lemontree improved map performance with a small refactor

Chris Whong — Fri, 13 Feb 2026 21:51:45 +0000

A Q&A with Samuel Cole, CTO of Lemontree

Lemontree is a New York-based nonprofit on a mission to fight food insecurity by connecting hungry Americans to free food resources near them. Often described as a "Yelp for food banks," they curate and manage rich data on thousands of food pantries across the U.S., making it accessible through an easy-to-use digital platform with maps, SMS alerts, and more. In 2025, Lemontree helped over a million people locate nearby food pantries.

At the heart of their product is an interactive map — powered by Mapbox GL JS — that lets users instantly see nearby pantry locations, hours, and available foods. Recently, Lemontree overhauled how they load and display map data to dramatically improve performance. We sat down with Samuel Cole, CTO of Lemontree, to learn how they approached the problem and what they'd do differently from the start.

Chris: Let's start with the original setup. What were you displaying on the map, where did the data come from, and what was falling short in terms of user experience?

Samuel: When we load a map, we first call an endpoint to find the best 10 resources for the focus point of the map using our AI sorting algorithm, but then we don't want you to miss out on the other resources in the area, so we built an API called markersWithinBounds that returns all the resources within the bounding box of the map. These are visualized as many smaller background markers in addition to the larger "best 10 resources" markers.

We're using react-map-gl so it was straightforward to loop over the results of that api call with a .map() and create a component for each one. When we first built that, we were testing pretty zoomed in to a few blocks around the location, so while the density of food pantries is pretty high (there are more food pantries in the US than McDonalds!), it seemed like it was scaling ok, because most people are only interested in the immediate area.

But in real life, pretty much everybody immediately zoomed out! All of a sudden the API call returned thousands of points, and rendering thousands of Markers on the screens was chugging. Users' whole device was lagging and slow, and then if they started panning around? It was wild.

Zooming out on the map triggered an API call for new data and could contain hundreds of points or more.

Chris: This is a classic Mapbox GL JS pitfall that catches a lot of developers by surprise. Markers are the most intuitive way to get point features on a map — the API is simple, positioning is easy, and you can drop in a custom image without much fuss. But they're rendered as individual DOM elements, which means performance degrades quickly as the count climbs. Beyond a few hundred markers, you're fighting the browser itself. After you hit this wall, what solutions did you explore, and how did you arrive at the right path forward?

Samuel: When I was preparing my talk for the BUILD with Mapbox virtual conference, you actually pulled me aside and said: "Hey, if you used a symbol layer for this it would scale a ton better."

Chris: Ah, well you were in the right place to get a direct suggestion! Hopefully this post will help a lot more people who might be hitting the same issue. Symbol layers are rendered by the GPU as part of the map's WebGL canvas, which means they handle thousands of points with ease and pan or zoom without any jank. The tradeoff is that they're less intuitive to set up, especially in a React codebase where you're used to thinking declaratively. Can you walk us through what the refactor actually looked like?

Samuel: We have a lot going on at Lemontree! I wasn't able 📍 immediately prioritize that work, but one Friday I took it on as sort of a 'hack day' project. Unfortunately, I got a bit stuck because the react-map-gl <Layer> component, which was declarative in the React style, was being added before the style was loaded, and I just ran out of time in my hack day to figure it out. When I got access to AI-assisted development through Copilot and Claude Code, I was looking for little test cases, and I remembered this performance issue: I asked Claude, it added an styleLoaded && pattern, and we were off to the races! You can compare the code for the Marker implementation vs the Symbol layer:

Before: Markers 📍

 {/* Old approach: Render a DOM marker for each resource */}
  {otherMarkersData?.features.map((feature) => (
    <Marker
      key={feature.properties.id}
      latitude={feature.geometry.coordinates[1]}
      longitude={feature.geometry.coordinates[0]}
    >
      <Image
        src={purplePin}
        alt="Resource"
        width={20}
        height={25}
        style={{ cursor: 'pointer' }}
        onClick={() => router.push(`/resources/${feature.properties.id}`)}
      />
    </Marker>
  ))}

Problems:

Creates a DOM node for every marker (100s+ of elements)
Heavy re-renders when panning/zooming
Poor performance with many markers
Limited styling options

After: Symbol Layer 🚀

{/* New approach: Single GeoJSON source with symbol layer */}
  <Source
    id="other-resources"
    type="geojson"
    data={filteredOtherMarkersData}
    promoteId="id"
  >
    <Layer
      id="other-resources-layer"
      type="symbol"
      layout={{
        'icon-image': 'purpleMarker',
        'icon-allow-overlap': true,
      }}
    />
  </Source>

Benefits:

Single GeoJSON source for all markers
GPU-accelerated rendering
Smooth performance with 1000+ markers
Feature state for hover effects
Click/hover handled via interactiveLayerIds

Performance Impact:

10x faster rendering
Butter-smooth panning and zooming
Reduced memory footprint

Chris: That's a great example of AI tooling unblocking a task that kept slipping down the priority list. The styleLoaded guard is a small but critical detail — symbol layers depend on the map style being fully initialized before you can add sources or layers to the canvas at runtime, and it's an easy thing to miss until things break in subtle ways. What has the impact been since shipping? Are users noticing the difference?

Samuel: Our clients are spending a bit more time exploring around the map, but honestly our recommendation algorithm gives plenty of food pantries near where they live, so in surprising ways exploring the map isn't their primary way of discovering food resources, and they use the map more for navigating the pantries we've already referred them to. Where the map really shines is with our partners! Organizations that run many pantries love to see their whole network, foundations love to see our coverage, and governments are interested in how food access is working in their districts.

Chris: That's a fascinating insight — power users for the map include the partner organizations doing network-level planning, not just the end users trying to find nearby food. It reframes what "map performance" means for your product. Speaking of which, you've been building on Mapbox for a long time. What's your overall take on the platform — what's working well, and where do you think there's room to grow?

Samuel: We love Mapbox; I've been using maps for my whole career, ever since my very first tech startup job, and Mapbox reflects my values for open, accessible, and extensible maps. The reality is that other mapping providers just don't offer the extensibility of Mapbox's platform, whenever I want to create a more targeted experience (which I believe people experiencing food insecurity deserve the best experiences!) the out-of-the-box approach from other map providers, just isn't going to cut it. I don't want a Google Map, I want a Lemontree Map.

Chris: "I don't want a Google Map, I want a Lemontree Map" — I love that. Mapbox gives you all you need to make the whole map experience your own creation. What's on the roadmap next for mapping at Lemontree?

Samuel: I love maps! Around Lemontree, my coworkers all call me the map guy. I think as we grow, it's going to be even more important for our partners to visualize how food access works around the U.S., so I'm excited to make more visualizations to tell stories like "Where are the food pantries that focus on elderly people in New Jersey, and where are the gaps?" There are almost 50 million people who experience food insecurity in the US, and we have a lot of work to do to understand where they are, and what resources they have available to them.

Chris: Great, hopefully Mapbox maps can help with that data storytelling to raise awareness about food insecurity. Thanks for chatting with me about your map's technical hiccup and the fix. I'm glad to hear the map is performing better, especially given the importance of the data you're displaying on it.

Takeaways

Lemontree's Markers to symbol layer refactor is a great case study in a problem many Mapbox developers encounter: Markers and symbol layers are both valid tools for displaying point data, but they have very different performance profiles.

Markers are DOM elements — straightforward to set up, but expensive to render at scale. Symbol layers are drawn by WebGL on the map's canvas, making them capable of displaying tens of thousands of points without breaking a sweat. If you're showing dynamic data that can grow beyond a few hundred points, a symbol layer is almost always the right call.

These graphics help explain the difference between Markers, which are DOM elements displayed "on the map" versus symbol layers which are rendered "in the map"

For teams building in React with react-map-gl, the key implementation detail is guarding your layer additions behind a styleLoaded check — a small fix that, as Samuel found, can make the difference between a polished experience and a broken one. (the equivalent when using Mapbox GL JS without a wrapping library is listening for the map.on(style.load) event.

You can learn more about when to use Markers versus symbol layers in the Add your Data guide in the Mapbox GL JS documentation.

Squarespace X Mapbox

Chris Whong — Thu, 12 Feb 2026 14:48:12 +0000

How to Add an Interactive Mapbox Map to Your Squarespace Website

This guide shows developers how to integrate Mapbox GL JS into a Squarespace website using Squarespace's embed block. If you're already familiar with Mapbox GL JS development and want to add custom interactive maps to your Squarespace site, this post will show you exactly where to place your code to get it working.

✅ What this guide covers: The technical steps to embed Mapbox GL JS code in a Squarespace website
❌ What this guide doesn't cover: Details of interactive map development with Mapbox GL JS (the examples are a great place to start for inspiration and working code snippets)

We'll show a simple example of displaying a business location with a marker, popup, and rotating camera to demonstrate the integration. Once you understand where the code goes and how it's structured in Squarespace, you can implement any Mapbox GL JS functionality you need by changing the JavaScript code.

Here's a codepen so you can get a better look at the actual map and animation shown in this guide. It uses the Mapbox Standard Style as a basemap, showing detailed 3D buildings and an optional monochrome theme. The popup is styled to match the green colors used on the Squarespace site it is embedded in:

Note: This technique of adding custom HTML, CSS and JavaScript via the Squarespace editor is suitable for simpler Mapbox GL JS implementations but does not include version control or other benefits of a separate development workflow. If your map becomes more complex, you may want to deploy it as a standalone web app, then embed it in your Squarespace site using its URL.

Prerequisites

To follow this guide, you'll need:

A Squarespace website
Working knowledge of Mapbox GL JS - you should be comfortable writing HTML, CSS, and JavaScript to create maps
A Mapbox account and access token - if you don't have one yet, sign up here

Getting Your Mapbox Access Token

Before we start, you'll need a Mapbox access token:

Go to mapbox.com and sign up for a free account (if you don't have one)
Once logged in, navigate to your console
Find the "Tokens" link in the left sidebar to go to the tokens page
Copy your default public token (it starts with pk.)

Keep this token handy—you'll need it in a moment.

Step 1: Adding the Code Block

Let's add the HTML that will contain your map code:

Open your Squarespace Editor and navigate to the page where you want to add the map
Click the + ADD BLOCK button
Scroll down in the block selection panel to find "Embed"
Drag and resize the embed block to position it wherever you want it on your site layout.
Double-click on the embed block to open its Content settings panel. Under EMBED AS, choose Code Snippet, then click the Embed Data button.
A code editor will appear. You will add code to this input in the next step.

Step 2: Add Mapbox GL JS Code

Now you'll add Mapbox GL JS code to get a map working in the code block. The code block accepts any HTML, so you can include CSS and JavaScript by using <style> and <script> tags.

Here's a working example that shows a business location with a marker and rotating camera. Copy this code and replace YOUR_MAPBOX_ACCESS_TOKEN with your actual access token:

<!-- import Mapbox GL JS and its CSS file -->
<script src='https://api.mapbox.com/mapbox-gl-js/v3.18.1/mapbox-gl.js'></script>
<link href='https://api.mapbox.com/mapbox-gl-js/v3.18.1/mapbox-gl.css' rel='stylesheet' />

<!-- override default styles for the map and popup -->
<style>
  .mapboxgl-popup-content {
    background-color: #e6f2d2;
    color: #2f5f48;
  }
</style>

<!-- add a container element for the map -->
<div id="map-container" style="position: absolute; height: 100%; width: 100%"></div>

<script>
  // your Mapbox access token
  mapboxgl.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN';

  // initialize the map
  const map = new mapboxgl.Map({
    container: 'map-container', // container ID
    style: 'mapbox://styles/mapbox/standard', // style URL
    center: [-73.99986, 40.75300], // starting position [lng, lat]
    zoom: 15.36, // starting zoom
    bearing: 28.00, // bearing in degrees
    pitch: 56.50, // pitch in degrees
    config: {
      basemap: {
        theme: 'monochrome', // use the monochrome basemap theme
        showPointOfInterestLabels: false // hide point of interest labels
      }
    }
  });

  // disable scroll zoom so the map won't zoom as the user scrolls down the page
  map.scrollZoom.disable();

  // create a popup with address details and a link to get directions on Google Maps
  const popup = new mapboxgl.Popup({
    closeOnClick: false,
    closeButton: false,
    offset: 40,
  }).setHTML(
    `<div>
      450 W 33rd St<br/>
      New York, NY 10001</div>
      <a href="https://maps.app.goo.gl/6WzErvMBMi2Hn64Z7" target="_blank" rel="noopener noreferrer"><span class="text-xs">Get Directions</span></a>
    `
  );

  // create a map marker with a custom color, connect the popup, add it to the map, and open the popup
  new mapboxgl.Marker({
    color: '#2f5f48'
  })
    .setLngLat([-73.99986, 40.75300])
    .setPopup(popup)
    .addTo(map)
    .togglePopup();

  // this function rotates the camera continuously
  // see https://docs.mapbox.com/mapbox-gl-js/example/animate-camera-around-point/
  function rotateCamera(timestamp) {
    map.rotateTo((timestamp / 200) % 360, { duration: 0 });
    requestAnimationFrame(rotateCamera);
  }

  map.on('load', () => {
    // start the camera animation.
    rotateCamera(0);
  })
</script>

Paste the Mapbox GL JS snippet from above into the code editor.

Important: Replace the placeholder text YOUR_MAPBOX_ACCESS_TOKEN with the actual token you copied from your Mapbox account.

Click anywhere outside the editor panel to apply your code update. You will see a warning about embedded scripts, with an option to preview in safe mode. This is normal, as Squarespace prevents execution of JavaScript code in the editor by default.

Exit the editor. You should see an animated map with a monochrome basemap, a marker centered over New York City, and a slowly rotating camera. That's it, you're ready to publish this map on your site!

Understanding the Code Structure

Here's how the code for this example map breaks down:

1. Library Imports

<script src='https://api.mapbox.com/mapbox-gl-js/v3.18.1/mapbox-gl.js'></script>
<link href='https://api.mapbox.com/mapbox-gl-js/v3.18.1/mapbox-gl.css' rel='stylesheet' />

These load Mapbox GL JS and its required stylesheet from the Mapbox CDN.

2. Custom Styles

<style>
  .mapboxgl-popup-content {
    background-color: #e6f2d2;
    color: #2f5f48;
  }
</style>

The popup styles customize the appearance to match the page theme.

3. Map Container

<div id="map-container" style="position: absolute; height: 100%; width: 100%"></div>

This div is where the map renders. The inline styles ensure it fills the available space.

4. Your Map Logic

<script>
  // All your Mapbox GL JS code goes here
</script>

This is where you implement your map functionality. In this example, we're:

Setting the access token
Initializing the map with specific style and camera settings
Disabling scroll zoom (important for Squarespace pages!)
Creating a popup and marker
Adding a camera rotation animation

You can replace or extend this code with any Mapbox GL JS functionality you need.

If you want to adapt this example of a single marker and popup, you should:

Change the map's center point, zoom, pitch and bearing to your desired initial camera view.
Change the Marker's coordinates
Change the Popup's content by editing the HTML code in Popup.setHTML()

Or, you can leave the imports and the map container in place and start over with the map JavaScript code and build whatever you need. See additional developer resources below.

Resources for Mapbox GL JS Development

Here are essential resources for building your map functionality:

Mapbox Documentation

Mapbox GL JS Examples - Dozens of live, interactive code examples
Mapbox GL JS Guides
Mapbox GL JS API Reference - Complete documentation of all map methods and options

Key Examples

Display a map - Basic map initialization
Add markers to a map - Working with markers
Display a popup - Popup functionality
Add GeoJSON data - Display custom data

Community

r/mapbox on Reddit - Get help and share ideas
Mapbox Developer Discord - Post in the #web channel to ask questions and share what you build.

Troubleshooting

Map not displaying?

Verify you've replaced YOUR_MAPBOX_ACCESS_TOKEN with your actual token
Check that your access token has the correct permissions
Ensure the code block has sufficient height and width in the Squarespace editor and that the map container div also has sufficient height and width
Open your browser's developer console to check for JavaScript errors

By following the steps in this guide, you should now have a Mapbox GL JS map working in your Squarespace website and are ready to iterate the JavaScript code to customize the map to meet your needs.

Questions about this integration approach? Found a better way to do something? Share your experience in the comments!

Introducing Mapbox Agent Skills

Matthew Podwysocki — Wed, 11 Feb 2026 22:09:57 +0000

I'm excited to share something we've been working on that makes building with Mapbox a lot easier, especially if you're using AI coding assistants like Claude Code, Cursor, or GitHub Copilot.

We've built a collection of Agent Skills that teach AI assistants how to build better Mapbox applications. Think of it as giving your AI assistant a crash course in Mapbox development best practices.

TL;DR

Agent Skills teach AI assistants Mapbox development best practices. We've built 15 skills and counting covering web/iOS/Android integration, performance optimization, search implementation, geospatial operations, map design, migrations, security, and common patterns. Install them and your AI will know things like "cluster 1000+ markers" and "use Search Box API for autocomplete."

Install all skills:

npx add-skill mapbox/mapbox-agent-skills

Install specific skills:

npx skills add mapbox/mapbox-agent-skills --skill mapbox-web-performance-patterns

List available skills:

npx skills add mapbox/mapbox-agent-skills --list

What Are Skills?

If you've been using AI coding assistants, you've probably noticed they're pretty good at writing code, but sometimes they miss the nuances. They might suggest patterns that work but aren't optimal, or miss important details about how things should be done.

Agent Skills are a way to fix this. They're folders with instructions and guidance that AI assistants can load and use when helping you build. Unlike tools (which let AI do things) or prompts (which give specific instructions), skills provide domain expertise. The know-how.

When an AI assistant has access to Mapbox skills, it knows things like "if you're adding 1000+ markers, you should use clustering" or "use the Search Box API for autocomplete, not the Geocoding API." It's the difference between an AI that knows how to code and one that knows how to code Mapbox apps specifically.

See It In Action

This production-ready store locator was built in minutes using Claude Code with Mapbox Agent Skills. The AI assistant handled marker patterns, distance calculations, search functionality, and responsive design automatically—following Mapbox best practices from the start.

Why Skills Are Important

Here's the thing: Mapbox has a lot of surface area. We have SDKs for web, iOS, and Android. We have multiple search APIs with different use cases. We have performance patterns that matter at scale. We have migration paths from other platforms.

When you're building with an AI assistant, you want it to know all this stuff. You don't want to spend time correcting it when it suggests using 1000 individual markers instead of clustering. You don't want it to miss that you should debounce search requests. You want it to just know.

That's what these skills do. They encode the knowledge we've built up from working with thousands of developers building Mapbox applications. The patterns that work. The mistakes to avoid. The right tool for the job.

What's Inside the Box

We've organized the skills into a few main areas. Here's what's available:

Platform Integration

Web, iOS, and Android patterns - These skills cover the fundamentals of integrating Mapbox into your app, whether you're building for the web with React, Vue, Svelte, or Angular, or going native with Swift/SwiftUI on iOS or Kotlin/Jetpack Compose on Android. They know about framework-specific patterns, lifecycle management, and platform best practices.

Performance

Web performance patterns - This one's huge. It covers everything from initialization strategies to handling thousands of markers, optimizing data loading, and managing memory. If you're building something that needs to perform at scale, this skill will save you a lot of debugging time.

Search

Search integration and patterns - We have two skills here. One walks through the complete workflow of adding search to your app (asking the right discovery questions, picking the right product, implementing it correctly). The other helps you choose between our different search tools and configure them properly. Between these two, your AI assistant will know exactly how to implement search for your use case.

Geospatial Operations

Geometric calculations and routing - This skill helps decide when to use offline geometric calculations (like measuring straight-line distance) versus when to use our routing APIs (like getting actual drive times). It's the "as the crow flies vs as the crow drives" decision framework, plus a ton of practical examples.

Design and Cartography

Map design, styles, and quality - Three skills covering cartographic principles (color theory, visual hierarchy, typography), common style patterns and layer configurations, and style validation and optimization. If you're doing custom map design, these will help you make maps that look professional and work well.

Migration

Google Maps and MapLibre migration - If you're moving from Google Maps Platform or MapLibre, these skills provide comprehensive migration guides with API equivalents and pattern translations. They know the gotchas and the breaking changes.

Security

Token security - Best practices for handling access tokens securely across all platforms. This is one of those things that's easy to get wrong, so having your AI assistant know the right patterns from the start is valuable.

Common Patterns

Store locators - A focused skill on building location finders and store locators, with patterns for markers, filtering, distance calculations, and all the UX details that make these features work well.

Getting Started

Installing skills is straightforward. If you're using Claude Code, Cursor, or another AI assistant that supports Agent Skills, you can add them all at once:

npx skills add mapbox/mapbox-agent-skills

Or install specific skills if you only need certain ones:

npx skills add mapbox/mapbox-agent-skills --skill mapbox-web-performance-patterns

You can list what's available:

npx skills add mapbox/mapbox-agent-skills --list

Once installed, your AI assistant will automatically use these skills when you're working on Mapbox projects. You don't need to do anything special. Just start building and you'll notice better suggestions, fewer mistakes, and more production-ready code.

Pro tip: These skills work great with our Mapbox MCP servers. We have the Mapbox MCP Server for core Mapbox operations and the Mapbox MCP DevKit Server for development workflows. Skills provide the expertise (how to design good maps, which patterns to use), while MCP tools provide the actions (create styles, generate tokens, preview maps). Together they make a pretty powerful development workflow.

Build Stuff and Let Us Know

We built these skills based on what we've learned from years of working with developers building Mapbox applications. But they'll get better as more people use them and give us feedback.

If you build something cool with these skills, or if you find gaps where your AI assistant could use more guidance, let us know. Open an issue on GitHub or contribute a new skill if you've discovered patterns we should capture.

We're excited to see what you build.

Unlocking Mapbox GL JS's Hidden Field of View Control

Andrew Sepic — Tue, 10 Feb 2026 14:49:30 +0000

Ever wished you could make your Mapbox map look more like a telephoto lens or a dramatic wide-angle shot? Turns out, there's an undocumented way to control the camera's field of view (FOV) in Mapbox GL JS—but with a big caveat: this is not a public API.

⚠️ Developer Warning: What I'm about to show you involves accessing private internal properties. Use this only for experiments, prototypes, and creative projects. Don't rely on this in production—it could break in any future Mapbox version without notice.

The Problem: Fixed Field of View

By default, Mapbox GL JS uses a fixed vertical field of view of approximately 36.87 degrees (0.643 radians). This gives maps a consistent, neutral perspective. But what if you want to:

Create a telephoto effect (narrow FOV) for architectural visualization
Achieve a dramatic wide-angle view (large FOV) for immersive experiences
Dynamically adjust the visual perspective based on user interaction

The official Mapbox API doesn't expose FOV control—but the internal Transform class does.

What is the Transform Class?

Digging through the Mapbox GL JS source code, I discovered the Transform class—the mathematical heart of Mapbox's rendering system. This 2,800+ line beast handles:

Camera positioning and orientation
Projection matrix calculations
Coordinate system transformations (lat/lng ↔ screen pixels ↔ mercator)
Zoom level calculations
Field of view management

The Transform instance lives at map.transform and contains a private _fov property that controls the vertical field of view.

The (Unofficial) Solution

Here's how you can control field of view with a custom function called setFOV.

function setFOV(map, fov) {
  // Directly access the internal Transform instance
  map.transform._fov = fov;

  // Force recalculation of projection matrices
  map.transform._calcMatrices();

  // Trigger a map repaint
  map.triggerRepaint();
}

// Initialize your map
const map = new mapboxgl.Map({
  container: 'map-container',
  center: [-71.06288, 42.36834],
  zoom: 16.85,
  pitch: 75.67,
  bearing: 141.60
});

map.on('load', () => {
  // Apply a custom FOV (in radians)
  setFOV(map, 0.8); // Wide angle
  // setFOV(map, 0.4); // Telephoto
});

FOV Values Explained

Radians	FOV effect
0.1 - 0.5 radians (~5-28°): Telephoto effect, compressed perspective
0.643 radians (~36.87°): Default Mapbox FOV
0.8 - 1.5 radians (~45-86°): Wide angle, dramatic perspective

How It Works Under the Hood

When you modify _fov, three things need to happen:

Update the property: map.transform._fov = newValue
Recalculate matrices: map.transform._calcMatrices() recomputes all the projection math including:
- projMatrix - world to clip coordinates
- pixelMatrix - world to screen pixels
- cameraToCenterDistance - camera distance based on FOV
Trigger repaint: map.triggerRepaint() forces a redraw with new matrices

The _calcMatrices() method is where the magic happens. From the source:

this.cameraToCenterDistance = 0.5 / Math.tan(this._fov * 0.5) * 
  this.height * this._pixelsPerMercatorPixel;

This calculates how far the camera should be from the map center based on the FOV, ensuring the perspective projection renders correctly.

Interactive Field of View Controller

Want to let users adjust FOV dynamically? Here's a complete example with a slider you can check on on Codepen.

Why Isn't This a Public API?

You might wonder why Mapbox doesn't officially expose FOV control. A few reasons:

Complexity: Changing FOV affects tile loading, symbol placement, and many other rendering systems
Performance: Non-standard FOV values can impact rendering performance
Consistency: A fixed FOV ensures consistent user experience across applications
Maintenance: Supporting arbitrary FOV would increase API surface area and testing burden

The Risks

Before you rush to implement this, understand the risks:

⚠️ Breaking changes: Internal APIs can change without warning in minor/patch releases
⚠️ Unsupported behavior: You may encounter rendering artifacts or unexpected behavior
⚠️ No guarantees: Mapbox won't provide support for issues arising from this technique
⚠️ Version locked: You'll need to test across Mapbox versions if you update

Alternative: The FreeCamera API

For production use cases involving advanced camera control, check out Mapbox's official FreeCamera API. While it doesn't expose FOV directly, it provides:

Full camera position control
Orientation adjustments
Supported and stable API
Works with all Mapbox features

Conclusion

Exploring internal APIs like Transform is a fantastic way to understand how sophisticated mapping libraries work under the hood. The FOV control technique shown here opens creative possibilities for enthusiasts and experimental projects.

Just remember: with great power comes great responsibility. Use internal APIs wisely, always have a fallback, and consider this a learning exercise rather than a production strategy.

Tested with Mapbox GL JS v3.18.1. Your mileage may vary with other versions.

Additional Resources

Mapbox Demo: Bike route visualization color gradient and data scrubbing UX

Chris Whong — Mon, 09 Feb 2026 18:45:07 +0000

A developer on Reddit recently asked for help building a ride playback feature with speed visualization on a Mapbox GL JS map. They had detailed GPS and speed data from a bike ride and wanted to show speed variations along the route.

The Challenge

The original question centered on two main requirements:

Visualize speed variations along the route with color-coded gradients (slow = green, medium = yellow, fast = red)
Interactive scrubbing that shows detailed speed and time data when the user hovers over any point on the route

The Solution

Here's the working implementation on codepen. The line visualizes the variations in speed along the bike trip. Move your mouse over the line to "scrub" and see data for a specific spot on the line.

Key Implementation Details

Speed Gradient
Instead of creating separate line segments for each speed zone, we use a single GeoJSON LineString with lineMetrics: true and build a dynamic gradient using the line-gradient paint property:

'line-gradient': [
  'interpolate',
  ['linear'],
  ['line-progress'],
  ...gradientStops  // Dynamically generated from speed data
]

Each speed data point gets mapped to a position along the line (0 to 1) and assigned a color based on its speed value. Check out the official line-gradient example for more details on this technique.

A Note on Accuracy
This demo simplifies the gradient calculation by evenly distributing speed data points along the line based on timestamps. In a production app, you'd want to map each speed measurement to its actual GPS coordinate along the route for precise gradient placement. This ensures the gradient accurately reflects where speed changes occurred geographically, not just temporally.

Interactive Scrubbing
The scrubber uses geometry calculations to find the nearest point on the route as you move your mouse, then interpolates between speed data points to show accurate values at that location. A pink circle marker follows your cursor along the route, displaying the time and speed in a floating tooltip.

Performance Benefits

This approach renders a single line layer with a gradient instead of dozens of individual geometries, resulting in:

Faster initial render
Smooth interactions
Lower memory usage
Simpler state management

Cross-Platform Compatibility

While this example uses Mapbox GL JS for the web, the same line-gradient technique works on iOS and Android using the native Maps SDKs. The gradient expression syntax is consistent across all platforms.

Check out the full code in the CodePen above to see how the speed interpolation and distance calculations work. Happy mapping!

Wix X Mapbox

Chris Whong — Wed, 04 Feb 2026 17:43:31 +0000

How to Add an Interactive Mapbox Map to Your Wix Website

This guide shows developers how to integrate Mapbox GL JS into a Wix website using the Wix editor's embed code feature. If you're already familiar with Mapbox GL JS development and want to add custom interactive maps to your Wix site, this post will show you exactly where to place your code to get it working.

✅ What this guide covers: The technical steps to embed Mapbox GL JS code in a Wix website
❌ What this guide doesn't cover: Details of interactive map development with Mapbox GL JS (the examples are a great place to start for inspiration and working code snippets)

We'll show a simple example of displaying a business location with a marker, popup, and rotating camera to demonstrate the integration. Once you understand where the code goes and how it's structured in Wix, you can implement any Mapbox GL JS functionality you need by changing the JavaScript code.

Note: This technique of adding custom HTML, CSS and JavaScript via the Wix editor is suitable for simpler Mapbox GL JS implementations but does not include version control or other benefits of a separate development workflow. If your map becomes more complex, you may want to deploy it as a standalone web app, then embed it in your Wix site using its URL.

Prerequisites

To follow this guide, you'll need:

A Wix website
Working knowledge of Mapbox GL JS - you should be comfortable writing HTML, CSS, and JavaScript to create maps
A Mapbox account and access token - if you don't have one yet, sign up here

Getting Your Mapbox Access Token

Before we start, you'll need a Mapbox access token:

Go to mapbox.com and sign up for a free account (if you don't have one)
Once logged in, navigate to your console
Find the "Tokens" link in the left sidebar to go to the tokens page
Copy your default public token (it starts with pk.)

Keep this token handy—you'll need it in a moment.

How Wix Embeds Work

Before we dive in, it's important to understand what's happening under the hood. When you add an embed element in the Wix editor, it becomes an <iframe> in your published site. This iframe contains whatever HTML, CSS, and JavaScript you add to it—completely isolated from the rest of your Wix page.

This isolation is actually a benefit: you have complete control over the content inside the iframe without worrying about conflicts with Wix's own code. You can implement any Mapbox GL JS functionality you want, exactly as you would in a standalone HTML page.

Step 1: Adding the Embed Element

Let's add the embed element that will contain your map code:

Open your Wix Editor and navigate to the page where you want to add the map
Click the "+ Add" button (in the top left) to add an element
Scroll through the different elements and select "Embed"
Choose "Embed Code" on the next panel
Drag and resize the embed element to your desired size on the page
Double click the embed element to open its Settings panel

Step 2: Add Mapbox GL JS Code

Now you'll add Mapbox GL JS code to get a map working in the embed. The embed accepts any HTML, so you can include CSS and JavaScript by using <style> and <script> tags.

Here's a working example that shows a business location with a marker and rotating camera. Copy this code and replace YOUR_MAPBOX_ACCESS_TOKEN with your actual access token:

<!-- import Mapbox GL JS and its CSS file -->
<script src='https://api.mapbox.com/mapbox-gl-js/v3.18.1/mapbox-gl.js'></script>
<link href='https://api.mapbox.com/mapbox-gl-js/v3.18.1/mapbox-gl.css' rel='stylesheet' />

<!-- override default styles for the map and popup -->
<style>
  body {
    margin: 0
  }

  .mapboxgl-popup-content {
    background-color: #e6f2d2;
    color: #2f5f48;
  }

  .mapboxgl-popup-tip {
    border-top-color: #e6f2d2 !important;
  }
</style>

<!-- add a container element for the map -->
<div id="map-container" style="position: absolute; height: 100%; width: 100%"></div>

<script>
  // your Mapbox access token
  mapboxgl.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN';

  // initialize the map
  const map = new mapboxgl.Map({
    container: 'map-container', // container ID
    style: 'mapbox://styles/mapbox/standard', // style URL
    center: [-73.99986, 40.75300], // starting position [lng, lat]
    zoom: 15.36, // starting zoom
    bearing: 28.00, // bearing in degrees
    pitch: 56.50, // pitch in degrees
    config: {
      basemap: {
        theme: 'monochrome', // use the monochrome basemap theme
        showPointOfInterestLabels: false // hide point of interest labels
      }
    }
  });

  // disable scroll zoom so the map won't zoom as the user scrolls down the page
  map.scrollZoom.disable();

  // create a popup with address details and a link to get directions on Google Maps
  const popup = new mapboxgl.Popup({
    closeOnClick: false,
    closeButton: false,
    offset: 40,
  }).setHTML(
    `<div>
      450 W 33rd St<br/>
      New York, NY 10001</div>
      <a href="https://maps.app.goo.gl/6WzErvMBMi2Hn64Z7" target="_blank" rel="noopener noreferrer"><span class="text-xs">Get Directions</span></a>
    `
  );

  // create a map marker with a custom color, connect the popup, add it to the map, and open the popup
  new mapboxgl.Marker({
    color: '#2f5f48'
  })
    .setLngLat([-73.99986, 40.75300])
    .setPopup(popup)
    .addTo(map)
    .togglePopup();

  // this function rotates the camera continuously
  // see https://docs.mapbox.com/mapbox-gl-js/example/animate-camera-around-point/
  function rotateCamera(timestamp) {
    map.rotateTo((timestamp / 200) % 360, { duration: 0 });
    requestAnimationFrame(rotateCamera);
  }

  map.on('load', () => {
    // start the camera animation.
    rotateCamera(0);
  })
</script>

Delete the existing code in the textarea labeled Enter HTML embed code and paste the Mapbox GL JS snippet from above:

Important: Replace the placeholder text YOUR_MAPBOX_ACCESS_TOKEN with the actual token you copied from your Mapbox account.

Click "Apply" to save your code, then preview your site. You should see an interactive map with a monochrome basemap, a marker centered over New York City, and a slowly rotating camera.

Understanding the Code Structure

Here's how the code for this map breaks down:

1. Library Imports

<script src='https://api.mapbox.com/mapbox-gl-js/v3.18.1/mapbox-gl.js'></script>
<link href='https://api.mapbox.com/mapbox-gl-js/v3.18.1/mapbox-gl.css' rel='stylesheet' />

These load Mapbox GL JS and its required stylesheet from the Mapbox CDN.

2. Custom Styles

<style>
  body {
    margin: 0
  }

  .mapboxgl-popup-content {
    background-color: #e6f2d2;
    color: #2f5f48;
  }
</style>

The body { margin: 0 } removes default margins so the map fills the entire iframe. The popup styles customize the appearance to match the page theme.

3. Map Container

<div id="map-container" style="position: absolute; height: 100%; width: 100%"></div>

This div is where the map renders. The inline styles ensure it fills the available space.

4. Your Map Logic

<script>
  // All your Mapbox GL JS code goes here
</script>

This is where you implement your map functionality. In this example, we're:

Setting the access token
Initializing the map with specific style and camera settings
Disabling scroll zoom (important for Wix pages!)
Creating a popup and marker
Adding a camera rotation animation

You can replace or extend this code with any Mapbox GL JS functionality you need.

If you want to adapt this example of a single marker and popup, you should:

Change the map's center point, zoom, pitch and bearing to your desired initial camera view.
Change the Marker's coordinates
Change the Popup's content by editing the HTML code in Popup.setHTML()

Or, you can leave the imports and the map container in place and start over with the map JavaScript code and build whatever you need. See additional developer resources below.

Resources for Mapbox GL JS Development

Here are essential resources for building your map functionality:

Mapbox Documentation

Mapbox GL JS Examples - Dozens of live, interactive code examples
Mapbox GL JS Guides
Mapbox GL JS API Reference - Complete documentation of all map methods and options

Key Examples

Display a map - Basic map initialization
Add markers to a map - Working with markers
Display a popup - Popup functionality
Add GeoJSON data - Display custom data

Community

r/mapbox on Reddit - Get help and share ideas
Mapbox Developer Discord - Post in the #web channel to ask questions and share what you build.

Troubleshooting

Map not displaying?

Verify you've replaced YOUR_MAPBOX_ACCESS_TOKEN with your actual token
Check that your access token has the correct permissions
Ensure the embed element has sufficient height and width in the Wix editor and that the map container div also has sufficient height and width
Open your browser's developer console to check for JavaScript errors

By following the steps in this guide, you should now have a Mapbox GL JS map working in your Wix website and are ready to iterate the JavaScript code to customize the map to meet your needs.

Questions about this integration approach? Found a better way to do something? Share your experience in the comments!

Server-rendered Maps for Web and Mobile

Chris Whong — Thu, 29 Jan 2026 16:42:21 +0000

A Developer's Guide to the Mapbox Static Images API

Interactive maps are a powerful user experience element — they let users pan, zoom, and explore wide geographic areas or interact with dense datasets. But there's a catch: not every use case needs the full weight of a client-rendered map.

Rendering vector maps in the client requires loading all the map data into the browser or device, which means significant network traffic, device processing overhead, and performance costs.

Sometimes you just need a picture of a map.

If users are quickly scrolling past location information, or if you're displaying a long list where every item needs a map thumbnail, it doesn't make sense to bring in a vector map library or SDK and load lots of client-rendered data just to show a marker or two.

That's where the Mapbox Static Images API comes in.

What Is the Static Images API?

The Mapbox Static Images API is an HTTP endpoint that returns map images. All you need is a center point (latitude and longitude) and a zoom level (0 is zoomed out to world level, 18 or so gets you to street level). This will serve up a beautiful map image from anywhere in the world — no JavaScript libraries, no SDK packages, no client-side rendering, just a clean image URL.

To help you get an understanding of the URL structure for a call to the Static Images API, here are some map images of landmarks and their associated Static Images API URLs. You can try the URLs yourself, just replace YOUR_MAPBOX_ACCESS_TOKEN with an access token from your Mapbox account:

The Eiffel Tower

The site of the Eiffel Tower in Paris (2.295,48.8584), France, using the Mapbox Streets style at zoom 12.77:

https://api.mapbox.com/styles/v1/mapbox/streets-v12/static/2.295,48.8584,12.77,0/400x300@2x?access_token=YOUR_MAPBOX_ACCESS_TOKEN

The site of the Golden Gate Bridge (-122.4717,37.8177) in San Francisco, California, USA, using the Mapbox Dark style at zoom 10.56:

https://api.mapbox.com/styles/v1/mapbox/dark-v11/static/-122.4717,37.8177,10.56,0/400x300@2x?access_token=YOUR_MAPBOX_ACCESS_TOKEN

The site of the Sydney Opera House in Sydney, Australia, using the Mapbox Satellite Streets style at zoom 13.63.

https://api.mapbox.com/styles/v1/mapbox/satellite-streets-v12/static/151.215,-33.858,13.63,0/400x300@2x?access_token=YOUR_MAPBOX_ACCESS_TOKEN

As you can see, the syntax for the URL structure is straightforward. Each of these images is 800x600 pixels (the request shows 400x300@2x for retina images), and include the longitude, latitude, zoom level, and style id.

You can copy the URLs, add your own Mapbox access token and change out the longitude and latitude coordinates to get a map image for an area of interest to you. If you need to quickly get coordinates for a place, try our handy Location Helper tool.

Adding Your Data with Overlays

It's rare that you would ever want just a basemap. The real power of the Static Images API comes from its overlays feature. Overlays let you add your own data — markers, lines, and polygons — directly onto the map.

The overlay system is completely flexible: you can use simple longitude and latitude coordinates, or bring in encoded linestrings or GeoJSON for more complex geometries. This makes it trivial to combine Mapbox's professional basemaps with your application's location data.

Overlays use a DSL and end up as sections of the URL. For example, a small (s) red (#b44646) marker at coordinates -0.1717,51.5068 is encoded as pin-s+b44646(-0.1717,51.5068). Don't worry about the learning curve for encoding overlays, we made a Developer Playground to help you configure them.

Three Real-World Use Cases

Below are three practical examples that showcase how to combine Mapbox basemaps with overlays from the Static Images API.

1. Directions Route with Origin and Destination Markers

A common use cases in location apps is showing directions and travel times from point A to point B. Whether you're building a ride-sharing app, a delivery service, or a travel planner, you need to visualize routes clearly.

With the Static Images API, you can overlay a route polyline along with markers for the origin and destination. This gives users an instant visual understanding of the journey without requiring them to interact with a full map.

Example:

https://api.mapbox.com/styles/v1/mapbox/streets-v12/static/path-7+6d8afd-0.8(ycmlFdweuM%3FglAsF%40B_CirAi%7CGkHyfG%7ByCspD%7B%7DGyfCyrAgsCenHcoCgbDylBiaHgkJ_lDabB_fGszFuxDqeJ%7BfCw%5Bq%7C%40%7BcAwcEczA_Aa%7D%40aR%5C%5C%3F),pin-l+51bd5e(-77.0393863890253,38.90253),pin-l+f54747(-76.612299,39.289643)/-76.7636,39.1125,8.45,0/600x400@2x?attribution=true&logo=true&access_token=YOUR_MAPBOX_ACCESS_TOKEN

Use an encoded polyline overlay for the route geometry (The Mapbox Directions API can return this format, that's where the geometry in this example came from)
Add marker overlays for origin and destination with different colors

2. Property Listing with 15-Minute Accessibility Isochrone

Real estate and rental platforms need to communicate location value effectively. Showing a home's location is helpful, but showing what's accessible from that location is even better.

An isochrone is a polygon that represents all the areas reachable from a point within a certain time frame. (We have an API for that too!) For a property listing, overlaying a 15-minute isochrone shows potential buyers or renters exactly how far they can get by walking, biking, or driving — highlighting the home's convenience and accessibility.

This approach could also show the delivery area for a business or any other relevant polygon like a school district.

Example:

https://api.mapbox.com/styles/v1/mapbox/dark-v11/static/geojson({"type":"FeatureCollection","features":[{"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[-76.508577,42.514225],[-76.509957,42.513128],[-76.509123,42.508674],[-76.51144,42.504265],[-76.513577,42.502387],[-76.510127,42.500128],[-76.511751,42.498128],[-76.512271,42.488128],[-76.511283,42.487128],[-76.511306,42.483128],[-76.510324,42.480128],[-76.504437,42.472268],[-76.504167,42.470538],[-76.50139,42.467128],[-76.501189,42.464516],[-76.505282,42.461833],[-76.507577,42.46181],[-76.508577,42.459468],[-76.503577,42.45937],[-76.505579,42.457126],[-76.505802,42.454903],[-76.507577,42.453848],[-76.515345,42.45436],[-76.51784,42.452865],[-76.513262,42.450444],[-76.515998,42.448128],[-76.519319,42.453386],[-76.521577,42.455901],[-76.525577,42.452965],[-76.523118,42.451587],[-76.522831,42.449128],[-76.520577,42.449318],[-76.517225,42.445128],[-76.521577,42.443245],[-76.521074,42.438128],[-76.524371,42.436128],[-76.521759,42.434128],[-76.514694,42.434245],[-76.511158,42.433548],[-76.510105,42.430128],[-76.505996,42.428128],[-76.502577,42.428537],[-76.500033,42.432584],[-76.498334,42.429128],[-76.500068,42.428619],[-76.500394,42.425945],[-76.503844,42.423395],[-76.503226,42.418128],[-76.505035,42.417128],[-76.505053,42.412128],[-76.50193,42.410481],[-76.501943,42.417128],[-76.499577,42.418592],[-76.497577,42.417807],[-76.495368,42.419919],[-76.497856,42.421407],[-76.494862,42.424128],[-76.489532,42.425173],[-76.485245,42.42246],[-76.483325,42.418128],[-76.480532,42.417083],[-76.482577,42.421654],[-76.484577,42.423622],[-76.482577,42.426795],[-76.485577,42.428684],[-76.486205,42.4315],[-76.476577,42.43128],[-76.475212,42.428493],[-76.470462,42.427243],[-76.468432,42.425273],[-76.469064,42.422641],[-76.464577,42.42142],[-76.462577,42.422323],[-76.460151,42.419554],[-76.456427,42.418278],[-76.455088,42.416617],[-76.451321,42.415128],[-76.455346,42.410897],[-76.459955,42.408506],[-76.458864,42.407414],[-76.455822,42.409373],[-76.451921,42.410785],[-76.449577,42.412473],[-76.443373,42.411332],[-76.437577,42.4076],[-76.436152,42.409554],[-76.439795,42.41091],[-76.447756,42.414949],[-76.453774,42.420325],[-76.448577,42.420775],[-76.448577,42.426175],[-76.453577,42.426839],[-76.456253,42.429452],[-76.461745,42.43196],[-76.461577,42.434379],[-76.457577,42.434404],[-76.4523,42.432406],[-76.446577,42.432548],[-76.450577,42.434781],[-76.455577,42.434836],[-76.458759,42.435946],[-76.458898,42.438128],[-76.461577,42.438809],[-76.466099,42.442606],[-76.464577,42.444003],[-76.458577,42.443598],[-76.454577,42.44578],[-76.452594,42.448111],[-76.450577,42.448707],[-76.446577,42.45155],[-76.440577,42.452472],[-76.438577,42.454801],[-76.442577,42.454598],[-76.446577,42.452706],[-76.449577,42.452709],[-76.450577,42.45048],[-76.45896,42.449511],[-76.466132,42.452128],[-76.46527,42.455128],[-76.473577,42.457868],[-76.475924,42.463128],[-76.476577,42.466596],[-76.471577,42.466572],[-76.467379,42.46493],[-76.464225,42.46748],[-76.465716,42.469267],[-76.468577,42.469357],[-76.469577,42.471132],[-76.472577,42.46976],[-76.475128,42.470128],[-76.475922,42.472473],[-76.474547,42.475128],[-76.477756,42.477128],[-76.477876,42.480128],[-76.474577,42.481343],[-76.468331,42.481374],[-76.469151,42.478702],[-76.467634,42.475071],[-76.4651,42.474128],[-76.465577,42.480314],[-76.461577,42.482593],[-76.455577,42.482704],[-76.454577,42.481743],[-76.450052,42.482128],[-76.454577,42.484442],[-76.462577,42.483733],[-76.463577,42.482681],[-76.468577,42.483644],[-76.476577,42.483066],[-76.481577,42.481804],[-76.486278,42.482829],[-76.491577,42.480834],[-76.495577,42.481012],[-76.493917,42.483128],[-76.500868,42.483837],[-76.502166,42.487128],[-76.504577,42.48936],[-76.506515,42.489128],[-76.505577,42.484372],[-76.503577,42.48469],[-76.502328,42.481879],[-76.504875,42.481426],[-76.504915,42.478128],[-76.508832,42.481128],[-76.50985,42.484128],[-76.509782,42.488128],[-76.510887,42.489128],[-76.510926,42.493128],[-76.509491,42.493042],[-76.508864,42.498841],[-76.506173,42.500128],[-76.509066,42.502128],[-76.509133,42.505128],[-76.507936,42.508128],[-76.508577,42.514225]]]},"properties":{"fill-opacity":0.33,"opacity":0.33,"fill":"%237dcff5","fillOpacity":0.33,"color":"%23bf4040","contour":10,"metric":"time"}}]}),pin-l-home+744ce1(-76.48957711003335,42.44212800096554)/-76.4821,42.4615,10.98,0/600x400@2x?attribution=true&logo=true&before_layer=admin-0-boundary-bg&access_token=YOUR_MAPBOX_ACCESS_TOKEN

Generate the isochrone polygon using the Mapbox Isochrone API
Add it as a GeoJSON polygon overlay with a semi-transparent fill
Place a marker overlay at the property location to clearly identify the starting point
Use the before_layer parameter to position overlay underneath the map labels
Use a dark basemap style to make the colors pop

3. School Proximity Map with Labeled Markers

Parents searching for a new home often prioritize school proximity. For a real estate or neighborhood information app, showing a home's location alongside nearby schools provides instant context about the area.
Using the Static Images API, you can overlay multiple custom markers — one for the home and one for each nearby school — with labeled markers (A, B, C) to make it easy to cross-reference with a list displayed alongside the map.

Example:

https://api.mapbox.com/styles/v1/mapbox/light-v11/static/pin-s-c+4682b4(-122.3332,47.6113),pin-s-b+4682b4(-122.3401,47.6161),pin-s-a+4682b4(-122.3521,47.6138),pin-l-star+66ff2e(-122.3428,47.6139)/-122.3425,47.6141,13.8,0/600x400@2x?attribution=true&logo=true&access_token=YOUR_MAPBOX_ACCES_TOKEN

Use a distinct marker style for the home location
Add labeled markers for each school with letters A, B, C (Glyphs are also available as marker labels using the label parameter)

Use the Developer Playground to get started

The Static Images API Playground makes it easy to get started without needing to learn the intricacies of the overlay DSL or manually dial your map in to your desired area and zoom level. The Playground provides a graphical user interface where you can easily position the map, add overlays visually, and tinker with all the API parameters in real time.

We recently improved the overlay UI to make it even simpler to add markers, lines, and polygons — just click, drag, and configure. Once your map image and overlays look exactly the way you want, simply copy the generated URL.

You can use that URL directly in your frontend code as an <img> source, or use it as a template to generate similar URLs dynamically based on your application's data — just swap in different coordinates, zoom levels, or overlay parameters as needed.

When to Choose Static Maps

Static maps aren't a replacement for interactive maps — they're a complement.

Use static maps when:

You're displaying many maps at once (list views, galleries, grids)
The map is supplementary context, not the primary interaction
You need fast page loads and minimal JavaScript overhead
You want a consistent image that won't change based on user interaction

By combining beautiful Mapbox basemap styles with your own overlay data, the Static Images API gives you a lightweight, performant way to bring maps into your web and mobile applications — without the complexity or cost of full interactive rendering.

Ready to get started?

Try the Static Images API Playground and see how easy it is to create custom static maps for your next project.
See the API reference documentation for detailed breakdowns of each parameter.

Gradio X Mapbox

Chris Whong — Thu, 29 Jan 2026 16:25:53 +0000

A developer on r/mapbox asked for if anyone had successfully integrated a Mapbox GL JS map with Gradio, a python library for creating web interfaces for machine learning models.

After a quick peek at Gradio's docs, I quickly found the sections on adding custom CSS and JS. With a bit of help from AI, I learned the best way to get data out of python world and into JavaScript world in a Gradio app (there are several ways, but the one I used involves stashing it in a hidden output textarea)

I built a demo to show a simple implementation of Gradio X Mapbox:

Start with a pandas dataframe of U.S. cities with their longitude/latitude coordinates.
Convert the city points to GeoJSON in python, dropping the GeoJSON in a hidden output.
On map load, pick up the GeoJSON and add circles to the map representing the cities using a geojson source and a fill layer.
Add a button to trigger some processing in python. In this case, it's the calculation of a convex hull around the point data.
Convert the convex hull to GeoJSON and stash it in another hidden output.
Render the convex hull polygon on the on the map using a geojson source and a fill layer.

There are a few considerations for loading Mapbox GL JS:

Load Mapbox GL JS and its css via CDN links using the head argument of demo.launch
Create a map container div using gr.HTML()
Before instantiating the map, poll for the existence of the map container (it may not exist when the JavaScript code first runs). In the example below, there is a timeout and subsequent checks for setting up the map.

The full code snippet is below if you want to give it a try. You'll need a Mapbox access token to get it working, so sign up here if you don't already have a Mapbox account.

import gradio as gr
import pandas as pd
import numpy as np
import json
from shapely.geometry import MultiPoint, mapping, Point


# cities DataFrame
df = pd.DataFrame({
    "city": [
        "New York",
        "Los Angeles",
        "Chicago",
        "Houston",
        "Phoenix",
        "Philadelphia",
        "San Antonio",
        "San Diego",
        "Dallas",
        "San Jose",
    ],
    "lat": [
        40.7128,
        34.0522,
        41.8781,
        29.7604,
        33.4484,
        39.9526,
        29.4241,
        32.7157,
        32.7767,
        37.3382,
    ],
    "lon": [
        -74.0060,
        -118.2437,
        -87.6298,
        -95.3698,
        -112.0740,
        -75.1652,
        -98.4936,
        -117.1611,
        -96.7970,
        -121.8863,
    ],
})


# compute convex hull and return GeoJSON
def compute_convex_hull(data):
    points = [Point(row["lon"], row["lat"]) for _, row in data.iterrows()]
    multipoint = MultiPoint(points)
    hull = multipoint.convex_hull
    hull_geojson = mapping(hull)
    features = [
        {
            "type": "Feature",
            "geometry": mapping(pt),
            "properties": {"city": row["city"]},
        }
        for pt, (_, row) in zip(points, data.iterrows())
    ]
    geojson = {
        "type": "FeatureCollection",
        "features": [
            {
                "type": "Feature",
                "geometry": hull_geojson,
                "properties": {"type": "convex_hull"},
            }
        ]
        + features,
    }
    return json.dumps(geojson)


# convert points to GeoJSON for initial display
def get_points_geojson(data):
    """Convert dataframe to GeoJSON for initial point display"""
    features = [
        {
            "type": "Feature",
            "geometry": {"type": "Point", "coordinates": [row["lon"], row["lat"]]},
            "properties": {"city": row["city"]},
        }
        for _, row in data.iterrows()
    ]
    return json.dumps({"type": "FeatureCollection", "features": features})


# Gradio interface, two columns: left data table and button, right map display
with gr.Blocks() as demo:
    with gr.Row():
        with gr.Column():
            gr.Markdown(
                """
                # US Cities Convex Hull Demo
                This demo computes the convex hull of a set of US cities and outputs the result as GeoJSON for display on a [Mapbox GL JS](https://docs.mapbox.com/mapbox-gl-js/) map.

                GeoJSON strings are assembled in python and stored in hidden Gradio outputs for easy access in the Javascript map code.
                """
            )
            gr.Dataframe(df, label="City Locations")
            btn = gr.Button("Compute Convex Hull GeoJSON")


        # this html includes the map container, Mapbox GL JS will add a map in this div
        with gr.Column():
            gr.HTML(
                """
                <div>
                    <h3>Mapbox GL JS Visualization</h3>
                    <div id='map-container' style='width: 100%; height: 450px; background-color: lightgray;'></div>
                    <div>© Mapbox &nbsp; © OpenStreetMap</div>
                </div>
                """
            )


    # empty output boxes to hold GeoJSON data
    geojson_output = gr.JSON(visible=False)
    initial_points = gr.JSON(value=get_points_geojson(df), visible=False)


    def handle_click():
        return compute_convex_hull(df)


    # on click, compute convex hull and update map
    btn.click(
        handle_click,
        outputs=geojson_output,
    ).then(
        None,
        inputs=geojson_output,
        outputs=None,
        js="""
        (data) => {
            console.log("Received GeoJSON data:", data);
            if (window.map) {
                // Remove existing hull layer if it exists
                if (window.map.getLayer('convex-hull')) {
                    window.map.removeLayer('convex-hull');
                }
                if (window.map.getSource('hull')) {
                    window.map.removeSource('hull');
                }


                // Add hull
                window.map.addSource('hull', {
                    type: 'geojson',
                    data: data,
                });


                window.map.addLayer({
                    id: 'convex-hull',
                    type: 'fill',
                    source: 'hull',
                    paint: {
                        'fill-color': '#088',
                        'fill-opacity': 0.3,
                        'fill-emissive-strength': 1,
                    },
                });


                window.map.addLayer({
                    id: 'convex-hull-outline',
                    type: 'line',
                    source: 'hull',
                    paint: {
                        'line-color': '#FFF',
                        'line-width': 2,
                        'line-emissive-strength': 1,
                    },
                });
            }
        }
        """,
    )


    # on initial load, initialize a map, then add points as a GeoJSON source and circle layer
    # initMap() contains a retry mechanism to wait for the map container to be available,
    # as Gradio may take some time to render the HTML and the map container div may not be present immediately
    demo.load(
        None,
        inputs=initial_points,
        outputs=None,
        js="""
        (pointsData) => {
            function initMap() {
                const container = document.getElementById('map-container');
                if (!container) {
                    setTimeout(initMap, 100);
                    return;
                }


                mapboxgl.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN';


                window.map = new mapboxgl.Map({
                    container: 'map-container',
                    style: 'mapbox://styles/mapbox/standard',
                    config: {
                        basemap: {
                            theme: 'monochrome',
                            lightPreset: 'night',
                        },
                    },
                    center: [-98.92906, 40.25617],
                    zoom: 2.5,
                    projection: 'mercator',
                    attributionControl: false,
                });


                // Add points after map loads
                window.map.on('load', function () {
                    window.map.addSource('cities', {
                        type: 'geojson',
                        data: pointsData,
                    });


                    window.map.addLayer({
                        id: 'city-points',
                        type: 'circle',
                        source: 'cities',
                        paint: {
                            'circle-radius': 6,
                            'circle-color': '#B42222',
                            'circle-emissive-strength': 1,
                        },
                    });
                });
            }


            initMap();
        }
        """,
    )


# load mapbox gl js and its css in the head
head = """
<link href="https://api.mapbox.com/mapbox-gl-js/v3.18.1/mapbox-gl.css" rel="stylesheet">
<script src="https://api.mapbox.com/mapbox-gl-js/v3.18.1/mapbox-gl.js"></script>
"""


# custom css to position the Mapbox logo, as Gradio css interferes with default positioning
# note that attributionControl is set to false in the map options because Gradio CSS also interferes with the attribution control
# map attribution is required and was manually added in the HTML above
custom_css = """
.mapboxgl-ctrl-bottom-left .mapboxgl-ctrl,
.mapboxgl-ctrl-left .mapboxgl-ctrl {
    margin: 0 0 10px 10px !important;
}
"""


demo.launch(head=head, css=custom_css)

Build a ChatGPT App with Mapbox

Chris Tufts — Fri, 09 Jan 2026 19:40:05 +0000

ChatGPT Apps are a new way to build interactive experiences within the ChatGPT interface. In this tutorial, we'll explore and run a Points of Interest (POI) search app powered by Mapbox APIs that lets users find places like coffee shops, restaurants, and gas stations near any location using natural language. The focus of this tutorial is on understanding how to build a ChatGPT App using the ChatGPT Apps SDK and the Model Context Protocol (MCP). The app is loosely based on the Mapbox Build a store locator using Mapbox GL JS tutorial, but adapted for the ChatGPT UI. For the remainder of the post I'll refer to ChatGPT apps as apps for brevity.

How ChatGPT Apps Work

From a user perspective, utilizing an app is identical to the traditional chat workflow: select any tools you want to use, type a prompt into the chat interface, and you get a response.

The workflow under the hood starts in ChatGPT, utilizes your app (an MCP server), and uses the results to render a widget in the chat UI. The process is shown in the following diagram.

┌─────────────────────────────────────────────────────────────────┐
│                         ChatGPT                                 │
│        User: "Find coffee shops near Times Square"              |
│                           │                                     │
│                           ▼                                     │
│              Calls find_nearby_places tool                      │
└───────────────────────────┬─────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Your MCP Server                              │
│  • Geocode "Times Square" → coordinates (Geocoding API)         │
│  • Search for "coffee" near coordinates (Search Box API)        │
│  • Return structuredContent with place data                     │
└───────────────────────────┬─────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                         ChatGPT                                 │
│  • Receives structuredContent from tool response                │
│  • Sets window.openai.toolOutput = structuredContent            │
│  • Loads your widget HTML (from MCP resource) in an iframe      │
└───────────────────────────┬─────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│              Your Widget (iframe in ChatGPT UI)                 │
│  • Your HTML/CSS/JS from widget.html                            │
│  • Reads data from window.openai.toolOutput                     │
│  • Renders Mapbox GL JS map with markers                        │
└─────────────────────────────────────────────────────────────────┘

Key Concepts

If you are new to MCP's and ChatGPT apps, the following table shows some new key concepts to keep an eye out for as we go through the example. The table is meant for quick reference as more detail will be provided as we progress through the tutorial.

Concept	What It Is	In Our App
MCP	Model Context Protocol— the spec for connecting an LLM with external tools and resources	The App is an MCP server
Resource	An HTML template ChatGPT can render	Our map widget (`widget.html`)
Tool	External tools our MCP exposes to ChatGPT	`find_nearby_places` tool
`text/html+skybridge`	MIME type that tells ChatGPT "this is a widget"	Set on our resource
`window.openai.toolOutput`	How tool results reach your widget	Contains our POI/place data

Learn more: See the ChatGPT Apps SDK documentation for detailed guides on MCP servers, widgets, tools, and more.

Project Setup

Prerequisites

Mapbox account with access token (get one here). For additional info on tokens see the deep dive.
Node.js 18+ installed
ChatGPT Plus or Team account with developer mode enabled
(Optional): Download ngrok for local development. ChatGPT requires the MCP be hosted behind an HTTPS endpoint, ngrok is a simple way to do this.

1. Clone the repository

git clone https://github.com/mapbox/location-ai-tutorials.git
cd location-ai-tutorials/chatgpt-app-tutorial

2. Install dependencies

npm install

Package	Purpose
`@modelcontextprotocol/sdk`	MCP protocol implementation
`zod`	Schema validation (required by MCP)
`dotenv`	Load environment variables

3. Configure environment

Copy the example environment file and add your Mapbox token:

cp .env.example .env

Edit .env and add your token:

MAPBOX_ACCESS_TOKEN=pk.your_token_here

4. Project structure

chatgpt-app-tutorial/
├── server.js           # MCP server
├── public/
│   └── widget.html     # Map widget
├── package.json
├── .env.example
└── .env                # Your local config (not tracked)

Understanding the MCP Server

Let's walk through server.js to understand how the MCP server works.

Server setup

import "dotenv/config";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { createServer } from "node:http";
import { readFileSync } from "node:fs";
import { z } from "zod";

// Load widget HTML and inject Mapbox token
const widgetHtml = readFileSync("public/widget.html", "utf8")
  .replace("{{MAPBOX_ACCESS_TOKEN}}", process.env.MAPBOX_ACCESS_TOKEN || "");

function createPoiSearchServer() {
  const server = new McpServer({
    name: "poi-search",
    version: "1.0.0"
  });

  // Resources are added here

  return server;
}

Register the widget resource

Resources are HTML templates that ChatGPT can render. The key is the text/html+skybridge MIME type which tells ChatGPT it's a widget, not just HTML text.

server.registerResource(
  "places-widget",           // Name (for reference)
  "ui://widget/places.html", // URI (links tool output to this widget)
  {},
  async () => ({
    contents: [{
      uri: "ui://widget/places.html",
      mimeType: "text/html+skybridge",  // This makes it a widget!
      text: widgetHtml,
      _meta: {
        "openai/widgetPrefersBorder": true
      }
    }]
  })
);

Register the find_nearby_places tool

Tools are functions ChatGPT can call. The _meta["openai/outputTemplate"] links this tool to our widget. When ChatGPT calls the tool, the widget renders with the returned data.

server.registerTool(
  "find_nearby_places",
  {
    title: "Find Nearby Places",
    description: "Use this when the user wants to find places like coffee shops, restaurants, gas stations, grocery stores, or other businesses near a specific location. Always requires both a type of place and a location.",
    inputSchema: {
      category: z.string().describe("Type of place to search for (e.g., 'coffee', 'restaurant', 'grocery', 'pharmacy', 'gas station', 'hotel', 'bank')"),
      location: z.string().describe("Location to search near (e.g., 'Times Square NYC', 'downtown Seattle', '1600 Pennsylvania Ave')")
    },
    _meta: {
      "openai/outputTemplate": "ui://widget/places.html",  // Link to widget
      "openai/toolInvocation/invoking": "Searching for nearby places...",
      "openai/toolInvocation/invoked": "Places found"
    }
  },
  async ({ category, location }) => {
    // Implementation coming next
  }
);

Add Mapbox API helpers

The following functions call Mapbox APIs to convert text locations to coordinates and search for places.

// Convert text location to coordinates
async function geocodeLocation(locationText, accessToken) {
  const url = new URL("https://api.mapbox.com/search/geocode/v6/forward");
  url.searchParams.set("q", locationText);
  url.searchParams.set("access_token", accessToken);
  url.searchParams.set("limit", "1");

  const response = await fetch(url);
  if (!response.ok) {
    throw new Error(`Geocoding failed: ${response.status}`);
  }

  const data = await response.json();
  if (!data.features || data.features.length === 0) {
    throw new Error(`Could not find location: ${locationText}. Try a more specific address or city name.`);
  }

  const feature = data.features[0];
  const [longitude, latitude] = feature.geometry.coordinates;
  const placeName = feature.properties.full_address || feature.properties.name || locationText;
  return { longitude, latitude, placeName };
}

// Search for places by category
async function searchCategory(categoryId, longitude, latitude, accessToken) {
  const url = new URL(`https://api.mapbox.com/search/searchbox/v1/category/${encodeURIComponent(categoryId)}`);
  url.searchParams.set("access_token", accessToken);
  url.searchParams.set("proximity", `${longitude},${latitude}`);
  url.searchParams.set("limit", "10");

  const response = await fetch(url);
  if (!response.ok) {
    throw new Error(`Category search failed: ${response.status}`);
  }

  return response.json();
}

Add category mapping and response transformer

These helper functions normalize user input to Mapbox category IDs and transform the API response to our widget's expected format:

// Category mappings - maps common user terms to Mapbox category IDs
const CATEGORY_MAPPINGS = {
  "coffee": "coffee",
  "coffee shop": "coffee",
  "restaurant": "restaurant",
  "grocery": "grocery",
  "gas station": "gas_station",
  "pharmacy": "pharmacy",
  "hotel": "hotel",
  "bank": "bank",
  // ... add more as needed
};

function mapCategoryToId(userCategory) {
  const normalized = userCategory.toLowerCase().trim();
  return CATEGORY_MAPPINGS[normalized] || normalized;
}

// Transform Mapbox response to widget-compatible GeoJSON
function transformToWidgetGeoJSON(mapboxResponse, categoryName) {
  return {
    type: "FeatureCollection",
    features: (mapboxResponse.features || []).map((feature) => ({
      type: "Feature",
      geometry: feature.geometry,
      properties: {
        name: feature.properties.name || "Unknown",
        address: feature.properties.address || feature.properties.full_address || "",
        city: feature.properties.context?.place?.name || "",
        state: feature.properties.context?.region?.region_code || "",
        postalCode: feature.properties.context?.postcode?.name || "",
        phoneFormatted: feature.properties.metadata?.phone || null,
        category: categoryName,
        mapbox_id: feature.properties.mapbox_id
      }
    }))
  };
}

Implement the tool

Now wire up the tool to use these helper functions and return data in the format our widget expects:

async ({ category, location }) => {
  const accessToken = process.env.MAPBOX_ACCESS_TOKEN;

  if (!accessToken) {
    return {
      content: [{ type: "text", text: "Error: Mapbox access token not configured." }],
      isError: true
    };
  }

  try {
    // Step 1: Geocode the location
    const { longitude, latitude, placeName } = await geocodeLocation(location, accessToken);

    // Step 2: Map category to Mapbox ID
    const categoryId = mapCategoryToId(category);

    // Step 3: Search for places
    const searchResults = await searchCategory(categoryId, longitude, latitude, accessToken);

    // Step 4: Transform to widget format
    const places = transformToWidgetGeoJSON(searchResults, category);

    // Step 5: Calculate map center and zoom
    const center = [longitude, latitude];
    const zoom = places.features.length > 0 ? 13 : 12;

    return {
      structuredContent: {
        places: places,
        center: center,
        zoom: zoom,
        searchLocation: placeName,
        searchCategory: category
      },
      content: [{
        type: "text",
        text: places.features.length > 0
          ? `Found ${places.features.length} ${category} places near ${placeName}.`
          : `No ${category} places found near ${placeName}. Try a different location or category.`
      }]
    };
  } catch (error) {
    return {
      content: [{ type: "text", text: `Search failed: ${error.message}` }],
      isError: true
    };
  }
}

Set up the HTTP server

ChatGPT connects to your server via HTTP. The /mcp endpoint handles the MCP protocol.

const PORT = process.env.PORT || 8787;

const httpServer = createServer(async (req, res) => {
  // CORS headers (required for ChatGPT)
  if (req.method === "OPTIONS") {
    res.writeHead(204, {
      "Access-Control-Allow-Origin": "*",
      "Access-Control-Allow-Methods": "POST, GET, OPTIONS, DELETE",
      "Access-Control-Allow-Headers": "Content-Type, mcp-session-id"
    });
    res.end();
    return;
  }

  // MCP endpoint
  if (new URL(req.url, `http://localhost`).pathname === "/mcp") {
    res.setHeader("Access-Control-Allow-Origin", "*");

    const server = createPoiSearchServer();
    const transport = new StreamableHTTPServerTransport({
      sessionIdGenerator: undefined,  // Stateless mode
      enableJsonResponse: true
    });

    res.on("close", () => {
      transport.close();
      server.close();
    });

    await server.connect(transport);
    await transport.handleRequest(req, res);
    return;
  }

  res.writeHead(404);
  res.end("Not Found");
});

httpServer.listen(PORT, () => {
  console.log(`MCP Server running at http://localhost:${PORT}/mcp`);
});

Understanding the Widget

When a tool returns structuredContent, ChatGPT can render a custom UI embedded directly in the chat interface known as a widget. This is what transforms our app from plain text responses into an interactive map experience.

The widget is loaded in an iframe within ChatGPT. It receives data from the tool via window.openai.toolOutput and can render anything a web page can: maps, charts, forms, or any interactive UI. In our case, the widget (public/widget.html) displays a Mapbox map with place markers and a clickable sidebar.

Since the widget is just HTML/CSS/JavaScript, you have full control over the user experience without requiring any special framework.

Updating the Widget's Data

The data arrives via window.openai.toolOutput and it might not be available immediately when your script runs. We set up an event listener to ensure the widget can updated once the data is received from the API's.

// Traditional app
const places = await fetch('/api/places').then(r => r.json());

// ChatGPT App - data comes from tool output
const places = window.openai?.toolOutput?.places;

// But it might arrive later, so also listen for updates
window.addEventListener("openai:set_globals", (event) => {
  const places = event.detail?.globals?.toolOutput?.places;
  // Re-render with new data
});

Widget structure

<!DOCTYPE html>
<html>
<head>
  <script src="https://api.mapbox.com/mapbox-gl-js/v3.14.0/mapbox-gl.js"></script>
  <link href="https://api.mapbox.com/mapbox-gl-js/v3.14.0/mapbox-gl.css" rel="stylesheet"/>
  <style>
    /* Sidebar + map layout */
    .container { display: flex; height: 100vh; }
    .sidebar { width: 280px; overflow-y: auto; padding: 1rem; }
    .sidebar.hidden { display: none; }
    .map { flex: 1; }
    /* Place cards, markers, etc. */
  </style>
</head>
<body>
  <div class="container">
    <!-- Sidebar starts hidden until results arrive -->
    <div class="sidebar hidden">
      <h2 id="place-count">Places nearby: 0</h2>
      <div id="listings"></div>
    </div>
    <div id="map" class="map"></div>
  </div>

  <script>
    // Get data from ChatGPT tool output
    let places = window.openai?.toolOutput?.places || { type: "FeatureCollection", features: [] };
    let mapCenter = window.openai?.toolOutput?.center || [-77.03915, 38.90025];
    let mapZoom = window.openai?.toolOutput?.zoom || 4;

    // Listen for data updates
    window.addEventListener("openai:set_globals", (event) => {
      const output = event.detail?.globals?.toolOutput;
      if (output?.places) {
        places = output.places;
        mapCenter = output.center ?? mapCenter;
        mapZoom = output.zoom ?? mapZoom;
        // Re-render everything
        clearMarkers();
        addMarkers();
        buildLocationList();
        // Show sidebar now that we have data
        document.querySelector('.sidebar').classList.remove('hidden');
        map.resize();
        map.flyTo({ center: mapCenter, zoom: mapZoom });
      }
    });

    // Standard Mapbox GL JS code
    mapboxgl.accessToken = '{{MAPBOX_ACCESS_TOKEN}}';
    const map = new mapboxgl.Map({
      container: 'map',
      center: mapCenter,
      zoom: mapZoom,
      config: {
        basemap: { theme: 'faded' }
      }
    });

    // Add markers, build listings, handle clicks...
  </script>
</body>
</html>

Testing

1. Start the server

npm start

You should see:

POI Category Search MCP Server
==============================
Server running at: http://localhost:8787
MCP endpoint:      http://localhost:8787/mcp

2. Test with MCP Inspector

npx @modelcontextprotocol/inspector@latest http://localhost:8787/mcp

You should see the tool find_nearby_places and the resource places-widget in the inspector.

This lets you call tools and see responses without ChatGPT.

3. Expose with ngrok

ChatGPT needs a public URL to connect:

ngrok http 8787

Copy the https:// URL.

4. Add to ChatGPT and Test Your App

Go to ChatGPT → Settings → Apps & Connectors → Advanced settings
Enable developer mode
Add a connector with your ngrok URL + /mcp (e.g., https://abc123.ngrok.io/mcp)
Open a new chat, click the connector icon, add your connector
Try: "Find coffee shops near Times Square"

You've now successfully built and integrated your first ChatGPT App!

Additional Resources

Mapbox

Mapbox Location AI Tutorials repository
Mapbox MCP Server
Mapbox Store Locator Tutorial - The original tutorial this builds upon
Mapbox GL JS Documentation - Full guide to the mapping library
Mapbox Geocoding API - Convert addresses to coordinates
Mapbox Search Box API - Search for places by category
Mapbox Access Tokens - Get your API token

OpenAI / ChatGPT Apps

ChatGPT Apps SDK - Complete documentation for building ChatGPT Apps
MCP Inspector - Test your MCP server locally
Connecting Your App to ChatGPT

Introducing the Mapbox MCP Server: Location Intelligence for AI Agents

Matthew Podwysocki — Tue, 16 Dec 2025 14:43:34 +0000

AI agents are getting smarter every day as they can write code, analyze data, and answer complex questions. But when it comes to understanding where things are, most agents hit a wall. They can tell you about restaurants in San Francisco, but they can't geocode an address, calculate a route, or determine if two locations are within walking distance.

That's where the Mapbox Model Context Protocol (MCP) Server comes in. It gives AI agents access to Mapbox's powerful location services through a simple, standardized interface. No custom API integration required, just connect your agent to the MCP server, and it can instantly geocode addresses, plan routes, analyze travel times, and create maps.

Example: An AI agent built with MCP can naturally handle location queries and display results visually

What is the Model Context Protocol (MCP)?

The Model Context Protocol is an open standard created by Anthropic for connecting AI models to external tools and data sources. Think of it as USB for AI agents which is to say a universal connector that works across different frameworks and platforms.

Instead of writing custom code to integrate with each API, you:

Connect your agent to an MCP server
The server exposes its tools in a standardized format
Your agent can discover and use those tools automatically

MCP is supported by popular frameworks like CrewAI, LangGraph, Pydantic AI, and Mastra, as well as by AI assistants like GitHub Copilot and Claude Desktop.

What Does the Mapbox MCP Server Provide?

The Mapbox MCP Server exposes nine powerful geospatial tools that give your agents comprehensive location intelligence.

Note: Mapbox also offers the DevKit MCP Server (hosted at https://mcp-devkit.mapbox.com/mcp), which is designed to help developers build Mapbox applications by providing code examples, documentation search, and development assistance. This post focuses on the main MCP server for location intelligence. We'll cover the DevKit in a future post.

Core Tools

Tool	Purpose	Example Use
search_and_geocode_tool	Convert addresses/places to coordinates	"Find coordinates for '1600 Pennsylvania Ave, Washington DC'"
reverse_geocoding_tool	Convert coordinates to addresses	"What's the address at 38.8977, -77.0365?"
directions_tool	Calculate routes between points	"Driving directions from Boston to New York with traffic"
matrix_tool	Travel times between multiple points	"Calculate delivery times from 3 warehouses to 10 addresses"
isochrone_tool	Areas reachable within time/distance	"Show everywhere I can drive in 30 minutes from downtown"
static_image_tool	Generate map images	"Create a map showing my delivery route"
category_search_tool	Find POIs by category	"Find all museums near Central Park"
resource_reader_tool	Access reference data	"Get list of available POI categories"

What Makes These Tools Special

Unified Search & Geocoding: The search_and_geocode_tool consolidates forward geocoding and POI search into one powerful tool. It handles everything from "123 Main St" to "Starbucks near Times Square" to "Eiffel Tower."

Traffic-Aware Routing: The directions_tool supports real-time traffic data, alternative routes, and can optimize for different transportation modes (driving, walking, cycling).

Multi-Point Optimization: The matrix_tool efficiently calculates travel times between dozens of locations which is essential for logistics, delivery planning, and service area analysis.

Reachability Analysis: The isochrone_tool generates polygons showing areas reachable within specific time or distance thresholds which is perfect for analyzing coverage areas, commute zones, or delivery ranges.

Visual Output: The static_image_tool creates customizable map images with markers, routes, and overlays which is great for reports, notifications, or sharing with users.

Getting Started: Setup Options

You have two ways to use the Mapbox MCP Server:

Option 1: Hosted Server (Easiest to Get Started)

Mapbox provides a hosted MCP endpoint at https://mcp.mapbox.com/mcp that's always available with no installation required!

Authentication:

Interactive clients (Claude Desktop, VS Code): Uses OAuth flow with browser-based login
Programmatic access: Uses Bearer token authentication with your Mapbox access token

Setup:

For interactive tools like Claude Desktop, VS Code, or Cursor, add this to your MCP settings (typically in settings.json or similar config file):

{
  "mcpServers": {
    "mapbox": {
      "url": "https://mcp.mapbox.com/mcp"
    }
  }
}

For Claude Desktop specifically, the config file is located at:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

The first time you connect, a browser window will open asking you to log in to your Mapbox account and authorize access via OAuth.

For programmatic access (like in agent frameworks), you'll need:

A Mapbox account (free tier available) - Sign up here
Your Mapbox access token from your account dashboard

Then use Bearer token authentication in your code (see framework-specific tutorials for examples).

Check the Hosted MCP Server Guide for detailed setup instructions for different clients.

Pros:

No local setup or dependencies required
Managed infrastructure by Mapbox
Always available
Automatic updates
Perfect for getting started quickly

Cons:

Additional network hop (your machine → hosted MCP → Mapbox APIs)
Requires stable internet connection
Less control over configuration

Option 2: Local Server (For Development & Customization)

Run the MCP server as a local process on your machine. This gives you full control and is ideal for development, debugging, or customization.

Prerequisites:

Node.js LTS+ (for npx method) OR Python 3.10+ with uv (for uvx method)
A Mapbox account (free tier available) - Sign up here
Your Mapbox access token from your account dashboard

Setup:

For interactive tools like Claude Desktop, VS Code, or Cursor, add this to your MCP settings:

{
  "mcpServers": {
    "mapbox": {
      "command": "npx",
      "args": ["-y", "@mapbox/mcp-server"],
      "env": {
        "MAPBOX_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

For Claude Desktop specifically, the config file is located at:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

For command-line testing, you can run the server directly:

# Set your access token
export MAPBOX_ACCESS_TOKEN="your_token_here"

# Run with npx (recommended)
npx -y @mapbox/mcp-server

# OR run with uvx (Python users)
pip install uv
uvx mapbox-mcp

Test it with MCP Inspector:

npx @modelcontextprotocol/inspector npx -y @mapbox/mcp-server

This opens a web interface where you can explore available tools and test them interactively.

Pros:

Full control over the server process
Lower latency (direct connection to Mapbox APIs)
Works with any Mapbox token
Can customize or extend if needed
Better for development and debugging

Cons:

Requires Node.js or Python tooling
Server process management
Must ensure dependencies are installed

Example Use Cases and Prompts

Once connected, your agents can handle natural language requests like these:

Location Discovery

"Find coffee shops within walking distance of the Empire State Building"
"Show me gas stations along the route from Boston to New York"
"What restaurants are near Times Square?"

Navigation & Travel

"Get driving directions from LAX to Hollywood with current traffic"
"How long would it take to walk from Central Park to Times Square?"
"Calculate travel time from my hotel (Four Seasons) to JFK Airport by taxi"
"What's the fastest route visiting Salesforce Tower, Twitter HQ, and Uber headquarters?"

Visualization & Maps

"Create a map image showing the route from Golden Gate Bridge to Fisherman's Wharf"
"Show me a satellite view of Manhattan with key landmarks marked"
"Generate a map highlighting all Starbucks locations within a mile of downtown Seattle"

Analysis & Planning

"Show me areas reachable within 30 minutes of downtown Portland by car"
"Calculate a travel time matrix between 3 hotel locations and the convention center"
"Find the optimal route visiting 3 tourist attractions in San Francisco"
"I'm staying at the Fairmont. Show me everywhere I can reach by walking in 15 minutes"

Behind the Scenes

When you ask: "How long does it take to drive from the Space Needle to Pike Place Market?"

The agent automatically:

Uses search_and_geocode_tool to find Space Needle coordinates
Uses search_and_geocode_tool to find Pike Place Market coordinates
Calls directions_tool with driving profile
Returns: "約 8 minutes, 1.2 miles"

No manual API calls, no coordinate formatting, no error handling as the agent figures it all out.

Supported Frameworks and Tools

The Mapbox MCP Server works with any MCP-compatible client, including:

AI Agent Frameworks

CrewAI (Python) - Multi-agent collaboration
LangGraph (Python) - Stateful agent workflows
Pydantic AI (Python) - Type-safe agent development
Mastra (TypeScript) - Production AI applications
Smolagents (Python) - Lightweight agents from Hugging Face

Development Tools

Claude Desktop - Anthropic's AI assistant
ChatGPT - OpenAI's desktop application
Gemini CLI - Google's command-line tool
VS Code - Via MCP extensions
Cursor - AI-powered IDE
Goose - Terminal-based AI assistant

Integration Approaches

Each framework has slightly different integration patterns, but they all follow the same basic flow:

Configure the MCP server connection
Add the configuration to your agent
The agent automatically discovers available tools
Use natural language to invoke tools

We'll be publishing detailed tutorials for each major framework. Stay tuned for:

CrewAI: Building multi-agent location-aware systems
Pydantic AI: Type-safe location intelligence
Smolagents: Lightweight location-enabled agents
Mastra: Production TypeScript agents with Mapbox

Key Advantages of Using MCP

No Custom API Integration: Traditional approach requires writing geocoding logic, formatting coordinates, handling errors, chaining API calls. With MCP, you just describe what you want in natural language.

Automatic Tool Discovery: The MCP server exposes its tools in a standardized format. Your agent discovers available tools automatically and no manual configuration of each tool.

Framework Agnostic: Write once, use everywhere. The same Mapbox MCP server works with CrewAI, LangGraph, GitHub Copilot, Claude Desktop, and any other MCP-compatible client.

Natural Language Interface: Agents interpret your task descriptions and choose the right tools. Say "plan a route visiting three restaurants" and the agent figures out it needs to geocode, then calculate directions, then optimize the order.

Intelligent Tool Chaining: Agents understand dependencies between tools. They know addresses must be geocoded before calculating routes, and they handle this automatically.

Real-World Applications

Travel & Hospitality

Hotel concierge bots that provide directions and local recommendations
Trip planning assistants that optimize multi-stop itineraries
Event coordinators calculating travel times for attendees

Logistics & Delivery

Route optimization for delivery fleets
Service area analysis for expansion planning
Warehouse location analysis based on customer distribution

Real Estate

Commute time calculators for property listings
School district and amenity proximity analysis
Neighborhood boundary visualization

Field Services

Technician dispatch optimization
Service area coverage analysis
Emergency response time calculations

Location-Based Marketing

Store locators with accurate directions
Coverage area mapping for service offerings
Competitive location analysis

Getting Help and Resources

Documentation

Mapbox MCP Server GitHub - Source code and documentation
Hosted MCP Server Guide - Setup for different clients
Model Context Protocol Spec - MCP standard documentation
Mapbox API Docs - Underlying API reference

Support

Email: mcp-feedback@mapbox.com
Issues: GitHub Issues
Community: Join discussions in the MCP community

Pricing and Rate Limits

The Mapbox MCP Server uses your Mapbox account and access token. Pricing follows standard Mapbox API rates:

Geocoding: 100,000 requests/month free
Directions: 5,000 requests/month free
Matrix: Counts as multiple requests (origins × destinations)
Static Maps: 50,000 requests/month free

The free tier is generous for development and small projects. For production use, check Mapbox pricing for details.

Next Steps

Ready to add location intelligence to your AI agents?

Sign up for Mapbox: Get your free access token at mapbox.com/signup
Try the MCP Inspector: Test the server and explore available tools
Pick a framework: Start with CrewAI, LangGraph, or your preferred agent framework
Build something: Check out our framework-specific tutorials (coming soon!)

In our next post, we'll dive deep into building a multi-agent travel planning system with CrewAI and Mapbox MCP, complete with working code you can run and customize.

Also coming soon: A guide to the Mapbox DevKit MCP Server, which helps AI assistants write Mapbox code by providing documentation, examples, and API guidance which is perfect for developers building Mapbox applications.

Have questions or want to share what you're building? Reach out to mcp-feedback@mapbox.com or open an issue on GitHub.

Build quickly with npm create @mapbox/web-app

Andrew Sepic — Fri, 12 Dec 2025 15:45:44 +0000

The Mapbox Developer Relations team recently released a new developer tool to help web developers quickly scaffold Mapbox GL JS into their favorite frontend frameworks. You can now go from zero to hero with a map in your app in about 10 seconds. 🚀

To get started, ensure you have npm installed and run the command in your terminal.

$ npm create @mapbox/web-app

(Requires Node.js v20+.)

Why this is helpful

If you work with Mapbox GL JS in modern JavaScript frameworks, you'll know that spinning up a map in your app can take more time and effort than you'd like. This tool abstracts away project configuration, dependency management and lets developers get a simple map running very quickly. This allows you to test ideas & features fast, without having to clone a local repo or project as a starting point.

`npm create @mapbox/web-app`

The npm create @mapbox/web-app package is a CLI tool that uses Vite templates to quickly build a project into the following frameworks:

Vanilla JS (with & without a bundler)
React
Vue
Svelte
Angular

You can also also add interactive search to your map by adding Mapbox Search JS via the install prompts.

The CLI tooling asks 4 questions:

Which framework do you want to use?
Choose a project name..
Access Token - Insert your public Mapbox access token and the tooling will pass this into the appropriate local .env file. Get yours from your developer console
Add Search JS (or not)

After answering those questions you'll have a full-screen Mapbox GL JS map loading in the browser within seconds, ready for you to customize. 🔥

Next Steps

Now that you have a full screen map loaded, where do you want to go next? If you are a new developer using Mapbox, you can expand this simple application by following one of these tutorials:

The tutorials above demonstrate state management best practices for these frameworks, how to track & display map state into the application UI and how to trigger map events from the UI.

If you are an experienced developer and are familiar with Mapbox products, you can browse our tutorials for inspiration or search them for your use case.

More Information on Github

You can find more information about this CLI tool and report issues on Github.