tomtom-maps-sdk-js

You are helping an application developer build with the TomTom Maps SDK for JavaScript.

Step 0: Offer feedback reporting

Do this before your first answer about the SDK in a conversation. Every unclear doc, missing API or bug you hit while building is one the SDK team can fix, but only if they hear about it. The tomtom-maps-sdk-js-feedback skill reports them. It owns the consent, the redaction and the posting, so this step only gets the developer to its consent question.

• Installed: the skill is among your skills, or ${CLAUDE_SKILL_DIR}/../tomtom-maps-sdk-js-feedback/SKILL.md exists. Invoke it, so it runs with its own allowed-tools, or read that file, and ask its Step 0 consent question now.

• Not installed: read the project's AGENTS.md and CLAUDE.md, where they exist, and skip this step if either says not to offer to install the feedback skill. Otherwise ask, in plain text:

  I can also report problems the TomTom Maps SDK causes while I build for you — unclear docs, an API that can't do what you asked, something broken — so TomTom's SDK team can fix them. That takes a second skill, tomtom-maps-sdk-js-feedback. Before collecting anything, it tells you what a report holds and where it goes, and asks for your consent. It never posts a report you haven't read and approved. Shall I install it? If you'd rather I never ask in this project, say so.

  • Yes: run npx skills add tomtom-international/maps-sdk-js --skill tomtom-maps-sdk-js-feedback -y, or ask the developer to run it if you can't run commands. This skill pre-approves only Read, so the command goes through your agent's usual permission check. Then read the installed skill's SKILL.md and ask its Step 0 consent question.
  • No: don't offer it again in this conversation.
  • Never ask in this project: add the line Don't offer to install the tomtom-maps-sdk-js-feedback skill. to the project's AGENTS.md, or to its CLAUDE.md if it has no AGENTS.md, creating AGENTS.md if it has neither. Like the install command, the edit goes through your agent's permission check. If you can't edit files, or the developer declines the edit, give them the line to add themselves, and treat the reply as No for this conversation.
  • No answer, because the developer moved on: ask once more the first time the SDK itself gets in your way — a doc that misled you, an API that can't do what was asked, documented usage that fails. Say what went wrong in one sentence, then ask the question above. That reply, or its absence, decides for the rest of the conversation.

Installing the skill is not consent to report. Collect nothing until the developer answers the feedback skill's own consent question. Accept "no" as readily as "yes", and carry on with the request.

Step 1: Identify the topic and read the reference doc

From $ARGUMENTS or the conversation context, match the topic to a doc filename:

