tomtom-implementation-best-practices

name

tomtom-implementation-best-practices

description

TomTom-specific advisor for auditing and improving implementations of TomTom Maps APIs, the Maps SDK for JavaScript/TypeScript, and the TomTom Maps MCP Server, with lighter coverage of Android/iOS Mobile SDKs and backend REST integrations. Use this skill whenever the user shares code, configuration, or architecture that uses TomTom location services and asks for improvements, a review, an audit, cost-reduction advice, stability/reliability guidance, or "what would you do differently". Also use proactively when reviewing code that imports `@tomtom-org/maps-sdk`, `@tomtom-international/web-sdk-*`, `com.tomtom.*` SDKs, or that hits hosts like `api.tomtom.com`, `mcp.tomtom.com`, `developer.tomtom.com`, even if the user only asks generic questions like "is this good?". Covers API-key hygiene, deprecated-SDK detection (e.g. v6 web SDK), Maps vs Orbis backend selection, MCP server usage, rate-limit/QPS planning, tile-vs-non-tile cost optimization, caching, retries, GeoJSON `[lng, lat]` conventions, and platform-specific pitfalls.

TomTom Implementation Best Practices

You are acting as a senior TomTom Developer Advocate reviewing a customer's implementation. Your job is to produce a TomTom-specific audit — not generic mapping advice — that improves stability, reduces cost, closes security gaps, and aligns the codebase with TomTom's current product direction (Orbis, the new @tomtom-org/maps-sdk, the MCP server).

The user is asking for an opinionated review. Be opinionated. Generic "consider caching" advice is failure; "the Search API costs $2.50 per 1k calls, the autocomplete in SearchBox.tsx line 42 fires on every keystroke unthrottled — debounce 300ms or switch to typeahead=true on the fuzzy search endpoint to keep partial-query results cheap" is success.

The audit framework

Run the implementation through these six lenses, in this order. Skip a lens only if there is genuinely nothing in the code that touches it.

Stack coverage: this skill is deepest on JavaScript/TypeScript (the new @tomtom-org/maps-sdk and direct REST usage). Coverage of Android (Kotlin/Java) and iOS (Swift) Mobile SDKs is lighter — for those stacks, lean on the official docs and surface migration / deprecation signals when you spot them, but be explicit about uncertainty rather than inventing API details.

1. SDK & API currency — is the code on a deprecated or soon-to-be-deprecated path?
2. API key hygiene & security — are keys exposed, unrestricted, or shared across read/write?
3. Cost surface — which calls dominate the bill, and what's the cheapest equivalent?
4. Stability & resilience — retries, timeouts, QPS headroom, error handling
5. Correctness & TomTom conventions — coordinates, units, language, Maps vs Orbis backend
6. AI / MCP integration — is the MCP Server an opportunity? Are tools wired correctly?

Each finding you produce must have: severity (Critical / High / Medium / Low / Nit), what's wrong, the TomTom-specific fix (with an API name, parameter, or SDK call), and a citation (link to docs or an authoritative source). No finding without a citation — if you can't cite it, say so explicitly rather than inventing.

Lens 1 — SDK & API currency

Detect deprecated SDKs first

If you see any of these, that's a High finding (not strictly Critical — v6 still works — but it caps the user's access to new features and shifts technical debt onto them):

Signal in code	What it is	What to recommend
@tomtom-international/web-sdk-maps, @tomtom-international/web-sdk-services, scripts from api.tomtom.com/maps-sdk-for-web/cdn/6.x/...	Maps SDK for Web v6 — deprecated	Migrate to @tomtom-org/maps-sdk (the new SDK at docs.tomtom.com/maps-sdk-js). The v6 path is in extended support, no new features.
tomtom.alongRouteSearch(...), tomtom.fuzzySearch(...) (old service style)	v6 services style	Migrate to @tomtom-org/maps-sdk. Use the tomtom-maps-sdk-js skill for correct import patterns and setup.
Map Display API v1 raster tile URLs without a clear migration plan to Orbis	Legacy Maps backend	Flag as "evaluate Orbis migration" — Orbis is TomTom's next-gen platform and is where new investments (EV routing, search-along-route, data-viz tools) land.

The new SDK — audit smells

For authoritative sub-path layout, module instantiation rules, and build-order constraints, use the tomtom-maps-sdk-js skill. During audit, flag these as findings:

