maptiler

MapTiler — エージェントスキル

@maptiler/sdk · ドキュメント · Cloud Console · GitHub

MapTiler のすべての製品領域を対象とします。Web SDK、フレームワーク統合、ネイティブモバイル SDK、Cloud REST API、オンプレミスの Server / Engine、ベクタータイルスキーマが含まれます。リファレンスドキュメントは references/ 以下にあり、必要に応じて読み込まれます。厳選されたカタログとして references/INDEX.md を使用してください。

---

1. プラットフォームの範囲とファイル名のプレフィックス規則

プラットフォーム間の混在を避けるため、references/ 内を grep / グロブ検索するときは、次のプレフィックスフィルターを指定してください。

対象プラットフォーム	ファイル名のプレフィックス
Web（コア JS SDK）	sdk-js-*、examples-sdk-js-*
Web フレームワーク（React、Svelte、Vue、Angular）	web-libraries-*、examples-react-*、examples-svelte-*、examples-vuejs-*、examples-angular-*
Web マッピングエンジン（Leaflet、OpenLayers、Cesium、deck.gl）	examples-leaflet-*、examples-openlayers-*、examples-cesium-*、web-libraries-deck-gl*
Android（Kotlin/Java）	mobile-sdks-android-*、examples-android-*
iOS（Swift）	mobile-sdks-ios-*、examples-ios-*
クロスプラットフォームモバイル（Flutter、React Native）	mobile-sdks-flutter-*、mobile-sdks-react-native-*
Cloud REST API	cloud-api-*、cloud-admin-api-*
オンプレミスインフラストラクチャ	on-prem-*
ベクタータイルスキーマ	map-resources-schemas-*
MapLibre スタイル仕様	map-resources-specifications-*

---

2. 共通ルール（すべてのプラットフォームに適用）

A. 変数の漏出をゼロにするポリシー

references/versions.md を参照し、出力する前にすべてのテンプレートプレースホルダー（例：{{site.versions.sdk}}、{{site.url}}）を、具体的なバージョン文字列または絶対パスに置き換えてください。どのような応答でも、生の {{ または }} を絶対に出力しないでください。

B. スタイルの最新化（v2/v3 → v4）

古いマップスタイルは必ずアップグレードしてください。これは Web、モバイル、フォールバック XYZ レイヤー、サービスワーカーのキャッシュリスト、スタイル切り替えロジックに適用されます。

旧スタイル	最新の置き換え先	SDK 定数
basic-v2 / streets-v2-light	base-v4	MapStyle.BASE
basic-v2-dark	base-v4-dark	MapStyle.BASE.DARK
streets-v2	streets-v4	MapStyle.STREETS
outdoor-v2	outdoor-v4	MapStyle.OUTDOOR
satellite / satellite-v2	satellite-v4	MapStyle.SATELLITE
hybrid	hybrid-v4	MapStyle.HYBRID
dataviz-dark	dataviz-v4-dark	MapStyle.DATAVIZ.DARK
topo-v2	topo-v4	MapStyle.TOPO

非推奨の系統に属する URL や定数は絶対に出力しないでください：streets-v2、streets-v2-dark/light、basic-v2*、outdoor-v2*、satellite-v2、hybrid-v2、dataviz-dark、topo-v2。

このルールはスタイルやタイルパスを指定するすべての状況に適用されます。

• モバイルのスタイルエンドポイント（iOS / Android / Flutter / RN の生の style.json URL）：https://api.maptiler.com/maps/streets-v4-dark/style.json?key=YOUR_KEY
• セルフホスト／オンプレミスのフォールバック XYZ レイヤーおよびサービスワーカーのプリキャッシュリスト：/tiles/streets-v4/{z}/{x}/{y}.pbf — /tiles/streets-v2/ は使用しないでください
• スタイル切り替え UI の状態（ダーク／ライト切り替え、スワイプレイヤー、時間帯によるスタイル変更）：最新の v4 ID の間でのみ切り替えてください

C. バージョンの固定