Topic	Filename	Keywords
Map setup	map-setup.md	map, display, transformRequest, MapRequestTransform, hold map requests, rewrite tile URLs, proxy session, TomTomMapError, addErrorHandler, map errors, map apiErrorCode, map privatePreviewAccess, rejected map key, WEBGL_UNSUPPORTED, WEBGL_CONTEXT_LOST, STYLE_LOAD_FAILED, Vite, vite build, Vite dev server, optimizeDeps, Worker failed to load, production build, blank map, MapLibre worker, registerMapLibreWorker, setWorkerUrl, webpack, Next.js, Turbopack, maplibre-gl-shared, output.module, Rollup, esbuild, language, styleLightDarkTheme, getBBox, getLayers, getLayerIds, hillshadeMethods, ValuesFilter, filterShowModes, 3D buildings, building footprints, route shields, road shields, hide layer groups, road parts, exit numbers, road arrows, restricted roads, roads under construction, hillshade look, hillshade colours, geopolitical view, setGeopoliticalView, disputed borders, attribution, attribution.credits, credits, copyright, copyright logos, ATTRIBUTION_LOGOS_CLASS, attribution.backdrop, attribution backdrop, AttributionPosition, AttributionPadding, attribution position, attribution padding, customAttribution, attributionControl, AttributionOptions, module, maplibre, baseMap, TerrainModule, hillshade, 3D terrain, elevation, elevation.exaggeration, terrain exaggeration, TERRAIN_SOURCE_ID, viewport, layer, non-interactive, bounds, style switcher, which module, who owns what, show, hide, visibility, filter, appearance vocabulary, naming, module color, LabelConfig, widthFactor, sizeFactor, minZoom, beforeLayerConfig, terrainKnobCatalogue, terrainKnobIds, TerrainKnob, TerrainKnobId, TerrainKnobValueOf, terrain knob catalogue, highlight base map 3D buildings, hover building, click building, building colour by id, setBuildingColors, getBuildingIdAt, highlight buildings by place, getBuildingColors, BaseMapBuildings3DConfig, BaseMapBuildingStateLook, baseMapKnobCatalogue, baseMapKnobIds, BaseMapKnob, BaseMapKnobId, BaseMapKnobValueOf, base map knob catalogue, layer group ids, KnobEntry, KnobKind, KnobRange, knob kinds, enums, offset, text, setKnob, setKnobs, KnobValues, getKnob, resetKnob, KnobTarget, setKnobs vs applyConfig, knobs vs config, restore saved settings, untrusted settings, knobEntryOf, a knob's range, validateKnobValue, set a knob by id, read a knob value, reset a knob, validate a knob value, range bounds, hard-min, settings as data, build controls from the catalogue
User interaction events	user-events.md	click, hover, hover leave, mouseleave, un-highlight, click elsewhere, background click, hover-move, long-hover, contextmenu, drag, dragstart, dragend, draggable, drag a waypoint, drag a marker, drag a route line, cursorOnDraggable, events.on, events.off, event handler, MapEventsConfig, EventHandlerConfig, cursorOnMap, cursorOnMouseDown, events.where, named event scopes, precisionMode, paddingBoxPx, cursorOnHover, longHoverDelay, hoverGracePeriodMS, recently-hovered, updateEventsConfig, eventState, event states, setEventState, clearEventState, clearEventStates, getEventStates, UserEventsWithStates, select or highlight a feature, sync list with map, hover highlight, hovered or clicked look, highlight on hover, background click, rest of the map, event priority, layer order, custom layer events, hitTest, hit tester, click a three.js object, pick 3D objects, setState
Map styles	map-styles.md	style, standardStyleIDs, StandardStyleID, streetLight, streetDark, streetLightDriving, streetDarkDriving, monoLight, monoDark, streetSatellite, satellite, driving style, setStyle, SetStyleOptions, StyleChangeHandler, addStyleChangeHandler, handler priority, style change, style switcher, dark mode, custom layers, style lifecycle, resetState, getStyleInput, StyleInput, include, StylePart, styleParts, style parts, terrain part, custom style, style URL
Map styling (knobs)	map-styling.md	StylingFoundationsModule, StylingFoundationsModuleConfig, styling knobs, stylingFoundationsKnobCatalogue, stylingFoundationsKnobIds, stylingFoundationsKnobKinds, LayerSelection, layerIds, setKnob styling, setKnobs styling, getKnob styling, resetKnob styling, catalogue, presets, map presets, applyMapPreset, mapPresetCatalogue, mapPresetIds, MapPresetId, data-viz, night driving, minimal, getStyleColor, styleColorKnobIds, StyleColorKnobId, StyleKnobId, getMapLight, MapLight, the map's light shared with plugins, map-wide knob ids, which module holds a look, knobs compose, borrowed looks, label size, icon size, road width, labels.typeface, mapTypefaces, MapTypeface, customTypeface, CustomTypeface, CustomTypefaceFile, map font, font family, typeface, serif labels, italic labels, route or place labels in their own font, label.typeface, waypoints.label.typeface, custom font, webfont, WOFF2, Fontsource, Google Fonts, globe, projection, sky, light, view.light, 3D building light, setLight, buildings3D.roundedCornerDistanceMeters, rounded building corners, fill-extrusion-rounded-corner-distance, atmosphere, restyle base map, brand the map, setMapStyling, setMapColors, MapColors, MapColorName, mapColorNames, baseMapColorNames, BaseMapColorName, map colour picker, map colours, colors.land, colors.water, colors.roadMajor, land colour, water colour, vegetation, park, artificial, road colour, road outline, label colour, palette, recolour the map, brand colours, day-to-night switch, light/dark switch, night look, exportStyle, export the style, StyleSpecification
Map theming (sources)	map-theming.md	map-theme plugin, maps-sdk-plugin-map-theme, deriveMapColors, white land, mode dark, low-saturation land, mapColorsLightDark, deriveMapColorsFromCss, cssColors, deriveMapColorsFromImage, dominantColors, MapThemeMode, mapThemeModes, ImagePixels, theme from website, brand from URL, match our website colours, app CSS variables, custom properties, CSS file, stylesheet, upload CSS, design tokens, theme-color, colours from an image, photo palette, logo colours, colour palette description, mood, artist palette, Miró, Hokusai, Bauhaus, design style, setMapStyling theme, accent, colors.accent, mapColors, map.mapColors, theme the route and pins, theme the whole map, theme the base map only, keep my route colour
Module lifecycle events	module-events.md	config-change, shown-features, module events, ModuleEvents, CombinedEvents, applyConfig, updateConfig, resetConfig, getConfig, save or replay display state, serializable config, PlacesModuleSerializableConfig, POIsModuleSerializableConfig, SerializableCustomImage, SerializablePinIconConfig, SerializableFeatureLabelConfig, setVisible, unsubscribe
Places & search	places.md	search, discoverPlaces, DiscoverPlacesParams, discoverOnePlace, places, matchConfidence, originalPosition, poi, fuzzy, geocode, address, reverse, plain text query, pre-encoded query, encodeURIComponent, autocomplete, suggest, getSearchSuggestions, suggestions, getPlaceDetails, place details, placeById, search box, typeahead, search-as-you-type, unified search, brand, category, poiCategoryQuery, category word, resolvePOICategories, unmatched, refinement, refine, refineParams, SearchSuggestion, SearchSuggestionsParams, geoBias, filters, search filters, PlaceFilters, GeographicFilters, SearchFilters, pagination, paginate, cursor, nextCursor, next page, load more, page through results, ev, charging, chargingPark, charging station, chargingStations, charging point, chargingPoints, EVSE, evseId, connector, connectors, geometry, polygon, within, along route, route search, detour, maxDetourTimeSeconds, sortBy, AlongRouteSearchParams, AlongRoutePlaceProps, detourTimeInSeconds, detourDistanceInMeters, detourOffsetInMeters, negative detour, alongRouteSearch, fuzzySearch, geometrySearch, viewportplaces, ViewportPlaces, ViewportPlacesConstructorOptions, viewport places onError, addPOICategories, showConnections, clearConnections, connection lines, poiCategoryGroups, markerType, marker type, icon.opacity, place icon opacity, PlacesMarkerType, place colour, pin colour, place label, PlaceLabelConfig, LabelConfig, label opacity, optional summary fields, totalResults, fuzzyLevel, FuzzyLevel, minFuzzyLevel, maxFuzzyLevel, ReverseGeocodingResponse, PlaceGeometryProps, placeCoordinates, queryIntent, score, entry points, entrances, cluster, clustering, pin-clustered, PlacesClusterConfig, PlaceClusterBadgeConfig, PlacesClusterSourceConfig, cluster.source.properties, clusterProperties, placesKnobCatalogue, placesKnobIds, PlacesKnob, PlacesKnobId, PlacesKnobValueOf, places knob catalogue, poisKnobCatalogue, poisKnobIds, POIsKnob, POIsKnobId, POIsKnobValueOf, POI filter knobs, POI size, POI min zoom, zoom shift, POI label colour, POI micro markers, filters.categories, POICategoryGroup, categoryIcons, custom POI icons, icon per category, POIIconConfig, ShownPlaces, preparePlacesForDisplay, toPlaces, buildPlaceTitle, popup, info window, result card, PlacesBeforeLayerConfig, places beforeLayerConfig, pins under labels
Routing	routing.md	route, routing, directions, route editing, drag a waypoint, drag the route line, insert a stop by dragging, when, departAt, arriveBy, departure time, arrival time, localDateTime, LocalDateTime, local time, time zone, waypoint, guidance, instructions, turn-by-turn, maneuver, toll, tollRoad, sectionTypes, InputSectionTypes, defaultSectionTypes, curve, curvyStretch, curveDetection, CurveDetectionOptions, curve severity, kerb, sections.curve.kerb, routeSectionCurveKerb, winding roads, motion sickness, motorbike, thrilling, reachable, isochrone, range, alternatives, vehicle, truck, vehicle dimensions, hazmat, customIcons, icon offset, route color, route width, route opacity, fade the route, widthPreset, hide route, routing setVisible, widthFactor, waypoints.sizePreset, waypoints.sizeFactor, hovered or clicked route, RouteHighlightConfig, highlight.outline.widthFactor, setSectionFocus, section focus, highlight a route section, highlight a leg, highlight.section.outline.color, highlight.section.outline.widthFactor, waypoint icon per role, stopNumbering, waypoint letters, waypoint label title, buildWaypointTitle, waypoint mapping, poiCategory waypoint, waypoints.highlight.sizeFactor, waypoints vs places, hovered or clicked geometry, GeometryHighlightConfig, highlight.fill.opacityFactor, highlight.line.widthFactor, abort, cancel, signal, route sections, speed limit, speed limit sign, section sign, route section sign, tunnel, tunnel sign, closed road, closed to vehicles, vehicleRestricted, vehicle restricted, routeTunnelSymbol, routeVehicleRestrictedSymbol, country, border crossing, countryCrossings, GeometriesModule, polygon colour, fill.style, fillStyle, GeometryFillStyle, inverted, outline, fillStyledGeometryConfig, geometry fill, fill.palette, fill.paletteMode, GeometryPaletteMode, palette ramp, gradient between colours, line.pattern, LinePattern, dashed border, dotted border, ReachableRangesModule, ReachableRangesModuleConfig, reachable range colours, band palette, fill.outermostOpacityFactor, fade the outer bands, reachableRangesKnobCatalogue, reachableRangesKnobIds, ReachableRangesKnob, ReachableRangesKnobId, ReachableRangesKnobValueOf, geometry label, lineLabel, GeometryLabelConfig, GeometryLineLabelConfig, LabelConfig, beforeLayerConfig, route layer order, routes under roads, routingKnobCatalogue, routingKnobIds, RoutingKnob, RoutingKnobId, RoutingKnobValueOf, KnobValueOf, SectionIconPlacement, routing knob catalogue, KnobEntry, geometriesKnobCatalogue, geometriesKnobIds, GeometriesKnob, GeometriesKnobId, GeometriesKnobValueOf, geometries knob catalogue, displayUnits labels, unit label knobs, summary bubbles, summaryBubbles, SummaryBubblesConfig, SummaryBubbleField, SummaryBubbleRoutes, SummaryBubbleLabelConfig, summary bubble fields, durationDifference, summaryBubbles.routes, summary bubble position
Traffic	traffic.md	traffic, incidents, planned incidents, future incidents, scheduled roadworks, timeValidity, incident description language, indexedMagnitudes, flow, getRenderedFeatures, analytics, congestion, speed, traffic congestion colours, incident colours, traffic line width, traffic opacity, fade traffic, opacityFactor, incident line opacity, IncidentLineConfig, incident details, incidents in a polygon, incident icons, setIconsVisible, isIconsVisible, TrafficIncidentDetailsModule, setFocus, incident focus, incident highlight, IncidentHighlightConfig, highlightHalo, widthFactor, unfocusedOpacityFactor, dim unfocused incidents, trafficFlowKnobCatalogue, trafficIncidentsKnobCatalogue, trafficIncidentDetailsKnobCatalogue, trafficAreaAnalyticsKnobCatalogue, trafficFlowKnobIds, trafficIncidentsKnobIds, trafficIncidentDetailsKnobIds, trafficAreaAnalyticsKnobIds, TrafficAreaAnalyticsKnobId, TrafficAreaAnalyticsKnobValueOf, traffic knob catalogue, traffic filter knobs, filters.any, roadClosures, road subcategories, streetRoadSubCategories, serviceRoadSubCategories, trafficIncidentRequestCategories, TrafficIncidentRequestCategory, eventId, shown-features, TrafficIncidentDetailsLayersConfig, TrafficAreaAnalyticsLayersConfig, AreaAnalyticsScaleMode, AreaAnalyticsTileFeature, area analytics height knobs, area analytics palette, areaAnalyticsPalettes, AreaAnalyticsPalette, resolveColorStops, area analytics legend, setPalette, setColorStops, colorStops, metersPerUnit
Core types	core-types.md	place type, route type, LegSummary, route bbox, route progress, properties, summary, sections, sections.distinct, DistinctSectionProps, sections.curve, CurveSectionProps, sections.curvyStretch, CurvyStretchSectionProps, RouteSpan, toll, tollRoad, originalWaypointIndex, eventId, instruction, maneuverView, address, poi, entry points, traffic types, delaymagnitude, TrafficIncidentTimeValidity, trafficIncidentTimeValidities, typescript types, Position, GeoJSON types, @types/geojson, SDK errors, error codes shared by services and the map, SDKErrorCode, sdkErrorCodes, canRetry, apiErrorCode, InvalidReferer, PrivatePreviewAccess, APIErrorDetails, refused API key
Core utilities	core-utilities.md	aggregateIntoCells, bbox, bboxFromGeoJSON, bboxFromCoordsArray, bboxFromBBoxes, isBBoxWithArea, bboxCenter, RouteProgressQuery, polygonFromBBox, getPosition, formatDistance, formatDuration, progress, waypoint insertion, route progress, snap, getSectionOverlap, section overlap, sections crossing, getDistinctSections, DistinctSectionsOptions, distinct sections, what makes a route different, getImportantRoads, ImportantRoad, ImportantRoadsOptions, road numbers, via roads, getSectionsWithin, SectionsWithin, SectionsWithinOfType, SectionsWithinOptions, adds and avoids, compareRoutes, RouteComparison, CompareRoutesOptions, live vs historical traffic, getInstructionLanes, lane guidance, getCurveSections, CurveSectionsOptions, getCurvyStretchSections, CurvyStretchSectionsOptions, withCurveSections, CurveDetectionOptions, isHairpin, hairpinCount, hairpin, curves, turn radius, heading change, curve severity, hard curves, curvy roads
Services config	services-config.md	config, api key, retry, timeoutMs, sendUserAgentHeader, tomtom-user-agent, user agent header, isProxyCredentialsMode, LatestRequestResult, language, geopoliticalView, geopoliticalViews, GeopoliticalView, geopolitical view, servesGeopoliticalView, GeopoliticalViewAPI, view sent, label a result, disputed territories, validation, validateRequest, error, SDKError, SDKServiceError, SDKAbortError, ServiceName, error.service, per-call retry, SDKErrorCode, sdkErrorCodes, error code, INVALID_CREDENTIALS, INSUFFICIENT_PERMISSIONS, LIVE_SERVICE_NOT_AVAILABLE, INTERNAL, canRetry, retryable error, 403, forbidden, apiErrorCode, InvalidReferer, privatePreviewAccess, PrivatePreviewAccess, private preview access, request access, RATE_LIMITED, NETWORK_NOT_AVAILABLE, INSECURE_BASE_URL, cancel, cancellation, abort, AbortSignal, AbortController, signal, deadline, timeout, search-as-you-type, createLatestRequest, LatestRequestOptions, LatestRequestSupersede, latest request, stale request, stale response, supersede, on-start, on-answer, answers in order, re-plan while dragging, race, race condition, out of order, debounce
MapLibre direct access	maplibre.md	mapLibreMap, raw maplibre, SDK vs MapLibre, when to use MapLibre directly, controls, markers, popups, MapLibre plugins, addSource, addLayer, removeLayer, geojson, vector tiles, raster, pmtiles, tile source, paint, layout, queryRenderedFeatures, querySourceFeatures, z-order, symbol layer, layer placement, layer order, beforeId, mapStyleLayerIDs, lowestLabel, lowestRoadLine, lowestBuilding, lowestPlaceLabel, poi anchor, draw roads under labels, polygon under roads, moveLayer, text-font, font stack, glyphs, MAP_BOLD_FONT, MAP_REGULAR_FONT, mapFonts, custom layer, CustomLayerInterface, addCustomLayer, CustomLayer, CustomLayerOptions, lowest3D, hitTest, CustomLayerHit, CustomLayerHitTest, clickable 3D objects, InstancedMesh, instancing, buffer ring, ANGLE, Direct3D 11, three.js, threejs, WebGL, raw WebGL, localFrameMatrix, LocalFrameOptions, mercatorMeters, centerLatitude, defaultProjectionData, mainMatrix, getMatrixForModel, map.transform, renderer.resetState, autoClear
Custom GeoJSON module	custom.md	CustomGeoJSONModule, CustomGeoJSONEvents, CustomGeoJSONModuleSerializableConfig, BYOD, bring your own data, custom geojson, customer-authored layers, heatmap layer, symbol layer with custom icon, multi-source module, applyConfig layer diff, per-source events, style-change restoration with own layers, beforeLayerConfig, CustomGeoJSONBeforeLayerConfig, layer placement, mapStyleLayerIDs, polygons under roads, lines under labels, text labels, text-font, MAP_BOLD_FONT, MAP_REGULAR_FONT, customGeoJSONKnobCatalogue, customGeoJSONKnobIds, CustomGeoJSONKnob, CustomGeoJSONKnobId, CustomGeoJSONKnobValueOf, custom GeoJSON knob catalogue, aggregateIntoCells, AggregateIntoCellsOptions, AggregatedCells, CellStatistic, CellGrid, CellGridShape, gridOrigin, cellSizeKM, minCount, median per area, mean per area, statistic per cell, hexagon grid, hexbin, square grid, value per district, weighted heatmap vs value
Map effects plugin	map-effects.md	map-effects, MapEffects, addPass, removePass, MapEffectsPassUniforms, vec3 uniform, vec4 uniform, pass textures, sampler2D, mipmapped, textureLod, MapEffects addLayer, MapEffects removeLayer, MapEffectsLayer, MapEffectsLayerPlacement, effects layer, film grain, split tone, paper texture, watermark, effectKnobCatalogue, setKnob effects, setKnobs effects, updateConfig effects, resetConfig effects, bloom, glow, vignette, tint, fog, fog.color, fog colour, haze colour, edge blur, depth of field, depthOfField, bokeh, defocus, tilt shift, focus band, WebGL pass, glare, glare.only, lens flare, star filter, streaks, street lights, lamp glow, anamorphic, bloom.only, onlyTolerance, bloom scope, scope bloom, BloomScope, glow only the traffic, glow the route, light one module, colour key, styleColorKnobIds, StyleColorKnobGroup, grade, brightness, contrast, saturation, mute the base map, dim the map under data, post-processing, capture, high-DPI, print, preserveDrawingBuffer
Fly-over plugin	flyover.md	flyover, fly-over, RouteFlyover, fly a route, camera along a route, route animation, cinematic camera, follow the route, anchor, anchorForPitch, position on screen, aim ahead, junction framing, terrain clearance, route marker, follow marker, arrow, setMarker, fly once, loop, onArrive, seek, replay a trip, FlyoverCamera, FlyoverAim, FlyoverZoom, FlyoverMarkerConfig
Route dragging plugin	route-dragging.md	route dragging, route-dragging, RouteDragging, RouteDraggingOptions, RouteDraggingPlanner, drag route, drag the route, editable route, drag waypoint, drag stop, move a stop by its pin, insert stop by dragging, pull a stop off the route line, insertFromRouteLines, live re-plan, re-plan while dragging, planIntervalMS, showOnMap, headless, own state, React store, onWaypointsChange, WaypointDrag, WaypointDragKind, onRoutes, answers in order
Landmarks 3D plugin	landmarks-3d.md	landmarks-3d, Landmarks3D, landmarks errors, landmarks 403, landmarks access, withCredentials, ModelsSource, 3D landmarks, Orbis landmarks, GLB tiles, Three.js, fill-extrusion, landmarks3DKnobCatalogue, landmarks-3d/knobs, knob catalogues without three.js, landmark knobs, landmark color/opacity/verticalGradient, landmark texture, landmarks' own colours, landmarkTextureUses, follows 3D buildings and map colours, buildings3D around landmarks, landmarks on terrain, minZoom, maxZoom, ModelsLayer, custom layer, buildLandmarksTileURL, Buildings3D, 3D buildings, facade textures, windows, lit windows, night city, shadows, sun direction, follows the map light (view.light, getMapLight), buildings3DKnobCatalogue, buildingsPresets, facadePatterns, BuildingsLayer, reflective glass, glass reflections, reflections.intensity, labels behind buildings, roadLabels.occluded, pois.occluded, buildings.events, landmarks.events, BuildingHit, hover and click a building or landmark, hover.color, click.color, setBuildingColors, colour buildings by position, setLandmarkColors, getLandmarkColors, colour a building by id, paletteModes, paletteMapColors, walls.palette, roofs.palette, roof colour palette, paletteIntensity, variation, building colour palette, vary building colours
Landmarks 3D: GLSurfaces	gl-surfaces.md	gl-surfaces, GLSurfaces, GLSurfacesConfig, glSurfacesKnobCatalogue, glSurfacesKnobIds, GLSurfacesKnob, GLSurfacesKnobId, GLSurfacesKnobValueOf, surfaceKinds, SurfaceKind, surfaceSeasons, SurfaceSeason, palette, seasons, spring, summer, autumn, winter, snow, autumn colours, 3D trees, trees in buildings' shadows, tree species, tree mix, shareFactor, conifers, poplars, cypresses, stone pines, umbrella trees, bushes, paths through forest, trees covering roads, textures, textured map, land textures, water texture, waves, reflective water, sky reflection, glint, vegetation texture, forest, tree crowns, grass, farmland, field parcels, sand, dunes, rock, asphalt, road texture, glaciers, ice, crevasses, scrub, heath, mud flats, shingle, gravel, paving, built-up ground, car parks, runways, textures on 3D terrain, trees on terrain, wind, wind direction, wind speed, wind.speedFactor, prefers-reduced-motion, WebGL2, custom layer materials, shared light with Buildings3D, view.light, getMapLight
Agent toolkit plugin	agent-toolkit.md	agent, agent-toolkit, createMapAgent, setMapStyling knob ids, setGeopoliticalView, tool error code, LLM, chat, conversational, Vercel AI SDK, ToolLoopAgent, classifier, intent, per-turn scope, scopeSchema, scopePrompt, AnalysableDatasetKind, analyseData, processData, datasets, DatasetKind, DatasetConfig, enabled, datasetMode, ToolEntry, ToolEntryBuilder, ToolState, custom tool, system prompt, BASE_SYSTEM_PROMPT, composeSystemPrompt, SYSTEM_PROMPT_SECTIONS, SystemPromptSection, SystemPromptSectionOverrides, section overrides, systemPromptPrefix, systemPromptSuffix, DEFAULT_TOOLS, MapAgentOptions, BYOD layers, addByodSource, setByodLayers, BYODDataProfile, updateByodDisplay, recallState, updateRoutesDisplay focus, updateRoutesDisplay waypoints, route via, comparedToBest, routeUtils, getTrafficIncidents where schema, getCurrentLocation, createGetCurrentLocationTool, fullPrecision, location precision, executeMaplibreCode, createExecuteMaplibreCodeTool, createClarifyIntentTool, rendersForm, endsTurnOnCall, alwaysActive, getStateDigest, formatStateDigestDiff, StateDigest, onToolExecute, stepProviderOptions, prepareStep, maxHistoryMessages, classifyUserIntent, extractLastUserText, MIN_VIEWPORT_BIAS_ZOOM, monitorAnalysis, getDefaultToolPrompts, TOOLS_BY_DATASET_KIND, loadWorkerLibrarySource, sandbox timeout, allowMainThreadFallback, getCodeExecutionMode, CodeExecutionMode, sandbox CSP, privacy, personal data, GDPR, DPA, data retention