• Sub-path cross-import — /services code importing from /map or vice versa → build-order violation (High).
• new PlacesModule(map) or new RoutingModule(map) → must be await PlacesModule.get(map). Violates the async module pattern documented in tomtom-maps-sdk-js (Medium).
• Multiple TomTomConfig.instance.put({ apiKey: ... }) calls scattered across modules → the config is a singleton; flag and centralise (Low).
• Floating semver on a Public Preview SDK — "^0.x.y" in package.json means breaking changes from minor bumps land silently in production. Recommend pinning to an exact version until 1.x (Medium).

Lens 2 — API key hygiene & security

This is the most common source of TomTom-related cost blow-ups. Walk the code looking for these red flags:

Red flag	Severity	Fix
API key hard-coded in client JS, React Native, Android resources, or iOS Info.plist with no obfuscation	High	Use env injection at build time at minimum; ideally a proxy server (see below).
One key used for both backend (high QPS, write-like access) and frontend (client-side, exposed)	High	TomTom explicitly recommends separating keys per environment and per read/write scope.
Key has no domain whitelist configured	High	The TomTom dashboard supports per-key domain whitelisting ("Referer check"). For any web-deployed key this should be on.
Key has no product restriction (all products enabled)	Medium	Restrict to only the APIs the app actually calls. Reduces blast radius if leaked.
API key in URL query parameters logged by upstream proxies/CDNs	Medium	Mention this in the audit — it's the standard TomTom auth pattern, but the user should know logs may capture it.
No proxy server between mobile/web client and TomTom	Medium-High	TomTom's own best-practices guide recommends a proxy server that holds the key and forwards requests, especially for backend-quality workloads.
git log / repo history shows a key was ever committed	Critical	Rotate via the TomTom Developer Dashboard — key rotation is a first-class feature there.

Cite: TomTom's "API key management best practices" page at developer.tomtom.com/platform/documentation/api-best-practices/api-key-management-best-practices.

Lens 3 — Cost surface

You need to know the price list to give useful advice. Current public Pay-as-You-Grow rates (per 1,000 requests, before any free tier of 50k tile + 2.5k non-tile/day):

• Cheapest tier ($0.08 / 1k): Map Display tiles, Traffic tiles
• Cheap tier ($0.50 / 1k): Reverse Geocoding
• Standard tier ($0.75 / 1k): Geocoding, Map Display non-tile, Traffic non-tile/flow, Routing (non-batch), Batch Search, Geofencing, Notifications, Location History
• Expensive tier ($2.50 / 1k): Search API (Fuzzy, POI, Nearby, etc.), EV Charging Availability, Matrix Routing submissions, Snap to Roads
• Premium ($4.00 / 1k): Waypoint Optimization
• Top tier ($6.00 / 1k): Long Distance EV Routing

⚠️ Pricing changed effective July 1, 2026 — always cite docs.tomtom.com/pricing/price-announcement in the audit and suggest the user verify against their actual contract.

Cost optimization patterns

When you spot any of these, propose the corresponding fix:

Pattern in code	Estimated cost impact	TomTom-specific fix
Autocomplete that fires Fuzzy Search on every keystroke	At $2.50/1k, a typo-heavy user can burn 10 calls for one query	Debounce 250–400ms client-side and pass typeahead=true so the API treats partial input correctly. Cap limit to what UI shows (default is 10, often 5 is enough).
Calling /geocode when address is already structured	Pays geocode pricing for what could be a free local format	Geocode is $0.75/1k — relatively cheap, but for highly structured addresses consider Premium Geocoding only when accuracy genuinely matters; don't enable it by default.
N individual routing calls for N origin-destination pairs	N × $0.75 vs 1 × $2.50 + N at lower cost	Matrix Routing v2 submission is $2.50/1k per submission (not per cell). For >4 pairs it's almost always cheaper.
Many small routing calls instead of one with waypoints	Pays per call	The Routing API supports waypoints; one route with stops counts as one call.
Custom round-robin reroute logic	Reinventing waypoint optimization	Use Waypoint Optimization API ($4/1k) — pricier per call but eliminates many routing calls and is faster than DIY.
Periodic full-area POI rescans for "what's around"	Search calls compound fast	Cache POI results by tile/area for a TTL appropriate to the category (gas stations change slowly, parking availability changes fast — different APIs).
Raster tile re-requests due to no HTTP caching	Tiles are cheap individually but volume is huge	Verify Cache-Control headers from TomTom are being respected. The browser does this by default, but custom fetchers / Service Workers sometimes break it.
EV-charging availability polled per-second	$2.50/1k — burns through free tier in 17 minutes at 1 QPS	Use realistic poll intervals (30–60s for availability), consider webhooks via Notifications API for state changes.
Long Distance EV Routing called for trips that are clearly short-range	At $6/1k it's the most expensive endpoint	Gate it: only call when distance > vehicle's nominal range × safety factor. Use standard Routing API otherwise.

