Skip to main content

Mapbox 公式ドキュメント読み中メモ

公式ドキュメント読んだときのメモ（ポイント箇条書きと、今後用のメモ）

サンプルは 公式から そのまま引用したもの（試すとき用）

読みかけメモ​

  • 2025/07/13
    • 全体をざっと通読（詳細までは踏み込まず）
    • TODO: Camera、User Interaction、Style Layers などは実際に手を動かしながら理解を深める
    • Animation や Offline 関連は今は優先度低め、必要となったときに読む

Guides​

リンク​

Style​

  • Mapbox Standard
    • mapbox://styles/mapbox/standard
  • Mapbox Standard Satellite
  • Mapbox-designed styles
  • custom style ← Mapbox Studio で作る

Style は、レイヤのようなもので、
アプリからは Style を読み込んでマップを表示する。というもの

standard style のサンプル
swift
import UIKit
import MapboxMaps

class ViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad()

        let mapView = MapView(frame: view.bounds)
        mapView.mapboxMap.mapStyle = MapStyle(uri: StyleURI(rawValue: "mapbox://styles/mapbox/standard"))

        mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        view.addSubview(mapView)
    }
}

ツール群​

  • MapboxStatic.swift : マップのサムネイル画像がほしい場合にだけ使うもの
  • Mapbox Studio : カスタムの Style を作るためのもの

Telemetry Opt Out​

「ユーザーのプライバシー保護」と「Mapbox 利用規約の遵守」の観点から、Telemetry（匿名データ収集）に対してユーザーが拒否できる仕組みを必ず提供せよ、ということを書いているようだ

Get Started​

リンク​

最初にやること​

  • Part 1 : アカウント作って public token をプロジェクトに設定
    • Info.plist に MBXAccessToken のキーとして設定
  • Part 2 : プロジェクトにパッケージ追加
    • ここで .netrc の設定が要りそうに思ったが、ここでは書いてなかったか
  • Part 3 : アプリに表示
    • 載っているサンプルだと、地球儀が出てくる
    • もうちょい先で、「現在地」、「アノテーション(ピン)」、「カメラ」辺りの項を読むと必要なことはできそうか
最小のサンプル (SwiftUI)
swift
import SwiftUI
import MapboxMaps

struct ContentView: View {
    var body: some View {
        let center = CLLocationCoordinate2D(latitude: 39.5, longitude: -98.0)
        Map(initialViewport: .camera(center: center, zoom: 2, bearing: 0, pitch: 0))
            .ignoresSafeArea()
    }
}
最小のサンプル (UIKit)
swift
import UIKit
import MapboxMaps

class ViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad()

        let mapView = MapView(frame: view.bounds)
        let cameraOptions = CameraOptions(center:
            CLLocationCoordinate2D(latitude: 39.5, longitude: -98.0),
            zoom: 2, bearing: 0, pitch: 0)
        mapView.mapboxMap.setCamera(to: cameraOptions)
        mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]

        view.addSubview(mapView)
    }
}

User Location​

リンク​

ここで書かれていること​

  • iOS での 位置情報取得のための事前設定
  • Mapbox での 位置情報取得関連のクラス等

Info.plist 関連​

  • Info.plist
    • NSLocationWhenInUseUsageDescription
    • LocationAccuracyAuthorizationDescription
    • NSLocationAlwaysAndWhenInUseUsageDescription ← 必要の場合
Info.plist 設定例
Info.plist
...
<key>NSLocationWhenInUseUsageDescription</key>
<string>Your precise location is used to calculate turn-by-turn directions, show your location on the map, and help improve the map.</string>
...
<key>NSLocationTemporaryUsageDescriptionDictionary</key>
<dict>
  <key>LocationAccuracyAuthorizationDescription</key>
  <string>Please enable precise location. Turn-by-turn directions only work when precise location data is available.</string>
</dict>

最小サンプル​

最小のサンプル (UIKit)
swift
class ViewController: UIViewController {
    // This controller's initialization has been omitted in this code snippet
    var mapView: MapView!
    // A location provider that you use to customize location settings.
    let locationProvider = AppleLocationProvider()

    override func viewDidLoad() {
        super.viewDidLoad()
        mapView = MapView()
        // Override the default location provider with the custom one.
        mapView.location.override(provider: locationProvider)
        locationProvider.delegate = self
    }

    // Method that will be called as a result of the delegate below
    func requestPermissionsButtonTapped() {
        locationProvider.requestTemporaryFullAccuracyAuthorization(withPurposeKey: "CustomKey")
    }
}