すべての SDK、CDN、依存関係のバージョンは references/versions.md に記載されています。package.json、<script> タグ、Gradle の implementation 文字列、pubspec.yaml の項目を出力する前に、必ず参照してください。

D. プラットフォーム間の座標規則

MapTiler/MapLibre ファミリーのすべての API では [lng, lat] の順序が使われます。連携するプラットフォームではこの順序が異なり、この不一致が最もよくあるバグの原因です。頭の中で変換するのではなく、境界で変換してください。

送信元	規則	該当する場面
MapTiler SDK JS / MapLibre / Mapbox	[lng, lat] 配列	すべてのウェブ SDK コード（center、marker、source coordinates、expressions）
GeoJSON spec	[lng, lat]（または [lng, lat, ele]）	すべての geometry.coordinates の値
MapTiler REST URLs	パス内の {lng},{lat}	/geocoding/{lng},{lat}.json、/elevation/dataset/{lng},{lat}.json、静的マップ /static/{lng},{lat},{zoom}/…
Leaflet	(lat, lng) — 逆順	L.map().setView([lat, lng], z)、L.marker([lat, lng])、L.latLng(lat, lng)
iOS CLLocationCoordinate2D	(latitude:, longitude:) — 構造体レベルで逆順	Apple CoreLocation。MapTiler URL を作成する場合は c.longitude, c.latitude
Android LatLng / LngLat	MapTiler Android SDK では LngLat(lng, lat) を使用します。システムの Location では latitude／longitude が個別のプロパティとして公開されます	システムの型ではなく、SDK の型に合わせてください
MapTiler Geolocation API response	latitude／longitude の個別フィールド（ペアではありません）	SDK 呼び出しに渡す前に [loc.longitude, loc.latitude] を構築します

ルール：Leaflet、iOS CoreLocation、または「個別フィールド」のレスポンスに渡すときは、明示的に順序を入れ替えてください。後続のライブラリも上流の API と同じ規則に従うと決めつけないでください。

E. API キーの取り扱い

• ユーザーがメッセージに実際のものと思われる API キーを貼り付けた場合（「key」、「token」、「apikey」などの語の近くにある UUID 形式またはトークン形式の文字列）は、次のように注意を促してください：「平文で有効なキーと思われるものを共有しています。テストが終わったら、https://cloud.maptiler.com/account/keys/ でキーをローテーションしてください。」出力ではプレースホルダー（YOUR_MAPTILER_API_KEY）を使用してください。
• サービストークンをバックエンドの外に出してはいけません。 service.maptiler.com/v1/… を呼び出すサンプルコードを生成する場合は、トークンを process.env／同等の仕組みから読み込んでください。公開クライアントのコードスニペットに、トークンのように見えるプレースホルダーを埋め込まないでください。
• 本番環境の例では、キーをオリジンで制限してください。制限のないキーではなく、API キーの設定で origins: ["*.example.com"] を推奨してください。

---

3. ウェブ — MapTiler SDK JS

MapLibre をそのまま使わず MapTiler SDK を使う理由

必ず @maptiler/sdk からインポートし、maplibre-gl から直接インポートしないでください。 SDK は MapLibre のすべてを再エクスポートし、さらに次の機能を追加します。

• config.apiKey — API キーを一元管理し、セッションベースの課金を有効にします
• MapStyle enum — 常に最新のスタイル ID を使用できます。スタイル URL をハードコードしないでください
• helpers.* — ポリライン、ポリゴン、ポイント、ヒートマップを1行で作成できます（クラスタリング、カラースケール、GPX/KML に対応）
• 組み込みの geocoding、geolocation、elevation、staticMaps、coordinates、data、math モジュール
• terrain: true — コンストラクターのフラグ1つで3D地形を表示します
• projection: 'globe' — halo と space の大気効果を備えた地球儀表示
• コンストラクターレベルのコントロール（navigationControl: true、geolocateControl: true、…）
• MapLibre を拡張した完全な TypeScript 型

MapLibre プラグインとの互換性は維持されています。SDK の Map は MapLibre の Map を継承しています。

インストール

