このページは Cloud Translation API によって翻訳されました。

Nearby Search（新規）

プラットフォームを選択: Android iOS JavaScript ウェブサービス

Nearby Search（新版）リクエストは、1 つ以上の場所タイプを受け取り、指定されたエリア内の一致する場所のリストを返します。1 つ以上のデータ型を指定する項目マスクが必要です。周辺検索（新規）では、POST リクエストのみがサポートされています。

API Explorer では、ライブリクエストを実行して、API と API オプションを把握できます。

試してみる

インタラクティブなデモで、周辺検索（新）の結果を地図に表示してみます。

Nearby Search（新規）リクエスト

周辺検索（新規）リクエストは、次の形式の URL に対する HTTP POST リクエストです。

https://places.googleapis.com/v1/places:searchNearby

すべてのパラメータを JSON リクエスト本文またはヘッダーで POST リクエストの一部として渡します。次に例を示します。

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965},
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

Nearby Search（新版）のレスポンス

近くの検索（新規）は、レスポンスとして JSON オブジェクトを返します。レスポンスの説明:

places 配列には、一致するすべての場所が含まれます。
配列内の各場所は、Place オブジェクトで表されます。Place オブジェクトには、単一のプレイスに関する詳細情報が含まれます。
リクエストで渡された FieldMask には、Place オブジェクトで返されるフィールドのリストを指定します。

完全な JSON オブジェクトの形式は次のとおりです。

{
  "places": [
    {
      object (Place)
    }
  ]
}

必須パラメータ

FieldMask

レスポンスフィールドマスクを作成して、レスポンスで返すフィールドのリストを指定します。URL パラメータ $fields または fields を使用するか、HTTP ヘッダー X-Goog-FieldMask を使用して、レスポンスフィールドマスクをメソッドに渡します。レスポンスで返されるフィールドのデフォルトリストはありません。フィールドマスクを省略すると、メソッドからエラーが返されます。

フィールドマスキングは、不要なデータをリクエストしないようにするための優れた設計手法です。これにより、不要な処理時間と課金が発生するのを防ぐことができます。

返す場所データのタイプのカンマ区切りリストを指定します。たとえば、場所の表示名と住所を取得します。
```
X-Goog-FieldMask: places.displayName,places.formattedAddress
```
注: フィールドリスト内のスペースは使用できません。

すべてのフィールドを取得するには、* を使用します。
```
X-Goog-FieldMask: *
```
ワイルドカード「*」はすべてのフィールドを選択します。
ただし、このワイルドカードは開発環境では問題ありませんが、返されるデータ量が膨大になるため、本番環境ではワイルドカード（*）レスポンスフィールドマスクの使用は推奨されません。
places.iconMaskBaseUri と places.iconBackgroundColor の使用方法について詳しくは、場所アイコンのセクションをご覧ください。

次のフィールドを 1 つ以上指定します。
- 次のフィールドは、Nearby Search (Basic) SKU をトリガーします。
  
  places.accessibilityOptions、places.addressComponents、places.adrFormatAddress、places.attributions、places.businessStatus、places.containingPlaces、places.displayName、places.formattedAddress、places.googleMapsLinks^*、places.googleMapsUri、places.iconBackgroundColor、places.iconMaskBaseUri、places.id、places.location、places.name^**、places.photos、places.plusCode、places.primaryType、places.primaryTypeDisplayName、places.pureServiceAreaBusiness、places.shortFormattedAddress、places.subDestinations、places.types、places.utcOffsetMinutes、places.viewport
  
  ^* places.googleMapsLinks フィールドは一般提供前のプレビュー段階にあり、プレビュー期間中の使用料は請求されません（請求額は $0 です）。
  
  ^** places.name フィールドには、places/PLACE_ID の形式で場所のリソース名を指定します。places.displayName を使用して、場所のテキスト名にアクセスします。
- 次のフィールドは、Nearby Search (Advanced) SKU をトリガーします。
  
  places.currentOpeningHours、places.currentSecondaryOpeningHours、places.internationalPhoneNumber、places.nationalPhoneNumber、places.priceLevel、places.priceRange、places.rating、places.regularOpeningHours、places.regularSecondaryOpeningHours、places.userRatingCount、places.websiteUri
- 次のフィールドは、Nearby Search (Preferred) SKU をトリガーします。
  
  places.allowsDogs、places.curbsidePickup、places.delivery、places.dineIn、places.editorialSummary、places.evChargeOptions、places.fuelOptions、places.goodForChildren、places.goodForGroups、places.goodForWatchingSports、places.liveMusic、places.menuForChildren、places.parkingOptions、places.paymentOptions、places.outdoorSeating、places.reservable、places.restroom、places.reviews、places.routingSummaries、^* places.servesBeer、places.servesBreakfast、places.servesBrunch、places.servesCocktails、places.servesCoffee、places.servesDessert、places.servesDinner、places.servesLunch、places.servesVegetarianFood、places.servesWine、places.takeout
  
  ^* テキスト検索と周辺検索のみ
