Google Places APIを活用したホテル検索の実装ガイド



Google Places APIは位置情報に基づいたサービスを提供するための強力なツールです。この記事では、特にホテル検索のためのGoogle Places APIの利用方法について解説します。APIの基本的な使い方から実際のリクエスト例、返却されるデータの構造まで、実装に役立つ情報をまとめました。


## 目次

1. APIの有効化
2. 主なAPI機能
3. テキスト検索
4. Place Details
5. Nearby Search
6. 場所の写真
7. まとめ

## APIの有効化

Google Places APIを利用するための初期設定は以下の通りです。

1. Google Cloud Platform(GCP)にアクセスし、「Places API」を有効化
   - 注意：「Places API(New)」を検索する（「Places API」ではない）
2. API Keyを取得
3. 取得したAPI Keyをリクエスト時に使用


- API Keyは全てのリクエストで使用します
- 以下のサンプルコードの`API_KEY`部分を実際のキーに置き換えてください


## 主なAPI機能

Google Places APIが提供する主な機能は以下の通りです。

- テキスト検索（Text Search）
- 周辺検索（Nearby Search）
- 場所の詳細情報（Place Details）
- 場所の写真（Place Photos）

これらの機能を組み合わせることで、ユーザーに最適なホテル情報を提供できます。

## テキスト検索

テキスト検索は、キーワードを使用して場所を検索する最も基本的な機能です。

### 基本的なテキスト検索

```sh
curl -X POST -d '{
  "textQuery" : "hotel fukuoka japan"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \
'https://places.googleapis.com/v1/places:searchText'
```

この基本的なリクエストでは、「hotel fukuoka japan」というキーワードで検索し、表示名、住所、価格レベルの情報を取得します。

### 返却データ例

```json
{
  "places": [
    {
      "formattedAddress": "Japan, 〒812-0011 Fukuoka, Hakata Ward, Hakata Ekimae, 2-chōme−8−１５ 三井ガーデンホテル福岡祇園 １階",
      "displayName": {
        "text": "Mitsui Garden Hotel Fukuoka Gion",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "5-chōme-6-20 Nakasu, Hakata Ward, Fukuoka, 810-0801, Japan",
      "displayName": {
        "text": "The Royal Park Canvas Fukuoka Nakasu",
        "languageCode": "en"
      }
    },
    // 以下省略
  ]
}
```

### 施設タイプを指定した検索

より精度の高い結果を得るために、`includedType`パラメータを使用して特定のタイプの施設に限定することができます。

```sh
curl -X POST -d '{
  "textQuery" : "hotel fukuoka japan",
  "includedType" : "hotel"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \
'https://places.googleapis.com/v1/places:searchText'
```

