Place Markers コンポーネント

これは Pro コンポーネントであり、Essentials コンポーネントとは異なる方法で課金されます。詳細については、概要をご覧ください。

Place Markers コンポーネントを使用すると、地図上に場所の重要な情報を直接表示する、カスタマイズ可能な地図の注釈を作成できます。場所の評価、場所のタイプ、営業中または閉店中のステータス、価格帯、カスタム テキスト（AI 生成ラベルや旅程番号など）などのコンテンツを表示できます。これにより、ユーザーは詳細なプレイスカードをタップしなくても、より多くの情報を含む地図を探索できます。

PlaceMarker は、Google Maps SDK for Android を使用して Marker インスタンスにデータを入力するために使用できるデータを提供します。Places SDK for Android で PlaceMarker を使用すると、マップの Maps SDK for Android の Marker と 1 対 1 で対応します。

PlaceMarker ごとに 1 つのマーカー アイコンとオプションのマーカー テキストを表示できます。

使用可能なアイコンは次のとおりです。

• Type: 場所のタイプ。
• None: アイコンなし。

使用できるテキスト マーカーは次のとおりです。

• Rating: 評価スコア。
• PriceRange: 価格帯（例: $10 ～ 20）。
• OpenStatus: ビジネスが営業中か休業中か。
• Custom: カスタム テキスト（「人気」など）。

プレイス ID（PlaceId）、リソース名（ResourceName）、地理座標（Coordinates）を使用して場所を参照します。

表示と帰属表示の要件

Places UI キットの地図マーカーが表示される場合、マーカーが単独で表示されてはなりません。インタラクティブで、クリックまたはタップすると関連する Place Details コンポーネントまたはライトボックスが開き、必要な Google ブランド、投稿者の帰属表示、問題の報告フローを提供する必要があります。

スペースが限られている場合のシナリオについては、写真とクチコミの帰属に関する要件をご覧ください。

Place Marker の例

Jetpack Compose @Composable 関数を提供することで、View-to-Compose ラッパーのオーバーヘッドを排除し、テーマの不一致の問題を回避します。

マーカーの基本的なカスタマイズ

次のコード例は、デフォルトのマーカーの三角形の吹き出しの先端を非表示にするなど、基本的なプレースマーカーのカスタマイズを示しています。

Kotlin

import androidx.compose.runtime.Composable
import com.google.android.libraries.places.compose.PlaceMarker
import com.google.android.libraries.places.compose.marker.MarkerIcon
import com.google.android.libraries.places.compose.marker.MarkerText
import com.google.android.libraries.places.compose.PlaceReference

@Composable
fun DefaultMarker() {
    PlaceMarker(
        reference = PlaceReference.PlaceId("PLACE_ID"),
        icon = MarkerIcon.None,
        beakPresence = false, // remove beak
    )
}

@Composable
fun RatingMarker() {
    PlaceMarker(
        reference = PlaceReference.PlaceId("PLACE_ID"),
        icon = MarkerIcon.None,
        text = MarkerText.Rating
    )
}

@Composable
fun TypeAndRatingMarker() {
    PlaceMarker(
        reference = PlaceReference.PlaceId("PLACE_ID"),
        icon = MarkerIcon.Type,
        text = MarkerText.Rating

    )
}

@Composable
fun PriceRangeMarker() {
    PlaceMarker(
        reference = PlaceReference.ResourceName("places/PLACE_RESOURCE_NAME"),
        icon = MarkerIcon.None,
        text = MarkerText.PriceRange
    )
}

@Composable
fun OpenStatusMarker() {
   PlaceMarker(
       reference = PlaceReference.Coordinates(latitude = 37.7749, longitude = -122.4194),
        icon = MarkerIcon.None,
        text = MarkerText.OpenStatus
   )
}

@Composable
fun CustomTextMarker() {
    PlaceMarker(
        reference = PlaceReference.PlaceId("PLACE_ID"),
        icon = MarkerIcon.None,
        // Custom text accepts a String to display a number (e.g. "3") or text (e.g. "NEW")
        text = MarkerText.Custom("NEW")
    )
}

クリック リスナーを作成する

スタンドアロン マーカーがタップされたときにカスタム アクションをトリガーする onClick コールバックを指定できます。ただし、マーカーが地図上にレンダリングされると（たとえば MarkerComposable 内）、タップイベントは地図によってインターセプトされます。この場合、マーカーのハンドラではなく、MarkerComposable の onClick ハンドラを使用する必要があります。

次のコード例は、MarkerComposable の onClick ハンドラの使用方法を示しています。

Kotlin

import android.util.Log
import androidx.compose.runtime.Composable
import com.google.android.libraries.places.compose.PlaceMarker
import com.google.android.libraries.places.compose.marker.MarkerIcon
import com.google.android.libraries.places.compose.PlaceReference


/**
 * PlaceMarker used outside of a map (e.g. in a list, bottom sheet, or custom overlay).
 *
 * There is no host component that provides a default click behavior here, so PlaceMarker's own
 * `onClick` is the only way for a developer to react to a tap. This is why `onClick` must stay
 * on the PlaceMarker API.
 */