npm install @maptiler/sdk

CSS は別途インポートする必要があります。

import '@maptiler/sdk/dist/maptiler-sdk.css';

API キー

偽のキーをハードコードしないでください。 ユーザーに尋ねるか、https://cloud.maptiler.com/account/keys/ を案内してください。フレームワークの環境変数の規則は次のとおりです。

ツール	環境変数
Vite	VITE_MAPTILER_API_KEY
Next.js	NEXT_PUBLIC_MAPTILER_API_KEY
CRA	REACT_APP_MAPTILER_API_KEY

import * as maptilersdk from '@maptiler/sdk';
maptilersdk.config.apiKey = import.meta.env.VITE_MAPTILER_API_KEY;

最小限のマップ

const map = new maptilersdk.Map({
  container: 'map',                       // element or ID
  style: maptilersdk.MapStyle.STREETS,    // enum — always latest
  center: [14.4178, 50.1167],             // [lng, lat] — NOT [lat, lng]!
  zoom: 12,
});

重要：コンテナーには明示的なサイズ（例：height: 100vh）が必要です。指定しないとマップは表示されません。

コンストラクターオプション（最もよく使われるもの）

new maptilersdk.Map({
  container, style, center, zoom,
  pitch: 0, bearing: 0,            // 0–85 / rotation
  projection: 'mercator',          // or 'globe'
  terrain: false, terrainExaggeration: 1,
  hash: true,                      // sync viewport to URL
  language: maptilersdk.Language.AUTO,
  cooperativeGestures: true,
  geolocate: maptilersdk.GeolocationType.POINT,
  navigationControl: true, geolocateControl: true,
  scaleControl: true, terrainControl: false,
  fullscreenControl: false, projectionControl: false,
  minimap: { containerStyle: { width: '200px', height: '150px' } },  // or `true` for defaults
});

navigationControl、geolocateControl、scaleControl、terrainControl、fullscreenControl、projectionControl、minimap、geolocate には、初期化後の addControl よりもコンストラクターフラグを使用してください。各オプションには、true、コーナーを示す文字列（'top-right'）、または設定オブジェクトを指定できます。addControl(new MaplibreThing(), 'top-right') は、サードパーティープラグインが必要な場合、または初期化後に変更する場合にのみ使用してください。

マップスタイル（全15種類のリファレンススタイル）

スタイル	用途	バリアント
MapStyle.STREETS	詳細な道路地図	.DARK、.PASTEL
MapStyle.SATELLITE	美しい衛星地図	.DARK
MapStyle.HYBRID	地図情報を重ねた美しい衛星地図	.DARK
MapStyle.OUTDOOR	ハイキングやスポーツ向けの地図	.DARK
MapStyle.WINTER	冬のアクティビティ向けの地図	.DARK
MapStyle.TOPO	汎用地形図	.DARK、.PASTEL、.TOPOGRAPHIQUE
MapStyle.DATAVIZ	シンプルなデータ可視化用地図	.DARK、.LIGHT
MapStyle.BASE	見やすい汎用地図	.DARK、.LIGHT
MapStyle.BRIGHT	コンテキスト表示やナビゲーション向けの明るい地図	.DARK、.LIGHT、.PASTEL
MapStyle.BACKDROP	モノクロのコンテキスト用地図	.DARK、.LIGHT
MapStyle.AQUARELLE	芸術的な水彩地図	.DARK、.VIVID
MapStyle.LANDSCAPE	明るい陰影起伏図	.DARK、.VIVID
MapStyle.OCEAN	海底地形図	.DARK
MapStyle.OPENSTREETMAP	豊富な情報を備えた、見慣れたOSMコミュニティスタイル	.DARK
MapStyle.TONER	コントラストの強いモノクロ地図	.LITE

プロキシベースの定数（MapStyle.STREETS）を使用し、URLをハードコードしないでください。存在しないバリアントを指定した場合、プロキシは.DEFAULTにフォールバックするため、スペルミスがあってもベーススタイルがエラーなく表示されます。コンパイル時のエラーは発生しません。