locationRestriction

検索対象の領域を円として指定します。中心点と半径（メートル単位）で定義します。半径は 0.0 ～ 50000.0 の範囲で指定してください。デフォルトの半径は 0.0 です。リクエストで 0.0 より大きい値に設定する必要があります。

次に例を示します。
```
"locationRestriction": {
  "circle": {
    "center": {
      "latitude": 37.7937,
      "longitude": -122.3965
    },
    "radius": 500.0
  }
}
```

オプションパラメータ

includedTypes/excludedTypes、includedPrimaryTypes/excludedPrimaryTypes

検索結果のフィルタに使用するタイプ表 A のタイプから、タイプのリストを指定できます。各タイプの制限カテゴリで指定できるタイプは最大 50 個です。

注: 表 B の値はレスポンスでのみ返されます。テーブル B の値をフィルタとして使用することはできません。
プレイスには、関連付けられている表 A のタイプから1 つのプライマリタイプのみを指定できます。たとえば、プライマリタイプは "mexican_restaurant" または "steak_house" です。includedPrimaryTypes と excludedPrimaryTypes を使用して、場所のメインタイプで結果をフィルタします。

場所には、表 A のタイプから複数のタイプ値を関連付けることもできます。たとえば、レストランのタイプは "seafood_restaurant"、"restaurant"、"food"、"point_of_interest"、"establishment" のいずれかになります。includedTypes と excludedTypes を使用して、プレイスに関連付けられたタイプのリストで結果をフィルタします。

"restaurant" や "hotel" などの一般的なプライマリタイプを指定すると、指定したプライマリタイプよりも具体的なプライマリタイプの場所がレスポンスに含まれることがあります。たとえば、プライマリタイプ "restaurant" を含めるように指定します。レスポンスには、"restaurant" をメインタイプとする場所が含まれますが、"chinese_restaurant" や "seafood_restaurant" など、より具体的なメインタイプを持つ場所も含まれます。

検索で複数のタイプの制限が指定されている場合、すべての制限を満たす場所のみが返されます。たとえば、{"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]} を指定すると、返される場所は "restaurant" 関連のサービスを提供しますが、主に "steak_house" として機能しません。

リクエストから includedTypes、excludedTypes、includedPrimaryTypes、excludedPrimaryTypes を省略すると、検索では位置情報の制限範囲内のすべてのタイプの場所が返されます。
includedTypes

表 A の検索対象の場所タイプのカンマ区切りのリスト。このパラメータを省略すると、すべてのタイプの場所が返されます。

excludedTypes

検索から除外する表 A の場所タイプのカンマ区切りのリスト。

リクエストで includedTypes（"school" など）と excludedTypes（"primary_school" など）の両方を指定すると、"school" に分類される場所がレスポンスに含まれますが、"primary_school" に分類される場所は含まれません。レスポンスには、includedTypes の少なくとも 1 つと excludedTypes のいずれにも一致しない場所が含まれます。

includedTypes と excludedTypes の両方に出現する型など、競合する型がある場合、INVALID_REQUEST エラーが返されます。

includedPrimaryTypes

検索に含める表 A のプライマリプレイスタイプのカンマ区切りのリスト。

excludedPrimaryTypes

検索から除外する表 A のプライマリプレイスタイプのカンマ区切りのリスト。

includedPrimaryTypes と excludedPrimaryTypes の両方に表示されるタイプなど、競合するプライマリタイプがある場合、INVALID_ARGUMENT エラーが返されます。
languageCode

結果を返す言語。
- サポートされている言語の一覧をご覧ください。サポートされる言語は頻繁に更新されるため、このリストがすべてのサポート言語を網羅しているとは限りません。
- languageCode が指定されていない場合、API はデフォルトで en になります。無効な言語コードを指定すると、API は INVALID_ARGUMENT エラーを返します。
- API では、できるだけユーザーとローカルの両言語で判読可能な番地を返します。そのために、ジオコーダはローカル言語で番地を返し、優先言語も考慮して、必要に応じてユーザーが理解できるスクリプトに書き直します。それ以外の住所はすべて、優先言語で返されます。住所コンポーネントはすべて、最初のコンポーネントで選択した言語と同じ言語で返されます。
- 優先言語で名前を表示できない場合、API は最も近い言語を使用します。
- 優先言語は、API が返す結果や、結果が返される順序に多少影響します。「～通り」を表す略語や特定の言語だけで有効な同義語など、ジオコーダによる略語の解釈は言語によって異なります。
maxResultCount

返される場所の結果の最大数を指定します。1 ～ 20（デフォルト）の値にする必要があります。
rankPreference

使用するランキングのタイプ。このパラメータを省略すると、検索結果は人気度順にランク付けされます。次のいずれかになります。
- POPULARITY（デフォルト）人気度に基づいて結果を並べ替えます。
- DISTANCE 指定された場所からの距離が近い順に結果を昇順で並べ替えます。
regionCode

レスポンスのフォーマットに使用される地域コード。 2 文字の CLDR コード値で指定します。デフォルト値はありません。

レスポンスの formattedAddress フィールドの国名が regionCode と一致する場合、国コードは formattedAddress から省略されます。このパラメータは、国名が常に含まれる adrFormatAddress と、国名が含まれない shortFormattedAddress には影響しません。

ほとんどの CLDR コードは ISO 3166-1 コードと同一ですが、いくつか注意が必要な例外もあります。たとえば、英国の ccTLD は「uk」（.co.uk）ですが、その ISO 3166-1 コードは「gb」（厳密には「United Kingdom of Great Britain and Northern Ireland」のエンティティ）です。このパラメータは、適用される法律に基づいて結果に影響する可能性があります。

Nearby Search（新規）の例

1 つの種類の場所を検索する

次の例は、circle で定義された半径 500 m 以内のすべてのレストランの名前を表示する Nearby Search（新規）リクエストを示しています。

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965},
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