@Composable
fun ClickableMarkerWithCustomConfig() {
   PlaceMarker(
       reference = PlaceReference.PlaceId("PLACE_ID"),
       icon = MarkerIcon.Type,
       
       onClick = { place ->
           openPlaceCard(place.id) // developer might want to open the place card
           Log.i("PlacesMarker", "Marker was tapped by user!")
       }
   )
}

/**
 * PlaceMarker used as the content of a MarkerComposable on a GoogleMap.
 *
 * MarkerComposable does NOT add PlaceMarker to the touch-input hierarchy: it snapshots the
 * composable into a bitmap and hands that bitmap to the Maps renderer as the marker icon. The
 * rendered marker is a map object, not a Compose node, so:
 *
 *   - PlaceMarker's own `onClick` would never be invoked here (no touch events ever reach it).
 *   - The tap is delivered by the Maps SDK to MarkerComposable's `onClick`, which is the only
 *     click entry point on a map.
 *
 * Accordingly, the state-based `PlaceMarker(state = ...)` overload used below deliberately does
 * not expose an `onClick` parameter, so the correct handler is the only one available.
 */
@Composable
fun PlaceMarkerOnMap(markerState: PlaceMarkerState) {
  GoogleMap(
    modifier = Modifier.fillMaxSize(),
    cameraPositionState = rememberCameraPositionState(),
  ) {
    markerState.location?.let { position ->
      MarkerComposable(
        state = rememberUpdatedMarkerState(position = position),
        // this is the click handler for the map use case.
        onClick = {
          markerState.place?.let { place -> openPlaceCard(place.id) }
          true // consume the event
        },
      ) {
        PlaceMarker(state = markerState)
      }
    }
  }
}

読み込みステータスとコールバックを処理する

次のコード例は、レンダリング エラーまたはデータ欠落エラーを処理するコールバックを提供する方法を示しています。

Kotlin

import android.util.Log
import androidx.compose.runtime.Composable
import com.google.android.libraries.places.compose.PlaceMarker
import com.google.android.libraries.places.compose.marker.MarkerIcon
import com.google.android.libraries.places.compose.PlaceReference

@Composable
fun StatusHandlingMarker() {
    PlaceMarker(
        reference = PlaceReference.PlaceId("PLACE_ID"),
        icon = MarkerIcon.Type,
        // Triggered when attribute data is successfully fetched and the marker is rendered.
        // Returns a minimal Place object with ID, location (LatLng), and viewport fields set.
        onMarkerLoaded = { place ->
            Log.i("PlacesMarker", "Marker successfully loaded for place ID: ${place.id}")
        },
        // Triggered when data fetching fails or required attribute data is missing for the place.
        // Returns an optional Place object and an Exception describing the root cause.
        onMarkerLoadFailed = { place, exception ->
            Log.e("PlacesMarker", "Failed to load marker for place ID: ${place?.id}", exception)
        }
    )
}

PlaceMarkerState を使用して地図上にマーカーを配置する

マーカーを配置する場所を決定するのに役立つように、場所オブジェクトが位置情報とビューポートとともに返されます。

Kotlin

// Step 1: Obtain configured handle in a single 1-line call (PlaceMarker mounted internally)
val markerState = rememberPlaceMarkerState(
  reference = PlaceReference.PlaceId(placeId),
  icon = MarkerIcon.Type
)

// Step 2: Pass PlaceMarkerState.location and PlaceMarker(state = PlaceMarkerState) directly to the map marker
GoogleMap(...) {
  markerState.location?.let { position ->
    MarkerComposable(
      state = rememberMarkerState(position = position),
      onClick = {
        markerState.place?.let { place ->
          // Handle marker click
        }
        true
      }
    ) {
      PlaceMarker(state = markerState) // Render marker UI content directly on map canvas
    }
  }
}

マーカーをカスタムサイズに拡大縮小する

Kotlin

// Off the map: scale with a one-line modifier.
// Modifier.scale is a draw-time transform, so the bubble, beak, icon and text all scale together.
@Composable
fun ScaledMarker() {
  PlaceMarker(
    reference = PlaceReference.PlaceId(placeId),
    icon = MarkerIcon.Type,
    text = MarkerText.Rating,
    modifier = Modifier.scale(2.1f),
  )
}

// On the map: scale by overriding LocalDensity.
// MarkerComposable snapshots its content into a marker bitmap sized to the measured layout bounds.
// Modifier.scale does not change those bounds, so the marker would be clipped and blurry. Scaling
// the density re-measures every dp and sp inside the marker, so the bitmap, the layout bounds and
// the map hit target all grow with it.
@Composable
fun ScaledMarkerOnMap(markerState: PlaceMarkerState) {
  val density = LocalDensity.current
  val scaledDensity = remember(density) {
    Density(density = density.density * 2.1f, fontScale = density.fontScale * 2.1f)
  }
  GoogleMap(...) {
    markerState.location?.let { position ->
      MarkerComposable(
        state = rememberUpdatedMarkerState(position = position),
        anchor = Offset(0.5f, 1.0f),
      ) {
        CompositionLocalProvider(LocalDensity provides scaledDensity) {
          PlaceMarker(state = markerState)
        }
      }
    }
  }
}