Pitch and Bearing in Maptoolkit Maps JS
Pitch tilts the map toward the horizon (0 is top-down, 60 gives a perspective view), while bearing rotates it around the vertical axis (0 is north-up, 90 is east-up). Both are set in the Map constructor and can be changed at any time with map.setPitch and map.setBearing. Use pitch and bearing to create dramatic 3D city views, align the map with a user’s heading, or give a scenic perspective for outdoor and terrain maps.
const API_KEY = 'YOUR_API_KEY';
const map = new maptoolkit.Map({
container: 'map',
apiKey: API_KEY,
style: `https://styles.maptoolkit.net/maptoolkit/maptoolkit.summer.json?api_key=${API_KEY}`,
center: [11.39085, 47.27574],
zoom: 13,
pitch: 60,
bearing: -17.6,
attributionControl: { compact: false }
});
map.addControl(new maptoolkit.NavigationControl(), 'top-right');
map.on('load', () => {
map.addSource('terrain-rgb', {
type: 'raster-dem',
tiles: [`https://tiles.maptoolkit.net/terrain/{z}/{x}/{y}.webp?api_key=${API_KEY}`],
tileSize: 256,
minzoom: 5,
maxzoom: 12,
encoding: 'terrarium'
});
map.setTerrain({ source: 'terrain-rgb', exaggeration: 1.5 });
// Force one render after the DEM source loads so terrain shows on initial load
map.once('idle', () => map.triggerRepaint());
});<!DOCTYPE html>
<html lang="en">
<head>
<title>Pitch and Bearing - Maptoolkit Maps JS</title>
<meta property="og:description" content="Initialize a map with a custom pitch and bearing." />
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<script src="https://unpkg.com/@maptoolkit/maps@11.0.0-beta.3/dist/maptoolkit.js"></script>
<link rel="stylesheet" href="https://unpkg.com/@maptoolkit/maps@11.0.0-beta.3/dist/maptoolkit.css" />
<style>
html, body { width: 100%; height: 100%; margin: 0; padding: 0; }
#map { width: 100%; height: 100%; }
</style>
</head>
<body>
<div id="map"></div>
<script>
const API_KEY = 'YOUR_API_KEY';
const map = new maptoolkit.Map({
container: 'map',
apiKey: API_KEY,
style: `https://styles.maptoolkit.net/maptoolkit/maptoolkit.summer.json?api_key=${API_KEY}`,
center: [11.39085, 47.27574],
zoom: 13,
pitch: 60,
bearing: -17.6,
attributionControl: { compact: false }
});
map.addControl(new maptoolkit.NavigationControl(), 'top-right');
map.on('load', () => {
map.addSource('terrain-rgb', {
type: 'raster-dem',
tiles: [`https://tiles.maptoolkit.net/terrain/{z}/{x}/{y}.webp?api_key=${API_KEY}`],
tileSize: 256,
minzoom: 5,
maxzoom: 12,
encoding: 'terrarium'
});
map.setTerrain({ source: 'terrain-rgb', exaggeration: 1.5 });
// Force one render after the DEM source loads so terrain shows on initial load
map.once('idle', () => map.triggerRepaint());
});
</script>
</body>
</html>Use the prompt below with any LLM to get the same result. Make sure the Maptoolkit MCP server is connected first — check out AI Integration & MCP to get started.
How it works
Two independent camera angles. pitch tilts toward the horizon, where 0 is straight down and
larger values are more oblique. bearing rotates around the vertical axis, where 0 is
north-up and 90 puts east at the top.
Both can be set at construction or changed later with setPitch and setBearing, or together
through any camera method’s options.
Pitch has a ceiling, and the default is lower than the maximum the renderer supports.
maxPitch raises it, which is what the terrain examples do to let users tilt further toward
the horizon.
Pitch is what makes 3D content visible at all: extrusions and terrain look like flat polygons from directly above. It also costs performance, since a tilted view pulls in tiles from much further away.
Next steps
Pitch and bearing are most useful when something drives them. Rotating the map to match a travel direction, or tilting as the user zooms into a city, both make the camera respond to what is happening rather than sit where it was put.
Saving and restoring the full camera state, including both angles, is the other common need, whether for a share link or for returning users to where they left off, which is the same state a jump between views sets.