権威あるリファレンス（説明、メソッド、バリアントの解決ルール）：references/sdk-js-map-styles.md。

言語

maptilersdk.config.primaryLanguage = maptilersdk.Language.ENGLISH;
map.setLanguage(maptilersdk.Language.FRENCH);     // runtime switch

特別な値：Language.AUTO（ブラウザー）、Language.LOCAL、Language.VISITOR。

---

4. Web — よく使うレシピ

// Marker + popup
new maptilersdk.Marker({ color: '#FF0000' })
  .setLngLat([14.4178, 50.1167])
  .setPopup(new maptilersdk.Popup().setHTML('<h3>Prague</h3>'))
  .addTo(map);

// Geocoding (forward / reverse) — features[].geometry.coordinates is [lng, lat]
await maptilersdk.geocoding.forward('Prague', { limit: 5, proximity: [14.4178, 50.1167] });
await maptilersdk.geocoding.reverse([14.4178, 50.1167]);

// Camera animation
map.flyTo({ center: [14.4178, 50.1167], zoom: 15, pitch: 60, duration: 3000 });

// Static map URL
maptilersdk.staticMaps.centered([14.4178, 50.1167], 12,
  { hiDPI: true, width: 800, height: 600, style: maptilersdk.MapStyle.OUTDOOR });

ベクターレイヤーヘルパー（helpers.add*）

最も一般的なレイヤータイプを1行で作成できます。すべて同じ形式を受け取ります：{ data, beforeId, … }。data には、GeoJSON、URL（GeoJSON / GPX / KML）、またはMapTilerデータセットUUIDを指定できます。

ヘルパー	主なオプション
addPolyline	lineColor、lineWidth、outline
addPolygon	fillColor、fillOpacity、outlineColor
addPoint	pointColor、pointRadius、cluster、showLabel
addHeatmap	colorRamp（ColorRamp.*）、property、radius、opacity

maptilersdk.helpers.addPoint(map, {
  data: pointsGeoJSON, pointColor: '#FF0000', pointRadius: 8,
  cluster: true, showLabel: true, beforeId: 'waterway-label',
});

3D地形／グローブ — 単一フラグのコンストラクター

// 3D terrain
new maptilersdk.Map({ container: 'map', style: maptilersdk.MapStyle.OUTDOOR,
  terrain: true, terrainExaggeration: 1.5, terrainControl: true, pitch: 60 });

// Globe projection
new maptilersdk.Map({ container: 'map', style: maptilersdk.MapStyle.SATELLITE,
  projection: 'globe', halo: true, space: true, center: [0, 20], zoom: 1.5 });

ヘルパーとオプション型の全リファレンス：references/sdk-js-map.md。トピックごとの実行可能なサンプル：examples-sdk-js-*.md を検索してください（マーカー、ジオコーディング、クラスタリング、ヒートマップ、地形、グローブ、天気など）。

---

5. Webフレームワーク

React / Next.js

import { useEffect, useRef } from 'react';
import * as maptilersdk from '@maptiler/sdk';
import '@maptiler/sdk/dist/maptiler-sdk.css';

maptilersdk.config.apiKey = import.meta.env.VITE_MAPTILER_API_KEY;

export default function MapComponent() {
  const containerRef = useRef(null);
  const mapRef = useRef(null);

  useEffect(() => {
    if (mapRef.current) return;                              // Strict-Mode guard
    mapRef.current = new maptilersdk.Map({
      container: containerRef.current,
      style: maptilersdk.MapStyle.STREETS,
      center: [14.4178, 50.1167], zoom: 12,
    });
    return () => { mapRef.current?.remove(); mapRef.current = null; };
  }, []);

  return <div ref={containerRef} style={{ width: '100%', height: '400px' }} />;
}

Next.js App Router："use client"; を追加し、NEXT_PUBLIC_MAPTILER_API_KEY を使用してください。SSRページでは、dynamic(() => import('./Map'), { ssr: false }) を使用します。

Vue / Svelte / Angular

