Meet Apple Maps Server APIs

ハイライト

Apple Maps はこれまでクライアント中心のエコシステムでした。iOS では MapKit、Web では MapKit JS。しかしサーバー側は空白でした。バックエンドでジオコーディングや周辺店舗検索をしたい場合、Google Maps API を自前で呼ぶか、クライアント側で処理して大量のネットワークリクエストを許容するしかありませんでした。

---

主要内容

店舗ロケーター機能を作るとき、過小評価されがちなのは「カードを組み立てる」ステップです。クライアントはまずビジネスサーバーから店舗住所を取得し、MapKit または MapKit JS で住所を座標に変換し、ユーザーから各店舗までの距離を計算し、各レスポンスを連絡先カードにマージします。ネットワークが良好なら待ち時間が増えるだけですが、セルラーの遅延が高いと、独立したリクエストごとに失敗や不完全なレスポンスの確率が上がります。

この Session は問題をコミック書店ロケーターに絞ります。画面に必要なのは3枚のカード：店舗住所、ユーザーの現在地、距離。サーバー側の地図 API がなければ、クライアントはビジネスバックエンドと Apple Maps サービスを行き来し、ローカルで結果をマージする必要があります。ユーザーにはスピナーが見え、デバイスは帯域と電力を消費します。

Apple は WWDC22 で Apple Maps Server APIs を補完しました。4つのサーバー機能を提供します。Geocoding、Reverse Geocoding、Search、Estimated Time of Arrival（ETA）。ビジネスサーバーがゲートウェイとして機能し、住所解決、ETA 計算、ビジネスデータの統合を行い、UI に最適な結果を一度に返せます。

この変更後、クライアントは自社サーバーへのリクエストが1回で済みます。バックエンドはコミック書店の住所を Geocode API に渡し、座標を取得して ETA API に渡し、距離と店舗営業時間などの自社データをマージします。MapKit、MapKit JS、Apple Maps Server APIs が同一の Apple Maps stack を形成します。クライアントは表示能力を保持し、繰り返し・キャッシュ可能・集約しやすい作業はサーバーへ移ります。

---

詳細

4つのサーバー API が4種類の地図問題を解決

（01:01）Apple Maps Server APIs は初めて4つの API を含みます。Geocoding、Reverse Geocoding、Search、ETA。住所解決から到着時間推定までの基本的な地図ワークフローをカバーします。

Geocoding: 住所 -> latitude / longitude
Reverse Geocoding: latitude / longitude -> 住所
Search: 検索文字列 -> business / point of interest などの地点
ETA: origin + destination -> 各 destination の estimated time of arrival / distanceMeters

キーポイント:

• Geocoding は店舗住所を latitude と longitude に変換。以降の計算はこの2値に依存。
• Reverse Geocoding は逆方向。ユーザーが選択した座標を住所に戻すのに適している。
• Search はユーザーがクエリ文字列を入力し、店舗、POI などの地点を発見できる。
• ETA は origin と destination を受け取り、各目的地の ETA を返す。Session の例は distanceMeters で店舗までの距離を計算。

クライアントの複数リクエストをバックエンドゲートウェイに集約

（03:41）Apple Maps Server APIs がない場合、クライアントは店舗住所を取得した後も地図機能を呼び続ける必要があります。Session は、クライアントとバックエンド間の chattiness がパフォーマンスと拡張性に影響すると明言。高遅延のセルラーでは独立リクエストが接続断や incomplete requests の原因にもなります。

旧フロー:
Client -> Business Server: 店舗住所リストをリクエスト
Business Server -> Client: 住所を返却
Client -> Apple Maps service: 各住所ごとに地図関連リクエスト
Client: 複数レスポンスを待ち、ローカルでマージ

新フロー:
Client -> Business Server: 表示可能な店舗リストをリクエスト
Business Server -> Apple Maps Server APIs: Geocoding / ETA などのリクエスト
Business Server: 地図レスポンスと自社店舗情報をマージ
Business Server -> Client: UI が直接使えるデータを返却

キーポイント:

• 新フローではクライアントが複数の地図リクエストを直接編成しない。
• ビジネスサーバーは重複する住所クエリを「バックエンドで一度だけ」実行でき、デバイス間の重複リクエストを削減。
• バックエンドは UI に近い結果を返す。クライアントのネットワーク待ちとレスポンスマージが減る。
• これが Session の「reduce network calls」と「power efficient」の由来。帯域と処理がユーザーデバイスからサーバーへ移る。

店舗ロケーター：まず Geocode、次に ETA

（06:16）例では Geocoding と ETA でユーザーから店舗までの距離を算出。まずコミック書店の住所を URL encode し、Geocode API の query parameter にする。レスポンスに latitude と longitude が含まれる。ユーザー住所も同様に処理。

1. URL encode comic book store address
2. Call Geocode API with the encoded address as a query parameter
3. Read latitude and longitude from the response
4. Repeat the same process for the customer address
5. Pass origin and destination query parameters to ETA API
6. Read distanceMeters from the ETA response