extension ViewController: AppleLocationProviderDelegate {
    func appleLocationProvider(
        _ locationProvider: MapboxMaps.AppleLocationProvider,
        didChangeAccuracyAuthorization accuracyAuthorization: CLAccuracyAuthorization
    ) {
        if accuracyAuthorization == .reducedAccuracy {
         // Perform an action in response to the new change in accuracy
        }
    }
}

Custom location providers​

これは 現在地取得のロジックをカスタマイズしたい場合の話か。
いまのところ使うことなさそう。

  • LocaitonManager : iOS 標準の LocationManager? の wrapper？
  • HeadingProvider : 方位を提供するプロトコル
  • MapReader : ズームや座標を取るためのもの
    • eraseToSignal() ← これは何をするもの？
      • Apple の Combine (Publisher/Signalモデル) という仕組みに似せた、リアクティブなAPIのようだ
      • → よく分からん。使う機会あったらちゃんとやる
  • Puck2D, Puck3D : 現在地を表示する UI コンポーネント
    • Location Puck : 現在地を表す青い点のこと (ホッケーの「パック」と呼んでいるようだ)

方向表示するアイコンを自作のキャラクターかなんかにしたい場合に使うか。
ランニングアプリやゲーム的に使いたい場合に便利ということかな。

Markers and Annotations​

リンク​

1. Annotation​

ピン(画像)を描画するサンプル

SwiftUI

swift
Map {
  let someCoordinate = CLLocationCoordinate2D(latitude: 40.7128, longitude: -74.0060)
  PointAnnotation(coordinate: someCoordinate)
    .image(.init(image: UIImage(named: "dest-pin")!, name: "dest-pin"))
}

UIKit

swift
// Initialize a point annotation with a New York City CLLocationCoordinate2D
let someCoordinate = CLLocationCoordinate2D(latitude: 40.7128, longitude: -74.0060)
var pointAnnotation = PointAnnotation(coordinate: someCoordinate)

// Make the annotation show a red pin
pointAnnotation.image = .init(image: UIImage(named: "dest-pin")!, name: "dest-pin")

// Create the PointAnnotationManager, which will be responsible for handling this annotation
let pointAnnotationManager = mapView.annotations.makePointAnnotationManager()

// Add the annotation to the manager in order to render it on the map.
pointAnnotationManager.annotations = [pointAnnotation]
ピン(円)を描画するサンプル

SwiftUI

swift
Map {
  let circleCoordinate = CLLocationCoordinate2DMake(40.7128, -74.0060)
  CircleAnnotation(centerCoordinate: circleCoordinate)
    .circleColor(.red)
}

UIKit

swift
// Define a geographic coordinate.
let circleCoordinate = CLLocationCoordinate2DMake(40.7128, -74.0060)

// Create the circle annotation.
var circleAnnotation = CircleAnnotation(centerCoordinate: circleCoordinate)
circleAnnotation.circleColor = StyleColor(.red)

// Create the CircleAnnotationManager, which will be responsible for handling this annotation
let circleAnnotationManager = mapView.annotations.makeCircleAnnotationManager()

// Add the annotation to the manager.
circleAnnotationManager.annotations = [circleAnnotation]
線 (polyline)を描画するサンプル

SwiftUI

swift
Map {
  // Define two or more geographic coordinates to connect with a line.
  // Line from New York City, NY to Washington, D.C.
  let lineCoordinates = [
      CLLocationCoordinate2DMake(40.7128, -74.0060),
      CLLocationCoordinate2DMake(38.9072, -77.0369)
  ]

  PolylineAnnotation(lineCoordinates: lineCoordinates)
    .lineColor(.red)
}

UIKit

swift
// Define two or more geographic coordinates to connect with a line.
// Line from New York City, NY to Washington, D.C.
let lineCoordinates = [
    CLLocationCoordinate2DMake(40.7128, -74.0060),
    CLLocationCoordinate2DMake(38.9072, -77.0369)
]
// Create the line annotation.
var lineAnnotation = PolylineAnnotation(lineCoordinates: lineCoordinates)
lineAnnotation.lineColor = StyleColor(.red)

// Create the PolylineAnnotationManager, which will be responsible for handling this annotation
let lineAnnotationManager = mapView.annotations.makePolylineAnnotationManager()

// Add the annotation to the manager.
lineAnnotationManager.annotations = [lineAnnotation]

ポリゴンのサンプルもある。略

2. View Annotation​

リンク​

書いてあること​

  • Annotation に View を出すときの例
  • 重ね順など