Reactと同じパターンです。マウントフック（onMounted / onMount / ngOnInit）内でマップを初期化し、アンマウントフック（onUnmounted / onDestroy / ngOnDestroy）内で map.remove() を呼び出します。また、リアクティブな状態を条件にマップの作成を制御しないでください。各フレームワークの完全なコード例：web-libraries-vue.md · web-libraries-svelte.md · web-libraries-angular.md。

フレームワークのライフサイクルルール（重要）

1. WebGL のクリーンアップ：React の useEffect、Vue の onMounted／onUnmounted、Angular の ngOnInit／ngOnDestroy、Svelte の onMount／onDestroy におけるすべてのマップインスタンスは、破棄時に 必ず map.remove() を呼び出し、参照を null にしてください。
2. マップの作成は厳密に 1 回だけ実行します：初期化フックの依存配列にリアクティブな状態を入れないでください。状態が変わるたびにキャンバスが破棄されて再作成され、中心、ズーム、動的オブジェクトが失われます。
3. 動的な更新には分離したフックを使います：SDK の更新メソッド（map.setStyle、map.flyTo、map.setLayoutProperty）を呼び出し、再初期化はしないでください。
4. イベントハンドラー内の古いクロージャ：click／draw.create リスナーで最新の React 状態が必要な場合は、useRef（const stateRef = useRef(state); stateRef.current = state;）に保存し、stateRef.current を通じて読み取ってください。依存配列にその状態を追加しないでください。

ライフサイクルの詳細：web-libraries-react.md。

---

6. CDN／単一ファイル／プレイグラウンド

versions.md に記載された固定バージョンを使用してください。latest や古いビルドは使用しないでください。

<script src="https://cdn.maptiler.com/maptiler-sdk-js/v4.0.2/maptiler-sdk.umd.min.js"></script>
<link href="https://cdn.maptiler.com/maptiler-sdk-js/v4.0.2/maptiler-sdk.css" rel="stylesheet" />

その他、よく使われる固定バージョン：

• Leaflet プラグイン：https://cdn.maptiler.com/maptiler-leaflet-maptilersdk/v4.1.0/maptiler-leaflet-maptilersdk.js
• ol-mapbox-style：https://cdn.jsdelivr.net/npm/[email protected]/dist/olms.js
• CesiumJS：1.141.0（スクリプト＋/Widgets/widgets.css）

ブラウザー ESM：<script type="module"> またはインポートマップを使用する場合は、UMD ビルドではなく .mjs ビルド（maptiler-sdk.mjs）を 必ず 使用してください。UMD から名前付き ES インポートを行うと、コンソールエラーが発生します。

---

7. ベクターレイヤー、スキーマ、データ駆動型スタイリング

スキーマの検証（必須）

スタイルルール、フィルター、ペイント／レイアウト式を書く前に、タイルセットのソースを特定し、そのスキーマリファレンスを確認してください。source-layer ID、フィーチャープロパティのキー（class、subclass、ele、height など）、ペイントフィールドを決して推測しないでください。

OMT → Planet v4 の移行時の注意点。 旧 OpenMapTiles スキーマでは、道路、鉄道、航空、フェリーのフィーチャーがすべて 1 つの transportation レイヤーにまとめられています。Planet v4 ではこれらが road、railway、aviation、aviation_line、ferry、aerialway という個別のトップレベルレイヤーに分割されています。Mapbox／MapLibre のスタイルを移植する場合や、2024 年以前のチュートリアルに従う場合、レイヤー名 transportation は解決されません。よくある名称変更は次のとおりです。

OMT（旧）	Planet v4（現行）
transportation（class: motorway/primary/.../residential）	road（class: motorway/trunk/primary/secondary/tertiary/minor/service/...）。residential クラスはありません。minor または service を使用してください
transportation_name	road_label
（なし — まとめて収録）	個別のレイヤーとして railway、aviation、ferry、aerialway
place	country_label、city_label、island_label、continent_label（階層が分割）

ユーザープロンプトで transportation、place などの OMT 時代のレイヤー名が指定されている場合、壊れたフィルターを黙って生成するのではなく、名称変更を明示してください。

