メソッド: searchPlayableLocations

指定した領域内にあり、かつ任意のフィルタ条件を満たすプレイアブル ロケーションのセットを返します。

注: 世界の状態は時間の経過とともに変化するため、同じ v3.searchPlayableLocations リクエストで異なる結果が返されることがあります。

HTTP リクエスト

POST https://playablelocations.googleapis.com/v3:searchPlayableLocations

この URL では gRPC Transcoding 構文を使用します。

リクエスト本文

リクエストの本文には次の構造のデータが含まれます。

JSON 表現 

{
  "areaFilter": {
    object (AreaFilter)
  },
  "criteria": [
    {
      object (Criterion)
    }
  ]
}
フィールド
areaFilter

object (AreaFilter)

必須。プレイアブル ロケーションを検索する領域を指定します。

criteria[]

object (Criterion)

必須。返されたプレイアブル ロケーションをフィルタしてランク付けする 1 つ以上（最大 100 個）の条件を指定します。

レスポンス本文

成功すると、レスポンス本文に次の構造のデータが含まれます。

v3.searchPlayableLocations メソッドに対するレスポンス。

JSON 表現 

{
  "locationsPerGameObjectType": {
    string: {
      object(PlayableLocationList)
    },
    ...
  },
  "ttl": string
}
フィールド
locationsPerGameObjectType

map (key: integer, value: object (PlayableLocationList))

各 PlayableLocation オブジェクトは、リクエストで指定された gameObjectType に対応しています。

"key": value ペアのリストを含むオブジェクト。例: { "name": "wrench", "mass": "1.3kg", "count": "3" }。
ttl

string (Duration format)

必須。プレイアブル ロケーションのセットの「有効期間」を指定します。この値を使用して、プレイアブル ロケーションのセットをキャッシュに保存する期間を決定できます。この期間を過ぎた後は、バックエンド ゲーム サーバーで新しい v3.searchPlayableLocations リクエストを発行して、プレイアブル ロケーションの新しいセットを取得する必要があります（これは、たとえばプレイアブル ロケーションのセットが削除されている、公園が特定の日に閉鎖されている、ビジネスが閉業しているといった可能性があるためです）。

小数点以下 9 桁まで、「s」で終わる秒単位の期間（例: "3.5s"）。

AreaFilter

プレイアブル ロケーションを検索する領域を指定します。

JSON 表現 

{
  "s2CellId": string,
  "pointExclusions": [
    {
      object (PointExclusion)
    }
  ]
}
フィールド
s2CellId

string (fixed64 format)

必須。目的の領域の S2 セル ID。セルのレベルを 11～16 の範囲で指定する必要があります。

S2 セルは、Earth での領域を識別する 64 ビットの整数です。これらは階層構造になっているため、空間インデックスに使用できます。

S2 ジオメトリ ライブラリは、次の複数の言語で使用できます。
pointExclusions[]

object (PointExclusion)

プレイアブル ロケーションを検索する際に除外するプレイアブル ロケーションを指定します。たとえば、ゲームですでに使用されているロケーションを、ユーザーが作成した「基地」や「補給庫」に基づいて除外することができます。

PointExclusion

返されたプレイアブル ロケーションのセットから特定のプレイアブル ロケーションを除外する方法を指定します。

JSON 表現 

{
  "point": string,
  "minSpacingMeters": number
}
フィールド
point

string (fixed64 format)

必須。検索結果から除外するリーフ S2 セルの ID。このフィールドを使用して、ご自身のコンテンツとプレイアブル ロケーションが重ならないようにすることができます。
minSpacingMeters

number

除外する S2 セルの周囲の最小間隔。

プレイアブル ロケーションはこの半径の範囲内に配置されなくなります。

Criterion

プレイアブル ロケーションのセットの検索に使用するフィルタ条件をカプセル化します。

JSON 表現 

{
  "gameObjectType": integer,
  "filter": {
    object (Filter)
  },
  "ranking": {
    object (Ranking)
  },
  "fieldsToReturn": string
}
フィールド
gameObjectType

integer

必須。プレイアブル ロケーションが使用されるゲーム オブジェクトのタイプについてデベロッパーが定義する任意の識別子。このフィールドを使用して、プレイアブル ロケーションを検索する際の条件をゲーム オブジェクト タイプごとに指定できます。

タイプが異なるゲーム オブジェクトは、プレーヤーが操作する方法も異なるため、このフィールドによって目的のデータ分析で使用するインプレッション データを分離することができます。

異なるタイプのゲーム オブジェクトを表すには、すべての request_criteria に一意の gameObjectType ID を割り当てる必要があります。たとえば、「1=monster location」、「2=powerup location」のように割り当てます。

レスポンスには map<gameObjectType, Response> が含まれます。
filter

object (Filter)