Google Placesでは様々な施設タイプが定義されています。詳細な一覧は[公式ドキュメント](https://developers.google.com/maps/documentation/places/web-service/place-types)で確認できます。

### 地理的範囲を指定した検索

`locationRestriction`パラメータを使用して、検索範囲を特定の地域に限定することができます。

```sh
curl -X POST -d '{
  "textQuery" : "vegetarian food",
  "pageSize" : "10",
  "locationRestriction": {
    "rectangle": {
      "low": {
        "latitude": 40.477398,
        "longitude": -74.259087
      },
      "high": {
        "latitude": 40.91618,
        "longitude": -73.70018
      }
    }
  }
}' \
  -H 'Content-Type: application/json' \
  -H 'X-Goog-Api-Key: API_KEY' \
  -H 'X-Goog-FieldMask: places.id,places.formattedAddress' \
  'https://places.googleapis.com/v1/places:searchText'
```

このリクエストでは、指定した緯度・経度で定義される長方形の範囲内で検索を行います。

### 全フィールドの取得

全ての利用可能なフィールドを取得するには、`X-Goog-FieldMask`に「*」を指定します。

```sh
curl -X POST -d '{
  "textQuery" : "hotel fukuoka japan",
  "includedType" : "hotel"
}' -H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' -H 'X-Goog-FieldMask: *' 'https://places.googleapis.com/v1/places:searchText' -o res.json
```

レスポンスには以下のような実用的な情報が含まれています。
- `id` - 場所の一意識別子
- `rating` - Googleマップでの評価
- `googleMapsUri` - Googleマップへのリンク
- `websiteUri` - 公式ウェブサイトへのリンク

## Place Details

`Place Details`は特定の場所の詳細情報を取得するためのAPIです。テキスト検索などで取得した`placeId`を使用して詳細情報を取得できます。

```sh
curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: id,displayName" \
https://places.googleapis.com/v1/places/ChIJkXqoOZORQTURyBBg18vUy4o
```

全ての情報を取得するには以下のコマンドを実行します。

```sh
curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://places.googleapis.com/v1/places/ChIJkXqoOZORQTURyBBg18vUy4o -o res1.json
```

Place Detailsのレスポンスには、テキスト検索で得られる情報に加えて、より詳細な情報が含まれています。
- 電話番号
- 営業時間
- ユーザーレビュー
- 写真
- 所在地の正確な座標

## Nearby Search

`Nearby Search`は特定の座標を中心とした円形の範囲内にある場所を検索するAPIです。

```sh
curl -X POST -d '{
  "includedTypes": ["hotel"],
  "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
```

このAPIは、「現在地から500m以内のホテルを探す」といった用途に最適です。

### 返却データ例

```json
{
  "places": [
    {
      "displayName": {
        "text": "Hyatt Regency San Francisco",
        "languageCode": "en"
      }
    },
    {
      "displayName": {
        "text": "The Jay, Autograph Collection",
        "languageCode": "en"
      }
    },
    // 以下省略
  ]
}
```

## 場所の写真

場所の写真を取得するには、まず`Place Details`APIで写真情報を取得し、その情報を使って実際の画像にアクセスします。

1. 写真情報の取得

```sh
curl -X GET \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: id,displayName,photos" \
https://places.googleapis.com/v1/places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E
```
2. 写真URLを取得

curlコマンドを実行すると以下のようなレスポンスが返却されます。
```json
{
  "id": "ChIJ2fzCmcW7j4AR2JzfXBBoh6E",
  "displayName": {
    "text": "Google GWC2",
    "languageCode": "en"
  },
  "photos": [
    {
      "name": "places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E/photos/AVzFdbkyZtsQ7a6-p29dnX46c9ce_hKFcZ4TpD2X7nSupVbtVP40dzSJPrXw6kLrwGJmUEUqnAsWZTIFW72keP8BGpKSbd6PYRJrO1n3BX9fxp8aVXPvTmCjdm3I2y6_xHRUEH5h2-aJPHk37DU5yTHNEW6JWAnDO_MVJBHx",
      "widthPx": 3072,
      "heightPx": 4080,
      "authorAttributions": [
        {
          "displayName": "D X",
          "uri": "https://maps.google.com/maps/contrib/111880328247318954522",
          "photoUri": "https://lh3.googleusercontent.com/a/ACg8ocKXXwT5_pA7B5Uwo1TDWd_qrmGP5ZFixkl5m-sHZ7qWVRqO1w=s100-p-k-no-mo"
        }
      ],
      "flagContentUri": "https://www.google.com/local/imagery/report/?cb_client=maps_api_places.places_api&image_key=!1e10!2sAF1QipMlXWx0_cBqZm-V0U_cYnim7N6XzVwHtPS3mPWT&hl=en-US",
      "googleMapsUri": "https://www.google.com/maps/place//data=!3m4!1e2!3m2!1sAF1QipMlXWx0_cBqZm-V0U_cYnim7N6XzVwHtPS3mPWT!2e10!4m2!3m1!1s0x808fbbc599c2fcd9:0xa18768105cdf9cd8"
    }
  ]
}
```


このphotosの中のnameを利用します。


3. 実際の写真の取得

上述のphotosの中のnameの先頭に`https://places.googleapis.com/v1/`をつけたURLにブラウザからアクセスすると画像が表示されます。
```
https://places.googleapis.com/v1/places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E/photos/AVzFdbkyZtsQ7a6-p29dnX46c9ce_hKFcZ4TpD2X7nSupVbtVP40dzSJPrXw6kLrwGJmUEUqnAsWZTIFW72keP8BGpKSbd6PYRJrO1n3BX9fxp8aVXPvTmCjdm3I2y6_xHRUEH5h2-aJPHk37DU5yTHNEW6JWAnDO_MVJBHx/media?key=API_KEY&maxHeightPx=400&maxWidthPx=400"
```

## Google Places APIレスポンスの重要なフィールド

実際のアプリケーション開発では、以下のフィールドが特に有用です。

### 基本情報
- `id` - 場所の一意識別子
- `displayName` - 表示名
- `formattedAddress` - フォーマットされた住所
- `location` - 緯度・経度情報

### ビジネス情報
- `rating` - 評価（5段階）
- `userRatingCount` - 評価数
- `priceLevel` - 価格レベル
- `websiteUri` - 公式ウェブサイト
- `nationalPhoneNumber` - 電話番号

### コンテンツ
- `photos` - 写真情報
- `reviews` - ユーザーレビュー

### アクセス
- `googleMapsUri` - Google Mapsへのリンク

## まとめ

Google Places APIを使用することで、ホテル検索アプリケーションに以下の機能を実装できます。

1. キーワードや地域に基づくホテル検索
2. ホテルの詳細情報の表示（住所、連絡先、評価など）
3. 現在地周辺のホテル検索
4. ホテルの写真表示