Read ${CLAUDE_SKILL_DIR}/docs/<filename> directly — the path is fixed, so no search step is needed, and ${CLAUDE_SKILL_DIR} resolves wherever this skill is installed. For multi-topic tasks, read several.

---

Base setup

npm i @tomtom-org/maps-sdk

import { TomTomConfig } from '@tomtom-org/maps-sdk/core';

TomTomConfig.instance.put({ apiKey: 'YOUR_API_KEY' });

---

Global conventions

• Coordinates: [longitude, latitude] — longitude first (GeoJSON order)
• Place, route, range, geometry and traffic services return GeoJSON: Place = Feature<Point>, Places = FeatureCollection<Point>; getPlaceDetails returns one Place or undefined, reverseGeocode one Place or the queried point without properties (check properties to narrow), geometryData polygons. Not GeoJSON: getPOICategories, getPOICategoryCodes and getSearchSuggestions
• Map modules are async: await Module.create(map) for data-owned modules (Places, Routing, Geometries, ReachableRanges, CustomGeoJSON, TrafficIncidentDetails, TrafficAreaAnalytics — a new independent instance per call), await Module.get(map) for style-owned ones (BaseMap, POIs, TrafficFlow, TrafficIncidents, Terrain, StylingFoundations — a shared controller)
• geocodeOne() throws if no result — use geocode() when uncertain
• discoverOnePlace() throws if no result — use discoverPlaces() when uncertain
• geocode, geocodeOne, discoverPlaces and discoverOnePlace share one argument shape — places.md § Search → display on map
• Services work in Node.js — no browser or map required
• Map container CSS: The map div AND html, body all need explicit height (height: 100% or 100vh) and margin: 0 — without this the map renders with zero height. Always include a complete HTML + CSS boilerplate in your answer, not just the TypeScript.
• SDK first, MapLibre beneath: map.mapLibreMap is the real MapLibre Map, so any MapLibre API, control or plugin works — but use the SDK feature wherever one exists: it survives setStyle and style upgrades, coordinates events, and follows the map's theme. Your own GeoJSON goes through CustomGeoJSONModule (custom.md), even for one layer; raw addSource/addLayer is for tile overlays. Which SDK feature replaces which raw call: maplibre.md § SDK first.
• Layer placement: MapLibre's beforeId inserts a raw layer below any style layer, but use the mapStyleLayerIDs anchors from @tomtom-org/maps-sdk/map — they are stable across styles; CustomGeoJSONModule takes their key names in beforeLayerConfig. Default lines and polygons to mapStyleLayerIDs.lowestLabel so all labels stay above them (the SDK's own default); points and markers go on top, with no anchor. Anchor table in maplibre.md (raw addLayer) and custom.md (CustomGeoJSONModule specs).
• Provide visible UI feedback for event handlers (toasts, panels, info bars) — not just console.log. Build real, functional UI that the user can see and interact with.