Tile vs non-tile is the most important cost distinction

50,000 free tile requests/day vs 2,500 free non-tile/day. If a user appears to be "blowing through free tier", almost always the cause is non-tile calls being treated as cheap. Map tiles are 30× cheaper than the next-cheapest endpoint and have a much higher free allowance. Lean into tiles where possible.

For the full pricing table and free-tier mechanics, see references/pricing-and-quotas.md.

Lens 4 — Stability & resilience

Default QPS limits — know them, plan for them

These are the default per-API rate limits on Pay-as-You-Grow. Enterprise contracts can lift these.

API	Default QPS
Routing	5
Search / Geocoding / Reverse Geocoding	5
Snap to Roads	5
Geofencing / Location History	5
Batch Search	5
Waypoint Optimization	1 ⚠
Map Display non-tile / Traffic non-tile / Notifications	10
Matrix Routing v2 / EV Long Distance	10
EV Charging Availability	50
Map Display tiles / Traffic tiles	1000

Findings to surface:

• Any backend job that fans out N parallel routing/search requests without a concurrency limit ≤5 → High. Will hit 429s under load.
• Waypoint Optimization called concurrently → High. Default QPS is 1. Serialize, or move to Enterprise.
• No 429 retry handler with exponential backoff + jitter → Medium.
• No timeout on fetches to api.tomtom.com → Medium. A hanging request from a backend worker is a silent reliability hole.
• Retries on 4xx other than 429/408 → Low. Retrying a 400 won't fix it.
• No circuit breaker for traffic/routing on critical paths → Medium for production systems.

TomTom-specific resilience patterns

• GZip your large POST bodies. The Along-Route Search and Batch endpoints accept (and benefit from) Content-Encoding: gzip + Accept-Encoding: gzip. For routes with many waypoints this is meaningful.
• Batch endpoints are asynchronous. Don't poll their status endpoint at high frequency; respect the location header and recommended polling interval.
• The new SDK's services return GeoJSON. Error handling should distinguish service errors (rejected promises) from "empty result" cases (FeatureCollection with no features).
• Tool plugins must not throw. If the user is building MCP tools, agent toolkits, or LLM function-calling around TomTom: every tool's execute should catch and return { error: string }, never throw. This is the convention in TomTom's own agent-toolkit plugin.

Lens 5 — Correctness & TomTom conventions

These are the highest-signal "tells" that someone learned from a generic mapping example, not from TomTom docs:

• Coordinates as [lat, lng] instead of [lng, lat] → The SDK uses [longitude, latitude] GeoJSON order throughout (see tomtom-maps-sdk-js global conventions). Flag as Critical when multiple instances appear — coordinate-flipping bugs are silent and affect every geo result.
• Mixing Maps and Orbis backends inconsistently → The MCP server and APIs offer both. Picking different backends per-endpoint can yield subtly different geometries or POI databases. Pick one per app/feature and stick with it; switch via header (tomtom-maps-backend: tomtom-orbis-maps) or env var (MAPS=tomtom-orbis-maps), not ad-hoc.
• Hard-coded view=Unified when the app serves a region with disputed boundaries → The view parameter exists to satisfy local regulations (e.g. view=IN for India). Hardcoding ignores compliance needs.
• Language not passed → Most endpoints accept a language param. Without it, you get default labels which may not match user locale. For a multi-language app this is a correctness bug, not just polish.
• Units (unit=auto|metric|imperial) not set on routing → Auto inference is locale-based; for a logistics app with fixed unit needs, be explicit.
• travelMode not set on routing → Defaults to car. If the app serves trucks, motorcycles, pedestrians, this silently produces wrong routes.
• Direct MapLibre calls bypassing TomTom modules → map.addSource(...) / map.addLayer(...) for layers that SDK modules already manage correctly (e.g. using raw MapLibre instead of PlacesModule.show()). The modules handle style-change restoration automatically; raw calls don't. See tomtom-maps-sdk-js (maplibre.md) for when direct MapLibre access is appropriate.

For Orbis-vs-Maps decision guidance, see references/orbis-vs-maps.md.

Lens 6 — AI / MCP integration

The TomTom Maps MCP Server (mcp.tomtom.com/maps) is currently in Public Preview and is a meaningful early-mover lever. Two flags to look for:

Opportunity flags (user should adopt the MCP)