フィルタ オプションと検索結果のセットに含める要素を指定します。
ranking

object (Ranking)

プレイアブル ロケーションをランク付けする方法を指定します。
fieldsToReturn

string (FieldMask format)

どの PlayableLocation フィールドを返すかを指定します。

name（インプレッションの記録に使用されます）、center_point、place_id（または plus_code）は常に返されます。

次のフィールドは、ここで指定しない限り省略されます。

  • addresses
  • biome_type
  • display_names
  • snapped_point
  • types

注: 含めるフィールドが多くなるほど、データや関連するレイテンシによってクエリにかかる費用は高くなります。

完全修飾されたフィールド名のカンマ区切りリスト（例: "user.displayName,photo"）。

Filter

プレイアブル ロケーションの検索に使用するフィルタを指定します。

JSON 表現 

{
  "maxLocationCount": integer,
  "spacing": {
    object (SpacingOptions)
  },
  "includedTypes": [
    string
  ],
  "excludedTypes": [
    string
  ],
  "contentRating": enum (ContentRating),
  "accessTypes": [
    enum (AccessType)
  ],
  "biomeTypes": [
    enum (BiomeType)
  ],
  "proximityOptions": [
    {
      object (ProximityOptions)
    }
  ]
}
フィールド
maxLocationCount

integer

返されるプレイアブル ロケーションの最大数を指定します。この値は 1,000 以内で指定する必要があります。デフォルト値は 100 です。

ランク付けが上位のプレイアブル ロケーションのみが返されます。
spacing

object (SpacingOptions)

プレイアブル ロケーションの間隔を調整するオプションのセット。
includedTypes[]

string

プレイアブル ロケーションのセットを目的のタイプのみに限定します。
excludedTypes[]

string

不要なプレイアブル ロケーションのタイプを除外します。

このフィールドは、includedTypes より優先順位が高くなります。
contentRating

enum (ContentRating)

年齢制限のある場所（バー、カジノ、ナイトクラブなど）に関連するプレイアブル ロケーションを含めるオプションを指定します。

デフォルト値は、プレイアブル ロケーションがすべての年齢層に適していることを意味する EVERYONE です。
accessTypes[]

enum (AccessType)

場所に関連付けられたアクセスタイプを指定する値。AccessType 列挙値の 1 つとして指定されます。

このフィールドを使用して、FREE（公園など）や PAID（遊園地など）の領域内のプレイアブル ロケーションをフィルタできます。デフォルト値は FREE です。このフィルタは生成されたロケーションにのみ適用されます。
biomeTypes[]

enum (BiomeType)

プレイアブル ロケーションのセットを特定の生物群系タイプのみに限定します。
proximityOptions[]

object (ProximityOptions)

付近の場所タイプに関する情報をリクエストする、または付近の場所タイプまでの距離を指定する際に使用できるオプションのセット（最大 10 個）。

SpacingOptions

プレイアブル ロケーションの間隔を指定するオプションのセット。

JSON 表現 

{
  "minSpacingMeters": number,
  "pointType": enum (PointType)
}
フィールド
minSpacingMeters

number

必須。2 つのプレイアブル ロケーションの最小間隔（メートル単位）。最小値は 10、最大値は 1000 です。

プレイアブル ロケーションが密集しないようにするには、このフィールドを設定します。

注:

間隔の計算では貪欲アルゴリズムが使用されます。このアルゴリズムでは、最大限に多くのロケーションを選択するのではなく、まず最もランク付けが高いロケーションを選定するよう最適化が行われます。次のシナリオを考えてみます。

  • ランク: A: 2、B: 1、C: 3。
  • 距離: A -- 20 m -- B -- 20 m -- C

間隔が 25 の場合は、[A] や [C] ではなく、最もランク付けの高い場所である [B] が選定されます。

注:

間隔は、ゲーム オブジェクト タイプ自体と、その前のゲーム オブジェクト タイプに適用されます。たとえば、3 つのゲーム オブジェクト タイプで、それぞれ以下の間隔が指定されているとします。

  • X: 100 m、Y: 未定義、Z: 50 m。
  1. X のロケーションを、各オブジェクトから 100 m の範囲内に追加します。
  2. Y のロケーションを間隔なしで追加します。
  3. 最後に、Z のロケーションも X と Y からそれぞれ 50 m の範囲内に追加します。

これらのロケーションの間の距離関係は次のようになります。

  • 起点 -> 終点
  • X -> X: 100 m
  • Y -> X、Y -> Y: 未指定。
  • Z -> X、Z -> Y、Z -> Z: 50 m。
pointType

enum (PointType)

プレイアブル ロケーションの中心点またはスナップ ポイントに最小間隔の制限を適用するかどうかを指定します。デフォルト値は CENTER_POINT です。

プレイアブル ロケーションのスナップ ポイントを使用できない場合は、中心点が代用されます。