X-Goog-FieldMask ヘッダーは、レスポンスに places.displayName というデータフィールドが含まれていることを指定します。レスポンスの形式は次のとおりです。

{
  "places": [
    {
      "displayName": {
        "text": "La Mar Cocina Peruana",
        "languageCode": "en"
      }
    },
    {
      "displayName": {
        "text": "Kokkari Estiatorio",
        "languageCode": "en"
      }
    },
    {
      "displayName": {
        "text": "Harborview Restaurant & Bar",
        "languageCode": "en"
      }
    },
...
}

フィールドマスクにデータ型を追加して、追加情報を返します。たとえば、places.formattedAddress,places.types,places.websiteUri を追加して、レストランの住所、タイプ、ウェブアドレスをレスポンスに含めます。

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965},
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.formattedAddress,places.types,places.websiteUri" \
https://places.googleapis.com/v1/places:searchNearby

レスポンスの形式は次のようになります。

{
  "places": [
    {
      "types": [
        "seafood_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "PIER 1 1/2 The Embarcadero N, San Francisco, CA 94105, USA",
      "websiteUri": "http://lamarsf.com/",
      "displayName": {
        "text": "La Mar Cocina Peruana",
        "languageCode": "en"
      }
    },
    {
      "types": [
        "greek_restaurant",
        "meal_takeaway",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "200 Jackson St, San Francisco, CA 94111, USA",
      "websiteUri": "https://kokkari.com/",
      "displayName": {
        "text": "Kokkari Estiatorio",
        "languageCode": "en"
      }
    },
...
}

複数の種類の場所を検索する

次の例は、指定された circle から半径 1,000 m 以内のすべてのコンビニエンスストアと酒屋の表示名を取得する「近くの検索（新規）」リクエストを示しています。

curl -X POST -d '{
  "includedTypes": ["liquor_store", "convenience_store"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.primaryType,places.types" \
https://places.googleapis.com/v1/places:searchNearby

この例では、フィールドマスクに places.primaryType と places.types を追加して、レスポンスに各プレイスのタイプ情報が含まれるようにします。これにより、結果から適切なプレイスを選択しやすくなります。

検索から場所の種類を除外する

次の例は、タイプが "school" のすべての場所（タイプが "primary_school" の場所は除く）に対する Nearby Search（新規）リクエストを示しています。結果は距離でランク付けされます。

curl -X POST -d '{
  "includedTypes": ["school"],
  "excludedTypes": ["primary_school"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  },
  "rankPreference": "DISTANCE"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

地域の近くにあるすべての場所を検索し、距離でランク付けする

次の例は、サンフランシスコのダウンタウンにあるポイントの近くの場所を検索する「周辺検索（新規）」リクエストを示しています。この例では、rankPreference パラメータを含めて、結果を距離でランク付けします。

curl -X POST -d '{
  "maxResultCount": 10,
  "rankPreference": "DISTANCE",
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

試してみよう:

API Explorer では、サンプルリクエストを実行して、API と API オプションを把握できます。

ページの右側にある API アイコンを選択します。
必要に応じて [標準パラメータを表示] を開き、フィールドマスクに fields パラメータを設定します。
必要に応じて、リクエスト本文を編集します。
[Execute] ボタンを選択します。ポップアップで、リクエストに使用するアカウントを選択します。
API Explorer パネルで展開アイコンを選択して、API Explorer ウィンドウを開きます。

Nearby Search（新規）

Nearby Search（新規）リクエスト

Nearby Search（新版）のレスポンス

必須パラメータ

FieldMask

locationRestriction

オプション パラメータ

includedTypes/excludedTypes、includedPrimaryTypes/excludedPrimaryTypes

includedTypes

excludedTypes

includedPrimaryTypes

excludedPrimaryTypes

languageCode

maxResultCount

rankPreference

regionCode