スキーマ	リファレンス
Planet v4（最新版）	map-resources-schemas-planet-v4.md
OpenMapTiles Planet	map-resources-schemas-omt-planet.md
Planet Lite	map-resources-schemas-planet-lite.md
建物	map-resources-schemas-buildings.md
等高線／アウトドア／海洋	等高線、アウトドア、海洋
土地被覆／地形／地籍	土地被覆、地形、地籍
スタイル仕様（レイヤー／ソース／式／ルート）	レイヤー、ソース、式、ルート

Buildings タイルセット — 常に優先（優先順位ルール）

専用の buildings タイルセットは、base-v4／streets-v4 に組み込まれた建物データよりも大幅に充実しています。3D 押し出し、ファサードの着色、建物ラベル、入口、またはフィーチャーごとのインタラクションには、必ずこれを使用してください。

項目	標準（maptiler_planet_v4）	専用（buildings）
高さフィールド	render_height、render_min_height	height、height_min
色	—	facade_color、roof_color
形状	—	roof_shape
ラベル	—	building_label（名称、ISO 639 翻訳）
入口	—	building_entrance
一意の ID	False	True（z14+）— setFeatureState で使用可能

// MapTiler SDK JS auto-injects the API key from config.apiKey — do NOT append ?key= manually.
map.addSource('buildings', {
  type: 'vector',
  url: 'https://api.maptiler.com/tiles/buildings/tiles.json',
});

// Facade color with fallback
'fill-extrusion-color': ['coalesce', ['get', 'facade_color'], 'hsl(44, 14%, 79%)']

SDK の外部（生の MapLibre GL JS、モバイルネイティブの style.json の取得、サーバー側リクエスト）では、URL に ?key=YOUR_MAPTILER_API_KEY を追加してください。自動挿入は行われません。

重要なフィールドの対応関係：標準では render_height／render_min_height、専用タイルセットでは height／height_min を使用します。これらを混在させると、描画に失敗してもエラーが表示されません。

SDK のガードレール — ColorRamp の誤生成

JS SDK の ColorRamp クラスには .getExpression() も .getCSSGradientDirection() もありません。スタイルを構築するには、ColorRamp.getRawColorStops() を反復処理し、標準的な MapLibre の補間式を手動で組み立ててください。

DDS の詳細

complex-dds-expressions-guide.md — データ駆動型スタイリングに使える、組み合わせ可能なパターンです。

---

8. クラウド REST API

すべての SDK API モジュールは config.apiKey を自動的に使用します。JavaScript 以外のコンテキストについては、REST ドキュメントを参照してください。

モジュール	用途	主なメソッド／リファレンス
geocoding	場所の検索、逆ジオコーディング	forward()、reverse()、batch() — cloud-api-geocoding.md
geolocation	IP アドレスによる訪問者の位置情報	info() — cloud-api-geolocation.md
elevation	標高の検索	at()、batch()、fromLineString() — cloud-api-elevation.md
staticMaps	静的地図画像	centered()、bounded()、automatic() — cloud-api-static-maps.md
coordinates	CRS／EPSG の変換	search()、transform() — cloud-api-coordinates.md
data	MapTiler データセット	get(uuid) — cloud-api-data.md
weather	風、気温、気圧、レーダー	cloud-api-weather.md
maps（ベクター／ラスター）	タイルセット、スタイル	cloud-api-maps.md
tiles	生のタイルエンドポイント	cloud-api-tiles.md
fonts／images／ogc	その他	fonts、images、ogc
管理（タイルセット、アップロード、キー、分析）	アカウント管理	cloud-admin-api-tilesets.md、api-keys、analytics
認証	キーとトークンの違い、リファラーのルール	cloud-api-authentication.md

// IP geolocation
const loc = await maptilersdk.geolocation.info();

// Elevation — returns [lng, lat, elevationMeters]
const point = await maptilersdk.elevation.at([14.4178, 50.1167]);

---

9. ネイティブモバイル SDK