フキダシみたいなもの、画像などを出したいとき用か

3. Style Layers​

リンク​

書いてあること​

  • Style Layer を コードから作りたい場合のサンプル（へのリンク）か
  • Style Layer には制約があるが、Mapbox Expressions というのを使うと、ある程度カスタマイズ出来るということか

TODO​

  • TODO: この方法で図形を描画するよりも、Mapbox Styles であらかじめ定義したものがあれば、そちらのほうが早そうか。比較する

↓

比較するまでもなく、以下のような使い分けするのがきれいか

  • 1 : 以下のようなのは、上記サンプルを参考にする
    • ユーザ作成の経路
    • お気に入りのピン
    • 経路登録のための仮のピン
  • 2 : 以下のようなのは、Style Layer であらかじめロードしておく
    • 提供したいピン : 管理者としてアップする用
    • 路線図 : レイヤとして重ねる用
    • 都道府県の境界 : ハイライト用

Style Layer は、全ユーザ共有のものなら Mapbox Studio で作成するのが良さそう。
アプリ内で作ることもできるが、描画オブジェクトが大量になった場合に使うようなイメージ可

Styles​

リンク​

書いてあること​

  • Styles について詳しく買いてありそう
  • TODO: Mapbox Studio 触って詰まるようなことがあったら読んでおこう。
    • Expression, Declarative Map Styling.. 辺りが活用出来ると、柔軟なものになる？

こんな感じ？

  • Style（スタイル）：地図のルック＆フィール全体（背景・道路・ラベル・建物など全部）
  • Layer（レイヤ）：Style を構成する個々の要素（建物だけ、道路だけ、など）
  • Source（ソース）：レイヤが参照するデータ（GeoJSON、タイルセットなど）
  • Expression：Style や Layer のプロパティを柔軟に制御するための「式」構文（JSONベース）

SwiftUI​

リンク​

何が書いてある​

  • SwiftUI への対応状況と、チュートリアル/サンプル
  • 対応していないものは UIKit でやる

必要なとこだけ試したら良さそうだ

Camera and Animations​

リンク​

書いてあること​

  • 1 : Camera ← 表示範囲(表示位置、ズームなど)を指定する
  • 2 : Animations ← Google Earth みたいなパンしてくアニメーションなどを想定
  • 3 : Viewport ← カーナビみたいな 表示切替を想定

→ という感じか

→ とすると、

  • TODO: ★★★ Camera (1) は必須なので、まずはここを最優先で理解する。読んで試す

User Interaction​

リンク​

TODO​

ピンをタップしたときの動作のカスタマイズ(フキダシを出したり)などは、 Map Content Gestures (3) 辺りを読めば良い？

以下のようなことを気にして読む

  • 任意の位置をタップで場所名を取得といったことができる？
    • 不可の場合に MapKit 任せにすることが出来る？

Geofecing​

リンク​

https://docs.mapbox.com/ios/maps/guides/geofencing/

前提​

  • Geofencing とは？
    • 特定のエリア（地理的な境界）にユーザーが入ったり出たりしたことを検出する仕組み

→ ああ、近くに「鉄棒のある公園あるよ」って通知してくれるようなイメージか・・？
→ そうだとするとバックグラウンド動作が必須になりそうな
→ その前に、最大20しか同時に監視できない(iOS制限)そうなので、場所移動するたびに更新するイメージか。難しそう

TODO​

  • 応用編だと思うので、その機能をつけたくなったらよく読むか・・・

Offline​

オフラインマップのためのもの？ 応用編と思うので、いったんスキップ

Cache Management​

  • これも応用編と思うので、いったんスキップ
  • またはキャッシュのための怪しい動作があってクリアしたいときなどに読もう

Debugging and Profiling​

  • これも応用編と思うので、いったんスキップ
  • または、デバッグで必要になったら読もう

Work with visionOS​

  • 自分が作るものには要らないけど、Zwift のようなバーチャルライドに組み込まれたら良さそう (ありそう)

Pricing​

リンク​

メモ​

  • Map 表示は MAU (Monthly Active Users) に基づいて課金されるということ
    • これは 同じユーザが何回使ったところでその月内はカウントアップはされないということ
  • Search API, Direction API などはリクエスト回数ベースでの課金 (ここで言及されているかは分からなかったが、どっかで読んだ)
    • このへんは ちょっと怖いので、MapKit 使うか
    • Map/Annotation の描画はパフォーマンスにおいて明らかな利点があるので採用するが、
    • Search API, Direction API は、MapKit で足りるかもしれないので・・