キーポイント:

• Session は具体的な endpoint パスを示さないため、ここは呼び出し順序として保持。URL は捏造しない。
• Geocode API の出力は ETA API の入力。店舗座標とユーザー座標がそれぞれ destination と origin になる。
• ETA API は最大10個の destination を指定可能。複数店舗を一度に比較するのに適している。
• 例は1つの destination のみ。レスポンスの ETA も1つ。実際のロケーターは複数店舗を同じ計算にバッチできる。
• ビジネスサーバーは結果と自社情報（例：営業時間）をマージできる。

認証：Maps auth token を30分の access token に交換

（08:29）すべての Apple Maps Server APIs に認証が必要。MapKit JS と同じ仕組み。開発者アカウントから private key をダウンロードし、JWT 形式の Maps auth token を生成し、token API を呼んで Maps access token に交換。

Private key from developer account
  -> generate Maps auth token (JWT)
  -> call token API with Maps auth token in a header
  -> receive Maps access token (JWT)
  -> use Maps access token in Apple Maps Server API calls
  -> refresh every 30 minutes

キーポイント:

• Maps auth token と Maps access token は別物。
• Maps auth token は access token 交換用。それ自体が以降のすべての API 呼び出しの認可を意味しない。
• Maps access token は JWT。レスポンスに expiry、issuedAt、expiresInSeconds などのフィールド。
• Session は access token を30分ごとに更新すると明言。バックエンドが更新を担当し、private key をクライアントに配布してはならない。

クォータと 429：失敗パスも設計する

（10:47）Apple Maps Server APIs は1日25,000回の service calls クォータを共有し、MapKit JS の service usage と共有。Maps developer dashboard は server API usage を Services に分類。

Daily quota: 25,000 service calls
Shared with: MapKit JS service usage
Quota exceeded: HTTP 429 Too Many Requests
Retry strategy: exponential backoff, not a tight retry loop

キーポイント:

• 1日のクォータを超えると新しい service calls は拒否され、HTTP 429 が返る。
• 異常トラフィックでも 429 が発生しうる。コードやインフラのバグによる過剰リクエストなど。
• 429 受信後はループでリトライしない。Session は exponential backoff でリトライ間隔を徐々に広げることを推奨。
• 店舗ロケーターのバックエンドは 429 時に降格可能なデータを返すべき。例：住所と営業時間のみ表示し、距離は後から補完。

---

重要ポイント

• やること：店舗ロケーターの住所解決と距離計算をバックエンドへ移す。
  価値：Session のコミック書店例は、バックエンドが Geocode API と ETA API で地図レスポンスをマージでき、クライアントは1回のビジネスレスポンスだけを受け取れることを示す。
  始め方：バックエンドで店舗住所とユーザー住所を URL encode し Geocoding を呼ぶ。座標取得後に ETA を呼び、distanceMeters を店舗カードデータに書き込む。

• やること：地図検索結果にビジネスデータの overlay を追加する。
  価値：Search API は店舗と POI を返し、Session は自社データを overlay できると述べる。
  始め方：バックエンドで Search 結果と自社 DB の営業時間、在庫、会員特典をマッチングし、MapKit または MapKit JS に返す。

• やること：よくある住所クエリにサーバー側キャッシュを実装する。
  価値：Apple は、異なるユーザーデバイスが同じ住所を繰り返し lookup すると重複リクエストと帯域の無駄になると特に指摘。
  始め方：正規化した住所をキャッシュキーにし、Geocoding の latitude / longitude をキャッシュ。ETA はユーザー origin に依存するためリアルタイム呼び出しを維持。

• やること：Apple Maps Server APIs 用のクォータダッシュボードと降格戦略を用意する。
  価値：サーバー API は1日25,000回のクォータを MapKit JS と共有。超過すると 429。
  始め方：Maps developer dashboard の Services 使用量を定期確認。バックエンドで 429 を捕捉し exponential backoff を使い、距離なしの店舗リストをフォールバックとして返す。

• やること：token 更新をバックエンドの基盤機能としてカプセル化する。
  価値：Maps access token は30分ごとに期限切れ。複数の地図 API が同一の認証フローを共有。
  始め方：バックエンドに private key を保存。サーバーでのみ Maps auth token を生成。token API で access token に交換し、expiresInSeconds 前に更新。

---

関連セッション

• What’s new in MapKit — クライアント側の地図表示とインタラクションの更新。Apple Maps Server APIs と合わせて完全な地図アーキテクチャを構成。
• Meet WeatherKit — 同じ Maps & Location のサービス型データ API。位置、ルート、店舗シナリオと組み合わせ可能。
• Reduce networking delays for a more responsive app — ネットワーク遅延が応答性に与える影響の深掘り。クライアントリクエスト数を減らすことが体験改善につながる理由の補足。
• Q&A: Maps technologies — MapKit、MapKit JS、Apple Maps Server APIs に関するエンジニアリング Q&A の入口。