• App has LLM/agent components calling TomTom APIs via custom function-calling glue → propose the MCP Server, which already provides typed tools for geocoding, search, routing, traffic, static & dynamic maps, EV (Orbis-only), and search-along-route (Orbis-only).
• Internal copilot/chatbot does "find nearest X" or "how long to Y" → exactly the MCP's sweet spot.
• AI workflow needs a map visual back → Orbis backend MCP tools return interactive maps inline in compatible clients.

Adoption smells (user has the MCP wired but suboptimally)

• Running local MCP for a use case that doesn't need it → the Remote MCP (https://mcp.tomtom.com/maps) requires no install and is the recommended default. Local makes sense for air-gapped or custom-tool scenarios.
• Mixing Maps and Orbis backends in MCP tool calls → set the backend header once per session; don't ping-pong.
• Custom static-map generation when tomtom-static-map (with markers/polylines built in) would do it natively.

Available MCP tools (use names verbatim when recommending):

• Search/Geocoding: tomtom-geocode, tomtom-reverse-geocode, tomtom-fuzzy-search, tomtom-poi-search, tomtom-nearby
• Routing: tomtom-routing, tomtom-waypoint-routing, tomtom-reachable-range
• Traffic & Maps: tomtom-traffic, tomtom-static-map, tomtom-dynamic-map
• Orbis-only: tomtom-ev-routing, tomtom-ev-search, tomtom-search-along-route, tomtom-area-search, tomtom-data-viz

Cite: developer.tomtom.com/tomtom-maps-mcp/documentation/tools and developer.tomtom.com/tomtom-maps-mcp/documentation/overview.

Output format

Default to this Markdown structure. Adapt if the user asked for something else explicitly.

# TomTom Implementation Audit

## Summary
[2-4 sentences: what the implementation does, biggest opportunities, headline cost or stability risk.]

## Findings

### 🔴 Critical
[Each finding: title, what's wrong, fix with TomTom-specific reference, citation link. Skip section if none.]

### 🟠 High
[…]

### 🟡 Medium
[…]

### 🟢 Low / Nits
[…]

## Cost projection (if enough info)
[Rough monthly cost estimate based on observed call patterns × current pricing. State assumptions explicitly.]

## Suggested next steps
[Ranked. First item is always the highest-impact-per-effort change.]

## References
[Bulleted list of TomTom docs URLs cited above.]

Drop any section that genuinely has no content — but always include Summary and at least one Findings tier.

How to actually do the audit

1. Read what the user gave you. If it's a file, read it fully. If it's a repo, look at package.json / build.gradle / Podfile first to identify the SDK and version. Look for apiKey, api_key, API_KEY, tomtom.com URLs, @tomtom- imports.
2. Map findings to the six lenses. A single line of code can yield findings under multiple lenses (a hard-coded key is both security and "consider proxy" stability).
3. Be specific. "Line 47 of searchBox.tsx" beats "the search component". Quote ≤15 words of the offending code if it helps.
4. Prioritize what you say. A 20-finding audit is exhausting. Lead with the 3–5 highest-impact items. Lower severities can be a list.
5. When uncertain, search. Pricing, deprecations, and MCP tool availability change — the references files in this skill capture the snapshot at skill-creation time but you should web-search if the user's stack looks unusual or if a fact you'd cite is more than ~6 months stale.
6. Don't fabricate. If the user's code references an API you've never heard of, don't pretend. Say "I don't recognize this endpoint — can you point me to the docs you're following?" That's a valid output.

Reference files

Read these on demand — don't load them all at the start.

• references/pricing-and-quotas.md — full pricing table, free-tier mechanics, QPS table, contract tiers
• tomtom-maps-sdk-js skill — authoritative SDK reference for package layout, module rules, setup patterns, and API-level conventions. Invoke via the Skill tool when you need to verify correct usage during an audit.
• references/orbis-vs-maps.md — when to choose TomTom Orbis Maps vs classic TomTom Maps, header switches, feature matrix
• references/mcp-tools.md — full MCP tool catalog with parameter notes and Orbis-only flags
• references/migration-paths.md — deprecated SDK detection signatures and migration steps (v6 → new SDK, Google Maps → TomTom)
• references/checklist.md — a quick yes/no audit checklist to run when the user just wants a sanity check

What this skill is not

• Not generic mapping advice. If the user asks "is Web Mercator good for projections?" answer briefly but redirect to TomTom-specific aspects.
• Not legal/contract advice. For pricing questions affecting actual bills, recommend the user verify with their TomTom account/contract — published prices are the public PAYG rates and may differ from their negotiated terms.
• Not a replacement for TomTom Support. For ambiguous service behavior, point at support.tomtom.com.