プラットフォーム	概要	API リファレンス
iOS（Swift）	mobile-sdks-ios.md	mobile-sdks-ios-api-classes.md
Android（Kotlin）	mobile-sdks-android.md	mobile-sdks-android-api-com-maptiler-maptilersdk-map.md
Flutter	mobile-sdks-flutter.md	mobile-sdks-flutter-*.md を検索
React Native	mobile-sdks-react-native.md	mobile-sdks-react-native-*.md を検索

iOS — 最小限の地図（SwiftUI）

import SwiftUI
import MapTilerSDK

struct ContentView: View {
    @State private var map = MTMapView(options: MTMapOptions(zoom: 2.0))

    var body: some View {
        MTMapViewContainer(map: map) {}
            .referenceStyle(.streets)
            .styleVariant(.defaultVariant)
            .task { await MTConfig.shared.setAPIKey("YOUR_MAPTILER_API_KEY") }
    }
}

MTConfig.shared.setAPIKey(_:) は async であり、地図を初期化する前に必ず呼び出す必要があります。Swift 6 では、Task または .task モディファイアから呼び出してください。UIKit の代替方法：viewDidLoad 内で MTMapView(frame:options:referenceStyle:) を宣言し、pinToSuperviewEdges() を呼び出します。

Android — 最小限の地図（Jetpack Compose）

// build.gradle.kts (app):  implementation("com.maptiler:maptiler-sdk-kotlin:<version>")
// AndroidManifest.xml:    <uses-permission android:name="android.permission.INTERNET" />
//                         android:hardwareAccelerated="true"

import com.maptiler.maptilersdk.config.MTConfig
import com.maptiler.maptilersdk.map.*

@Composable
fun MapScreen(context: Context) {
    MTConfig.apiKey = "YOUR_MAPTILER_API_KEY"        // set before first map
    val controller = remember { MTMapViewController(context) }
    MTMapView(
        referenceStyle = MTMapReferenceStyle.STREETS,
        options = MTMapOptions(),
        controller = controller,
        modifier = Modifier.fillMaxSize(),
    )
}

XML／View 版：レイアウトで MTMapViewClassic を使用し、onCreate で mapView.initialize(referenceStyle, options, controller, styleVariant = null) を呼び出します。

実行可能なサンプル：examples-ios-*.md、examples-android-*.md を検索してください。raw style.json の URL 規則（UIKit、XML／View、カスタムアセットパス）については、§ 2B を参照してください。

---

10. オンプレミス — サーバーとエンジン

セルフホスト環境へのデプロイやオフラインでのタイル生成については、以下をご覧ください。

トピック	リファレンス
MapTiler Server — はじめに	on-prem-server-getting-started.md
データのホスティング	on-prem-server-hosting-data.md
仮想タイルセット	on-prem-server-virtual-tilesets.md
サーバーでの地図スタイリング	on-prem-server-map-styling.md
オンプレミスでのジオコーディング	on-prem-server-geocoding.md
Engine CLI — はじめに	on-prem-engine-getting-started-cli.md
Engine — 入力／出力オプション	入力、出力

フォールバック XYZ レイヤーとサービスワーカーキャッシュにおけるタイルパスの規則については、§ 2B をご覧ください。

---

11. 重要な注意点（クロスプラットフォーム）