ゲームで使用されるポイントの種類に設定します。この設定は、PointExclusion と ProximityOptions の距離を計算する際にも使用されます。

PointType

プレイアブル ロケーションの地理座標（緯度と経度）を、中心点または最も近い道路の歩道にスナップされている場所に対応させるかどうかを指定します。

列挙型
POINT_TYPE_UNSPECIFIED ポイントの種類の指定なし。この値は使用しないでください。
CENTER_POINT 場所の中心点に対応する地理座標。
SNAPPED_POINT （近くに道路がある場合）最も近い道路の歩道にスナップされている場所に対応する地理座標。

ContentRating

プレイアブル ロケーションに適したユーザーの年齢層を指定する値のセット。

Playable Locations API は、あらゆる年齢層のプレーヤーの使用に適しているプレイアブル ロケーションをデフォルトで提供しますが、ゲームが成人のプレーヤーのみを対象としている場合は、年齢制限のある場所（バー、カジノ、ナイトクラブなど）に関連するプレイアブル ロケーションを含めることができます。

列挙型
CONTENT_RATING_UNSPECIFIED 指定なし。不使用。
EVERYONE 子供と 21 歳未満の若年層の使用に適しているプレイアブル ロケーションのセット（成人向けのコンテンツを含まないプレイアブル ロケーションなど）。
ADULTS_ONLY 21 歳以上のユーザーの使用に適しているプレイアブル ロケーションのセット。このセットには EVERYONE が含まれます。

AccessType

場所で提供されるアクセスの種類を指定する値のセット。

列挙型
ACCESS_TYPE_UNSPECIFIED アクセスの種類の指定なし。使用しないでください。
FREE 一般ユーザーが制限なくアクセスできます（例: 公園、遊び場、広場）。
PAID

有料ユーザーと会員に制限されます（例: ゴルフコース、遊園地、動物園）。

有料のロケーションに配置されたゲーム オブジェクトは、プレーヤーが半径 100 メートル以内にいるときに表示されるようにすることをおすすめします。

ProximityOptions

付近の場所タイプに関する情報をリクエストする、または付近の場所タイプまでの距離を指定する際に使用できるオプションのセット。

JSON 表現 

{
  "types": [
    string
  ],
  "maxDistanceMeters": number,
  "mode": enum (Mode)
}
フィールド
types[]

string

必須。プレイアブル ロケーションの maxDistanceMeters 内で検索するプレイスタイプのセット。プレイアブル ロケーションの種類のリストで指定されているタイプである必要があります。
maxDistanceMeters

number

必須。このプレイアブル ロケーションの半径（メートル単位）の範囲内で、指定されたプレイスタイプを検索します。値は 10～1,000 メートルの範囲で指定する必要があります。

リクエストされた S2 セルの近隣セルのみが検索されます。遠距離を設定した場合は、検索の対象が実質的にそれらのセルの範囲に制限されます。
mode

enum (Mode)

近隣オプションを情報提供のために使用するか、それともプレイアブル ロケーションをフィルタするために使用するかを指定します。デフォルト値は INFORMATION です。

Mode

近隣オプションを情報提供のために使用するか、それともプレイアブル ロケーションの結果をフィルタするために使用するかを指定する値のセット。

列挙型
MODE_UNSPECIFIED 指定なし。使用しないでください。
INFORMATION プレイアブル ロケーションで近隣に関する追加情報が必要です。指定されたプレイスタイプごとに、プレイアブル ロケーションから maxDistanceMeters の範囲にある最も近い場所までの距離が NearbyType として返されます。
FILTERING 指定されたいずれかのプレイスタイプから maxDistanceMeters の範囲にあるプレイアブル ロケーションのみが含まれます。

Ranking

返されたプレイアブル ロケーションのランク付けに使用する重み付け要素を定義します。

プレイアブル ロケーションのスコアとランク付けには次の要素が反映されます。

  • 知名度。Google のインデックスにおける場所のランク付けや、世界的な人気度などの要素によって決まります。
  • （省略可）各種の知名度に基づく調整比。より望ましい（または望ましくない）種類を指定します。
  • （省略可）混雑状況。より混雑している（または混雑していない）ロケーションを選択します。
  • （省略可）芸術的関心。より芸術的関心が寄せられているとみなされる場所を指定します。
JSON 表現 

{
  "typesProminenceModifier": {
    string: integer,
    ...
  },
  "busyness": {
    object (Busyness)
  },
  "capacity": {
    object (Capacity)
  },
  "dwellability": {
    object (Dwellability)
  },
  "artisticallyInteresting": {
    object (ArtisticallyInteresting)
  }
}
フィールド
typesProminenceModifier

map (key: string, value: integer)