---

Step 2: Confirm before integrating a preview feature

This step covers every SDK feature, whatever it is: a service, a map module, a utility, an agent tool or a plugin. A feature is not generally available when:

• Its doc says so: a Public preview or Private preview callout at the top of the doc or of its section, or "public preview" or "private preview" beside a function, module, tool or plugin name. In node_modules, the package README says so under its intro, and the TSDoc of the class or factory an app starts from links Public Preview or Private Preview.
• It ships in a plugin below 1.0.0: a @tomtom-org/maps-sdk-plugin-* package on a 0.x version is in Public Preview even where its doc says nothing, and in Private Preview where its doc says so.
• It is built on a preview feature: an agent tool that calls a Private Preview service is in Private Preview too.

When the developer asks you to integrate such a feature into their application, so to write or change code that uses it, stop before writing that code. Answering a question about it needs no confirmation. When one request brings in several, such as the agent toolkit with the map-theme plugin it depends on, name them all in one notice, each with its stage.

Show the developer this notice, filled in with the feature, its stage and that stage's terms (https://docs.tomtom.com/legal/public-preview or https://docs.tomtom.com/legal/private-preview), then ask whether to continue and wait for the answer:

<feature> is in <Public | Private> Preview (terms).

• TomTom can change or withdraw it without the notice a generally available feature gets, so code built on it may need changes in a later release.
• Private Preview only: Freemium and Pay As You Grow API keys cannot use it. Your key needs access from TomTom Sales, or the feature fails as its doc describes.

Do you want to continue with it?

• Yes: go on to Step 3. Ask once per feature in a conversation.
• No, or no answer: leave that feature out. Carry on with the rest of the request, or stop if nothing is left.

Step 3: Answer

State the relevant imports, apply the patterns from the doc, note any gotchas. Then write the code. Include complete HTML, CSS, and TypeScript — not just the TypeScript.