Skip to content
squidmapsBeta

← Blog

Custom basemaps, now from your AI assistant

squidmaps' custom basemaps give you a short list of controls instead of every layer, so you, or an AI assistant using the ephemeral maps API, can give a map its own look.

Chris WhongFounder and Builder at squidmaps

The basemap is the biggest thing on any web map. It’s the land, water, roads and labels behind your own points, lines and areas, and it sets the mood before anyone reads a word. A quiet gray basemap says “look at my data”. A pink one says something else entirely.

The Basemap section of the editor's left panel, set to Light, beside a menu of squidmaps basemaps with thumbnails of Streets, Light, Gray and Dark, and Light selected.
squidmaps' four basemaps, in the editor's basemap picker.

squidmaps has had custom basemaps for a while: pick one of our basemaps and change its colors. As of this week, a map made through the ephemeral maps API can bring its own custom basemap. That’s the API that AI assistants use through the squidmaps MCP server, so you can now ask Claude or ChatGPT for a map and the look of the map underneath it, in one conversation.

To show what that means, I asked an assistant for three maps, each with a themed basemap, and gave it no other direction. Here they are, live.

Three maps, three basemaps

“Make a map with a bubblegum themed basemap.” The assistant chose Manhattan and a couple of candy shops, then made the land pink, the water mint and the roads hot pink.

Bubblegum Manhattan: pink land, mint water and cotton-candy roads.

“Now make another one with a Middle-earth themed basemap.” Parchment land, ink-wash water and sepia roads, with buildings and railways turned off so it reads like an old hand-drawn map. The features are Lord of the Rings filming locations in New Zealand.

Middle-earth in New Zealand, on a parchment basemap.

“Now make one with a futuristic Tron style.” Glowing cyan roads on near-black, orange railways, and a few Tokyo landmarks in matching orange.

Neon Tokyo, on a glowing grid.

Each one took a single request. Then I added them to my account and published them.

Our approach: a few controls, not every layer

A modern vector basemap is made of dozens of layers: separate ones for highways, major roads, minor roads, their casings and their tunnels, every kind of label, land use, and so on. Full style editors like Maputnik let you change all of them, and that’s great if you’re a cartographer with an afternoon to spare. For most people it’s a wall of options where it’s easy to make a mess.

So squidmaps doesn’t hand you the layers. It gives you a short list of the things people actually want to change, and each one does the sensible thing across all the layers behind it:

Each control can change some of three things: its color, its opacity, and whether it’s shown at all. Fading the streets or hiding the buildings is often what lets your own features stand out.

A custom basemap starts from one of our four basemaps (Streets, Light, Gray or Dark) and only records what you changed. Anything you leave alone keeps that basemap’s look. And because a control is defined in terms of the basemap’s palette rather than individual layers, your basemap keeps working when we update the basemaps underneath it.

That small, fixed set of controls turns out to be just as useful for an AI assistant. There’s no layer list to dig through, only around twenty named things with a color, an opacity and an on/off switch. That’s easy to get right from a prompt like “bubblegum” or “Middle-earth”.

The custom basemap editor, with controls for land, water, roads and labels, each with a color and some with an opacity and a show or hide button, beside a live preview of Lower Manhattan, and a color picker open on Water.
The custom basemap editor: a color, an opacity and a show/hide switch for each control, with a live preview.

Made by an assistant, yours to keep

A map made through the API is temporary until someone claims it. When you open its link and add it to your account, its custom basemap comes too, saved to your account like any basemap you’d made yourself. From there:

So you can let an assistant rough out a style, then finish it yourself. Or the other way around.

For developers

Most people will never see any of this: they’ll use the editor or ask their assistant. But if you’re building on squidmaps, here’s how it fits together.

A squidmaps map is one JSON document in the open map spec. Its basemap field names the basemap under the features. A custom basemap saved to an account is { "type": "CUSTOM", "id": "<its id>" }.

When you create an ephemeral map, you can send the basemap’s definition alongside the map, as customBasemap. Here’s the one behind Bubblegum Manhattan:

{
  "name": "Bubblegum Manhattan",
  "basemap": { "type": "CUSTOM", "labelVisibility": true },
  "customBasemap": {
    "name": "Bubblegum",
    "description": "Pink land, minty water, cotton-candy roads.",
    "base": "light",
    "customizations": {
      "land": { "color": "#FFD6EA" },
      "water": { "color": "#8FE3E8" },
      "parks": { "color": "#B8F2C9" },
      "beaches": { "color": "#FFF0B3" },
      "areas": { "color": "#FFC4E1" },
      "buildings": { "color": "#FF9CCB", "opacity": 0.6 },
      "highways": { "color": "#FF5FAE" },
      "major_roads": { "color": "#FF8EC4" },
      "streets": { "color": "#FFFFFF" },
      "road_outlines": { "color": "#F7A8CF" },
      "railways": { "color": "#C58BE8" },
      "boundaries": { "color": "#B46BD9" },
      "country_labels": { "color": "#8A2F6B" },
      "city_labels": { "color": "#8A2F6B" },
      "neighborhood_labels": { "color": "#A8467F" },
      "street_labels": { "color": "#A8467F" },
      "water_labels": { "color": "#1F7E8A" }
    }
  },
  "features": [...]
}

The ephemeral maps docs list every control, which of them each basemap draws, and how to change the basemap along with the map.

Try it

If you use Claude, ChatGPT or another assistant with MCP, add the squidmaps server and ask for a map with a basemap to match: your team’s colors, a dark map for a night-time story, or something just for fun. Then claim it, and the basemap is yours.

Sign up →