プレイアブル ロケーションの特定の種類の重み付けを調整できます。望ましい種類の重み付けを増やすには正の値を使用し、そうでない種類の重み付けを減らすには負の値を指定します。

たとえば、「{park: 2, cinema: 3, bank: -1}」のように指定できます。この場合、公園の重み付けは 2、映画館については 3 増え、銀行の重み付けは 1 減ります。値は -10～+10 の範囲で指定できます。

複数のマッチング タイプに該当するプレイアブル ロケーションのスコア調整には、指定された中で最も大きい値が使用されます。

"key": value ペアのリストを含むオブジェクト。例: { "name": "wrench", "mass": "1.3kg", "count": "3" }。
busyness

object (Busyness)

プレイアブル ロケーションの混雑度を指定します。
capacity

object (Capacity)

大規模な場所の収容人数を指定します。

このランク付けの調整比は現在サポートされていませんが、フィードバックをお寄せくださいますようお願いいたします。
dwellability

object (Dwellability)

場所の平均滞在時間を指定します。

このランク付けの調整比は現在サポートされていませんが、フィードバックをお寄せくださいますようお願いいたします。
artisticallyInteresting

object (ArtisticallyInteresting)

場所に対して芸術的関心がどの程度寄せられているかを指定します。

Busyness

場所の利用頻度の高さに基づくランク付けの調整比を指定します。

JSON 表現 

{
  "busyness": enum (BusynessModifier)
}
フィールド
busyness

enum (BusynessModifier)

アクティビティ レベルに基づくランク付けの調整比を、BusynessModifier 列挙値の 1 つとして指定します。

busyness 値を指定しなかった場合、この調整比はプレイアブル ロケーションのランク付けに使用されなくなります。

BusynessModifier

優先される混雑度を指定する値のセット。つまり、場所を定期的に利用するユーザーが多いほうがいいか、少ないほうがいいかを指定します。

列挙型
MODIFIER_UNSPECIFIED 指定なし。
MORE_BUSY_BETTER より混雑している場所のランク付けを高くします。
LESS_BUSY_BETTER より混雑していない場所のランク付けを高くします。

Capacity

場所の収容人数に基づくランク付けの調整比を指定します。

このランク付けの調整比は現在サポートされていませんが、フィードバックをお寄せくださいますようお願いいたします。

JSON 表現 

{
  "capacity": enum (CapacityModifier)
}
フィールド
capacity

enum (CapacityModifier)

収容人数に基づくランク付けの調整比を、CapacityModifier 列挙値の 1 つとして指定します。

capacity 値を指定しなかった場合、この調整比はプレイアブル ロケーションのランク付けに使用されなくなります。

CapacityModifier

優先される収容人数を指定する値のセット。つまり、その場所が大規模な人数を収容できるかどうかを指定します。

列挙型
MODIFIER_UNSPECIFIED 指定なし。
LARGE 場所の規模が大きいほどランク付けが高くなります。

Dwellability

ユーザーが場所に滞在する可能性がどの程度高いかに基づくランク付けの調整比を指定します。

このランク付けの調整比は現在サポートされていませんが、フィードバックをお寄せくださいますようお願いいたします。

JSON 表現 

{
  "dwellability": enum (DwellabilityModifier)
}
フィールド
dwellability

enum (DwellabilityModifier)

滞在時間の長さに基づくランク付け調整比を、DwellabilityModifier 列挙値の 1 つとして指定します。

dwellability 値を指定しなかった場合、この調整比はプレイアブル ロケーションのランク付けに使用されなくなります。

DwellabilityModifier

優先される滞在時間の長さを指定する値のセット。つまり、場所を訪れたユーザーが滞在する可能性が高い時間を指定します。

列挙型
MODIFIER_UNSPECIFIED 指定なし。使用しないでください。
LONG

ユーザーは比較的長時間にわたってその場所に滞在する傾向があります。

滞在時間の長い場所ほどランク付けが高くなります。たとえば、公園はガソリン スタンドよりも滞在時間が長くなります。

ArtisticallyInteresting

場所に対して芸術的関心がどの程度寄せられているかに基づくランク付けの調整比を指定します。

JSON 表現 

{
  "artisticallyInteresting": enum (ArtisticallyInterestingModifier)
}
フィールド
artisticallyInteresting

enum (ArtisticallyInterestingModifier)

artisticallyInteresting 値を指定しなかった場合、この調整比はプレイアブル ロケーションのランク付けに使用されなくなります。

ArtisticallyInterestingModifier

場所に対して芸術的関心がどの程度寄せられているかを指定する値のセット。

列挙型
MODIFIER_UNSPECIFIED 指定なし。使用しないでください。
INTERESTING

ユーザーはこの場所に芸術的関心を寄せる傾向があります。

芸術的関心が寄せられている場所ほどランク付けが高くなります（博物館や劇場など）。