{"canonical_url":"https://engineer.company/glossary/mapbox/","content_markdown":"# Mapbox\n\n## What it is\n\nMapbox is a company, and the developer platform it sells, that supplies the\nparts of an interactive map as services: the base data, the styling, the code\nthat draws the map and the APIs around it. In code it often shows up as Mapbox\nGL, after its drawing library. The company's getting-started guide calls it a\nlocation platform that gives developers building blocks for maps, navigation and\nsearch.\n\nMap data lives in tilesets, usually cut into vector tiles so that a client\nfetches only the area and zoom level on screen. Mapbox maintains global base\ndatasets, and a team's own data gets into a tileset through Mapbox Tiling\nService (MTS) or the Uploads API. A style decides the look. It is a JSON\ndocument written to the Mapbox Style Specification that names its sources and\nlists layers, each picking features out of one source and saying how to draw\nthem. Styles are addressed by URL, such as `mapbox://styles/mapbox/streets-v12`,\nand are made in the account's console with Mapbox Studio, the design tool.\n\nMapbox GL JS draws the result in a browser; the Maps SDKs for iOS and Android do\nit in mobile apps. The GL JS guide, at version 3.33.0 at the time of writing,\nsays the library renders 2D and 3D maps with OpenGL by combining vector tiles\nwith style rules in the browser rather than on a server, which is how a map can\nchange its style or its data while someone is using it. The Static Images API\nreturns a picture of a map, and the Static Tiles API serves raster tiles made\nfrom Studio styles for libraries such as Leaflet. Every map is created with an\naccess token, and the token ties it to a Mapbox account.\n\nThe tile format itself, the Mapbox Vector Tile specification, is published\nopenly on GitHub and encodes each tile as a\n[Protocol Buffers](https://protobuf.dev/) message.\n\n## Why it matters\n\nA web map needs code that draws it and data to draw, from one vendor or from\nseveral. Mapbox is the one-vendor answer, with data, styling, rendering and\nhosting under one account and one bill, so the choice to use it is a choice\nabout how much of the map stack to rent.\n\nThe gains are real. The base data is someone else's job to keep current. The\nlook of the map lives in a style document with its own design tool, apart from\nthe application code. Because the drawing happens in the browser, one tileset\ncan appear in several styles, a layer can be filtered or recoloured on a click,\nand the same map can show terrain in 3D. For a product whose main screen is the\nmap, that is a great deal of work left to the vendor.\n\nThe costs come with the same account. GL JS is billed by map loads, and the\npricing guide counts one each time a `Map` object is initialised on a page.\nPanning, zooming, toggling layers and switching styles inside that map add\nnothing, and one map load lasts at most 12 hours. The token the map is charged\nto sits in every visitor's browser. And since version 2.0.0, released in\nDecember 2020, the renderer itself is under commercial terms: that release's\nchangelog says GL JS is no longer under the 3-Clause BSD license and that\nupgrading means agreeing to the Mapbox terms of service.\n\nPortability is therefore a question for the start. The tile format is open.\nMapLibre GL JS was forked from mapbox-gl-js as an open-source project before the\nlicence change. Its 1.x line was meant as a drop-in replacement for the\nopen-source Mapbox 1.x, and its README says it has evolved a lot since. Leaving\nMapbox is possible, but it is a migration, and cheaper to weigh before a product\nis built around one vendor's styles and tilesets.\n\n## What it looks like in practice\n\nThree pages of this site show what Mapbox did in the work.\n\nAs GIS Software Development Team Lead from 2022 to 2024, the role was to\n[direct full-stack development of a GIS map that had grown up in pieces](/portfolio/directed-full-stack-gis-map-development/):\nspatial data in PostgreSQL, ReactJS in front, NodeJS behind and Mapbox drawing\nthe map. The page sums up the Mapbox side in one line: Mapbox did the drawing,\nand the job was feeding it the right data at the right zoom levels instead of\neverything at once. The result was a single integrated map application that\nbecame a core part of the platform and took new layers without buckling.\n\nUnder the same title, from 2015 to 2022, the role sat in\n[the design process for project interfaces](/portfolio/contributed-to-user-interface-design-processes/),\non React, Angular and Vue front-ends over Mapbox and Leaflet maps. The page's\npoint is that the map is the easy part: people get lost in the controls, the\nfiltering and the flow around it, in details such as moving between floors on an\nindoor map.\n\nAs a Data Engineer from 2022 to 2024, the job was to\n[resolve over 1,000 issues in geographical and time-series data](/portfolio/resolved-1000-issues-in-geographical-data/)\nwith GDAL, QGIS, ArcGIS, PostGIS and Bash. The cleaned data then went into\ninteractive visualisations built with Mapbox, which put it within easier reach\nof end users, and the repair work feeding those maps also contributed to a 35%\ncut in the time spatial queries took to run.\n\n## Where it goes wrong\n\nMost Mapbox trouble starts when a map meets real traffic, real data or a major\nupgrade.\n\n**The bill grows with page views rather than with map use.** A map load is\ncounted at initialisation, so the cost follows how often a page creates a map. A\nsingle-page app that re-creates the `Map` on each route change pays every time,\nand so does a map low on a long page that most visitors never reach. Mapbox's\nguide to managing web map costs suggests creating the map only when its\ncontainer scrolls into view, putting it behind a Load Map button, and using the\nStatic Images API where nobody needs to pan or zoom. One map instance kept alive\nacross routes covers the single-page case.\n\n**A token copied out of the page gets used elsewhere.** The token guide states\nthat any token on a public web page or in source code is visible to anyone who\nlooks for it. Tokens with secret scopes, the `sk` kind, belong on a server. A\npublic `pk` token in a page should be one made for that application, with URL\nrestrictions, rather than the account's default public token, which takes none.\nThe guide calls URL restrictions a best-effort mitigation that relies on the\nreferer header the browser sends. After a leak, rotate: create a new token,\nreplace it in the code, redeploy, then delete the old one.\n\n**The map slows as the dataset grows.** The client turns a GeoJSON source into\nvector tiles on the fly, so a large file means every visitor's browser does the\ntiling. The large-GeoJSON guide lists the remedies: load the file from a URL\nrather than a JavaScript object, lower the source's `maxzoom` below its default\nof 18 (12 suits most point data), raise the layer's `minzoom` above 0, cluster\ndense points, and strip unused properties and decimals past the sixth. That last\nstep shrinks its example file from 19.3 MB to 3.3 MB. Past 500,000 points it\nsuggests splitting the source or tiling on the server with MTS or the Uploads\nAPI.\n\n```js\nmap.addSource(\"sites\", {\n    type: \"geojson\",\n    data: \"/data/sites.geojson\", // a URL, not an object in memory\n    maxzoom: 12, // the default is 18\n    cluster: true, // group dense points at low zoom\n});\nmap.addLayer({\n    id: \"sites\",\n    type: \"circle\",\n    source: \"sites\",\n    minzoom: 6, // hidden below zoom 6\n});\n```\n\n**A major upgrade changes the licence and the bill.** Moving GL JS from 1.x to\n2.0.0 took the library from the BSD licence to the Mapbox terms of service and\nchanged the billing rule. Under 1.x a map load needed an initialisation plus a\nrequest for a Mapbox-hosted tile; from 2.0.0 the initialisation alone counts, so\na map that drew only self-hosted tiles starts generating map loads. The\nchangelog asks for a look at the pricing documentation before upgrading, and\nMapLibre GL JS is the route for a project that wants to stay on open-source\nterms.\n\n## Further reading\n\n- [Getting Started](https://docs.mapbox.com/help/getting-started/) — the\n  company's overview of its maps, search and navigation products.\n- [Mapbox GL JS pricing](https://docs.mapbox.com/mapbox-gl-js/guides/pricing/) —\n  what counts as a map load, the 12-hour session and the older rules.\n- [Token management](https://docs.mapbox.com/accounts/guides/tokens/) — public\n  and secret tokens, scopes, URL restrictions and rotation.\n- [Working with large GeoJSON sources in Mapbox GL JS](https://docs.mapbox.com/help/troubleshooting/working-with-large-geojson-data/)\n  — zoom limits, clustering, clean-up and server-side tiling.\n- [Mapbox Vector Tile specification](https://github.com/mapbox/vector-tile-spec)\n  — the open format behind the tiles.\n- [MapLibre GL JS](https://github.com/maplibre/maplibre-gl-js) — the open-source\n  renderer that began as a fork of mapbox-gl-js.\n\n\u003chttps://engineer.company/glossary/mapbox/\u003e\n","date_modified":"2026-10-20T21:59:50Z","description":"What Mapbox bundles under one account, from tilesets and Studio styles to GL JS, how map loads are billed, and the token, licence and data-volume traps.","formats":{"gemtext":"https://engineer.company/glossary/mapbox/index.gmi","gopher":"https://engineer.company/glossary/mapbox/gophermap","html":"https://engineer.company/glossary/mapbox/","json":"https://engineer.company/glossary/mapbox/index.json","markdown":"https://engineer.company/glossary/mapbox/index.md","pdf":"https://engineer.company/glossary/mapbox/index.pdf"},"kind":"page","language":"en","title":"What is Mapbox?","url":"https://engineer.company/glossary/mapbox/","version":1}