問題	解決方法
地図が表示されない（Web）	コンテナーに明示的な高さが必要です（100vh または position: absolute; inset: 0）
マーカー／地図の中心が別の大陸に表示される	座標は[lng, lat]であり、[lat, lng]ではありません（例：プラハは[14.4178, 50.1167]であり、[50.1167, 14.4178]ではありません）
setStyle()の後にレイヤーが消える	map.once('styledata', …)内で再追加します
データがラベルに重なる	beforeId: 'waterway-label'を使用します
多数のポイントで動作が遅い	cluster: true（ヘルパーまたはソース）を有効にします
SPAでメモリーリークが発生する	アンマウント時に必ずmap.remove()を呼び出し、refをnullにします
maplibre-glを個別にインポートしている	@maptiler/sdkを使用します。MapLibreが含まれており、拡張されています
状態が変わるたびに地図が再作成される（React）	useEffectの依存配列を空にし、再初期化するのではなくsetXメソッドで変更します
ハンドラーで古いクロージャーが使われる	状態のミラーとしてuseRefを使用し、.currentを読み取ります
ブラウザーでESMスクリプトエラーが発生する	UMDではなく.mjsビルドを<script type="module">で使用します
モバイルで3D建物の表示が平面的になる	標準スタイルが読み込まれています。専用のbuildingsソースを追加します
モバイルでスタイルが404になる	エンドポイントをstreets-v2系からstreets-v4系に更新します
ジオコーディングキーで403が発生する	キー設定でリファラー／許可リストを確認します（cloud-api-authentication.md）
{{ }}が出力に漏れる	出力する前にversions.mdを参照して解決します
MapTiler Engineが起動しない	-o output_dir（または-o file.mbtiles）の出力先は既に存在していてはいけません。削除するか、新しいパスを指定します。-f／--forceフラグはありません
iOSアプリですべてのタイルが403になる	MTConfig.shared.setAPIKey(_:)はasyncですが、awaitなしで呼び出されています。最初の地図ビューが表示される前に、Task { … }内またはSwiftUIの.task修飾子内で設定します
mapbox-gl-drawのカーソル／ヒットテストが動作しない	プラグインのCSSは.mapboxgl-canvasを対象としていますが、MapTiler／MapLibreでは.maplibregl-canvasが使われます。フォールバックルールとして.maplibregl-canvas.mouse-add { cursor: crosshair }および.maplibregl-canvas.mouse-drag { cursor: grabbing }を追加します
ユーザーがチャットに有効なAPIキーを貼り付ける	そのキーを問題として報告し（Cloud Consoleでローテーションします）、自身の出力ではYOUR_MAPTILER_API_KEYプレースホルダーを使用します。実際のキーをそのまま返してはいけません
addControl(new XControl())パターンをでっち上げる	多くのMapTilerコントロールはコンストラクターのフラグとして利用できます：minimap、navigationControl、geolocateControl、scaleControl、terrainControl、fullscreenControl、projectionControl。まずフラグを使い、addControlはサードパーティープラグインまたは初期化後の変更にのみ使用します
SDKクラス名を幻覚する（MinimapControl、GeocodingBarなど）	クラス名を出力する前に、references/sdk-js-controls.mdとsdk-js-map.mdを照合します。正式なミニマップクラスはMaptilerMinimapControl（Maptiler接頭辞）であり、いずれにしてもコンストラクターオプションを使う方法が推奨されます
GeoSplatsのレンダリングに失敗する／モデルが空白になる	GeoSplats SDKにはWebGPUのサポートが必須です。ブラウザーの互換性（navigator.gpu）を必ず確認し、明確なUIフォールバックエラーオーバーレイを表示します

---

12. エコシステムパッケージ

パッケージ	目的
@maptiler/geosplats	高性能な3D Gaussian Splatting（WebGPUを活用）
@maptiler/geocoding-control	住所検索バーのUI
@maptiler/weather	風、気温、気圧、レーダーの各レイヤー（60 fps）
@maptiler/3d	glTF／GLB 3Dモデルの配置
@maptiler/elevation-profile	ルートの標高グラフ
@maptiler/marker-layout	重なりを防ぐDOMマーカーオーバーレイ
@maptiler/ar	拡張現実による3D地形
@maptiler/client	ヘッドレスAPIクライアント（Node.js／ブラウザー、地図なし）

---

13. リソース

• MapTiler Cloud Console
• MapTiler SDK JS Docs · Examples · NPM · GitHub
• MapTiler iOS SDK Docs · Android SDK Docs
• MapLibre Style Specification
• フレームワークのドキュメント：React · Vue · Svelte · Angular · Vite

---

14. リファレンスカタログ

重要度の高いリファレンスドキュメントを厳選したインデックスは、references/INDEX.md にあります。そこに記載されていないファイルは、§ 1 のプレフィックス規則で検索してください。