---
title: "Google Places APIの使い方：Places API (New)のフィールドマスク課金と実装コード"
url: "https://www.issoh.co.jp/tech/details/19922/"
published: 2026-11-17
updated: 2026-11-17
categories: ["開発"]
publisher: "株式会社一創"
---

# Google Places APIの使い方：Places API (New)のフィールドマスク課金と実装コード

Google Places APIは、店舗や施設の名前・住所・座標・営業時間をGoogleのデータベースから引くためのAPIです。2025年3月1日に旧版がレガシー扱いになり、現在の新規開発はPlaces API (New)が前提です。New版は返す項目をフィールドマスクで指定し、その項目によって1回あたりの単価が変わります。この記事では2026年11月17日時点の公式情報をもとに、Text Search・Nearby Search・Place Details・Autocompleteの呼び出し方、課金区分の境目、セッショントークンの落とし穴、place\_idの保存規約までをcurlとNode.jsのコードで示します。

## まとめ：Places API (New)で先に決める呼び出し方と取得フィールド・保存範囲

Places API (New)の請求額は、エンドポイントの種類よりも「どのフィールドを取るか」で決まります。施設名の`displayName`や座標の`location`を1つ入れただけでText SearchはProに上がり、月5,000件を超えた分は1,000件あたり32ドルです。評価や電話番号を足すとEnterpriseになります。一覧ではIDと表示に要る最小の項目だけを取り、利用者が選んだ1件だけ詳細を取りに行く構成が基本です。

住所入力の補完では、セッショントークンを付けたうえで、終端のPlace Detailsを住所と座標だけに絞ります。施設名などPro以上の項目を混ぜると、終端の1回がEnterprise + Atmosphereの単価で数えられる仕組みです。データベースに恒久保存してよいのは`place_id`だけで、座標は30日で消す設計にします。

## Places API (New)の4エンドポイントと旧Places APIの置き換え先

Places API (New)は[公式の概要ページ](https://developers.google.com/maps/documentation/places/web-service/op-overview)のとおり`places.googleapis.com`を入口にしたREST APIです。APIキーの発行と制限は地図APIと共通なので、[Google Maps APIのキー発行とリファラー・IP制限の手順](https://www.issoh.co.jp/tech/details/19873/)で準備を済ませてください。Places APIを呼ぶキーはサーバー側に置き、IPアドレスで制限します。

### 実務で呼ぶ4つのエンドポイントの用途と1回のリクエストで返る最大件数

| エンドポイント             | 向いている用途         | 最大件数     |
| ------------------- | --------------- | -------- |
| Text Search (New)   | 「渋谷 歯科」のような語で検索 | 20件×3ページ |
| Nearby Search (New) | 座標・半径・種別で周辺検索   | 20件      |
| Place Details (New) | 選ばれた1件の詳細取得     | 1件       |
| Autocomplete (New)  | 入力途中の住所・施設名の候補  | 候補の配列    |

Text Searchの上限60件は[Text Search (New)のリファレンス](https://developers.google.com/maps/documentation/places/web-service/text-search)に「変更の可能性あり」と添えて書かれています。チェーン店の全店舗一覧のように60件を超える取得は組めません。自社で店舗マスタを持つべき場面です。

### 2025年3月1日にレガシーとなった旧Places APIとNew版の対応関係

[レガシー製品の一覧](https://developers.google.com/maps/legacy)では、Places APIとJavaScriptのPlaces Service、モバイル向けPlaces SDKが2025年3月1日付でレガシーになりました。同ページは新規プロジェクトでレガシーAPIを有効にしない運用を勧め、AIのコード補完が旧版のコードを出しがちだとも注意しています。

置き換え先は、旧`textsearch`と`findplacefromtext`がText Search (New)、旧`nearbysearch`がNearby Search (New)、旧`details`がPlace Details (New)、旧`autocomplete`がAutocomplete (New)です。[移行ガイド](https://developers.google.com/maps/documentation/places/web-service/legacy/migrate-overview)は、2段目の料金区間に届く利用量なら月初に本番を切り替えるよう勧めています。月の途中で切り替えると新旧のSKUに件数が分かれ、割安な区間に届きにくくなるためです。

## フィールドマスクで決まる課金区分：Essentials・Proの境目と単価

[Places APIの課金ページ](https://developers.google.com/maps/documentation/places/web-service/usage-and-billing)は、指定したフィールドのうち最も高いSKUで1回分を課金すると定めています。区分を知らずに`*`で全項目を取ると、最上位のEnterprise + Atmosphereで数えられます。

### 名称と座標を取るだけでProになるエンドポイント別のフィールド区分

同じ`location`でも、Text SearchではPro、Place DetailsではEssentialsです。区分がエンドポイントごとに違う点が、見積もりを誤らせます。

- IDs Only：検索系は`places.id`と`nextPageToken`、詳細は`id`。無料
- Essentials：Place Detailsの`formattedAddress`・`location`・`addressComponents`。検索系には無い区分
- Pro：`displayName`・`businessStatus`・`photos`、検索系では`formattedAddress`と`location`もここ
- Enterprise：`rating`・`userRatingCount`・`nationalPhoneNumber`・`regularOpeningHours`
- Enterprise + Atmosphere：`reviews`・`takeout`・`parkingOptions`など

一覧は[Place Data Fields (New)](https://developers.google.com/maps/documentation/places/web-service/data-fields)と各リファレンスから抜き出した主な項目です。Nearby Searchは最低でもProになります。

### 2026年11月時点の料金表で見る無料枠と1,000件あたりの単価

[Google Maps Platformの料金表](https://developers.google.com/maps/billing-and-pricing/pricing)から主なSKUを抜き出しました。単価は無料枠を超えてから月10万件までの区間です。

| API                       | 区分          | 月の無料枠   | 1,000件あたり |
| ------------------------- | ----------- | ------- | --------- |
| Text Search・Place Details | IDs Only    | 無制限     | 0ドル       |
| Place Details             | Essentials  | 10,000件 | 5.00ドル    |
| Autocomplete              | Requests    | 10,000件 | 2.83ドル    |
| Place Details             | Pro         | 5,000件  | 17.00ドル   |
| Text・Nearby Search        | Pro         | 5,000件  | 32.00ドル   |
| Place Details             | Enterprise  | 1,000件  | 20.00ドル   |
| Text・Nearby Search        | Enterprise  | 1,000件  | 35.00ドル   |
| Place Details             | ＋Atmosphere | 1,000件  | 25.00ドル   |
| Text・Nearby Search        | ＋Atmosphere | 1,000件  | 40.00ドル   |
| Place Photos              | 写真1枚        | 1,000件  | 7.00ドル    |

月5万回のText Searchなら、Pro構成で1,440ドルです。一覧に`rating`を1つ足すとEnterpriseになり1,715ドル、`reviews`まで足せば1,960ドルに上がります。一覧に評価を出すかどうかは、デザインではなく予算の問題として決めます。

## Text SearchとNearby Searchで施設を検索するリクエストとページ送り

検索系の2つは、どちらもPOSTでJSONを送り、フィールドマスクを`X-Goog-FieldMask`ヘッダで渡します。日本語の結果を得るには`languageCode`に`ja`を指定します。省略時の既定は英語です。

### curlで試すText Search (New)とlocationBiasの範囲指定

東京駅の周辺を優先して歯科医院を探す例です。`locationBias`は範囲外も返しうる「寄せ」の指定で、円の半径は0〜50,000メートルです。範囲外を返さない`locationRestriction`は、Text Searchでは矩形しか使えません。

```
curl -X POST "https://places.googleapis.com/v1/places:searchText" \
  -H "Content-Type: application/json" \
  -H "X-Goog-Api-Key: ${PLACES_SERVER_KEY}" \
  -H "X-Goog-FieldMask: places.id,places.displayName,places.formattedAddress,nextPageToken" \
  -d '{
    "textQuery": "歯科医院",
    "includedType": "dental_clinic",
    "languageCode": "ja",
    "regionCode": "JP",
    "pageSize": 20,
    "locationBias": {
      "circle": {
        "center": {"latitude": 35.6812, "longitude": 139.7671},
        "radius": 1000.0
      }
    }
  }'
```

`includedType`は1つだけ指定でき、値は[Place Types (New)のTable A](https://developers.google.com/maps/documentation/places/web-service/place-types)から選びます。Table Bの種別は応答に出るだけです。語の解釈しだいで種別の絞り込みが外れるため、確実に絞るなら`strictTypeFiltering`を`true`にします。

### Nearby Search (New)の種別指定と最大20件・ページ送りなしの制約

[Nearby Search (New)](https://developers.google.com/maps/documentation/places/web-service/nearby-search)は、中心座標と半径で範囲を決めて種別で絞ります。`locationRestriction`の円は必須で、半径は0より大きくします。

```
curl -X POST "https://places.googleapis.com/v1/places:searchNearby" \
  -H "Content-Type: application/json" \
  -H "X-Goog-Api-Key: ${PLACES_SERVER_KEY}" \
  -H "X-Goog-FieldMask: places.id,places.displayName,places.location" \
  -d '{
    "includedTypes": ["convenience_store"],
    "maxResultCount": 20,
    "rankPreference": "DISTANCE",
    "languageCode": "ja",
    "locationRestriction": {
      "circle": {
        "center": {"latitude": 35.6812, "longitude": 139.7671},
        "radius": 800.0
      }
    }
  }'
```

`maxResultCount`は1〜20で、次ページのトークンは返りません。半径内に21件以上あっても20件で打ち切りです。漏れなく拾うには半径を縮めて中心をずらしながら複数回呼ぶことになり、回数ぶん課金が積み上がります。種別は区分ごとに最大50個まで並べられ、並び順の既定は人気順の`POPULARITY`、近い順なら`DISTANCE`です。

### Node.jsからpageTokenで最大60件まで取得するサーバー側の関数

Text Searchのページ送りは、応答の`nextPageToken`を次のリクエストの`pageToken`に渡して行います。フィールドマスクに`nextPageToken`を入れておかないとトークンは返りません。Node.js 18以降の標準`fetch`で書いた例です。

```
const ENDPOINT = "https://places.googleapis.com/v1/places:searchText";
const FIELD_MASK = "places.id,places.displayName,places.formattedAddress,nextPageToken";

export async function searchAllPlaces(textQuery) {
  const places = [];
  let pageToken;
  do {
    const res = await fetch(ENDPOINT, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-Goog-Api-Key": process.env.PLACES_SERVER_KEY,
        "X-Goog-FieldMask": FIELD_MASK,
      },
      body: JSON.stringify({ textQuery, languageCode: "ja", regionCode: "JP", pageSize: 20, pageToken }),
    });
    if (!res.ok) {
      throw new Error(`Places API ${res.status}: ${await res.text()}`);
    }
    const data = await res.json();
    places.push(...(data.places ?? []));
    pageToken = data.nextPageToken;
  } while (pageToken && places.length < 60);
  return places;
}
```

3ページ取れば3回分の課金です。2ページ目以降は「もっと見る」を押したときだけ取りに行きます。公式のNode.js向けライブラリは2026年11月17日時点で3.1系が最新で、ソースは[GitHubのgoogle-maps-placesパッケージ](https://github.com/googleapis/google-cloud-node/tree/main/packages/google-maps-places)にあります。

## Autocompleteとセッショントークンでつなぐ住所入力の課金設計

住所欄の入力補完では、Autocomplete (New)を文字入力のたびに呼び、候補が選ばれた時点でPlace Details (New)を1回呼びます。この一連を同じセッショントークンで束ねると、課金の数え方が変わります。

### セッションをPro以上の項目で閉じると終端が最上位SKUになる落とし穴

[Autocomplete (New)とセッション課金のページ](https://developers.google.com/maps/documentation/places/web-service/session-pricing)によると、セッションの終わり方で請求が3通りに分かれます。

- 終端のPlace DetailsがEssentialsの項目だけ：最初の12回のAutocompleteは1回ずつ課金、13回目以降は無料。終端はPlace Details Essentials（1,000件あたり5ドル）
- 終端にPro・Enterprise・Enterprise + Atmosphereの項目を含む：Autocompleteはすべて無料。終端は取った項目に関係なくPlace Details Enterprise + Atmosphere（同25ドル）
- 終端がIDs Onlyだけ、またはPlace Detailsを呼ばずに離脱：Autocompleteは1回ずつ課金

`displayName`を1つ足しただけで、終端の単価は5ドルから25ドルに跳ねます。住所入力なら`formattedAddress`・`addressComponents`・`location`に絞り、Essentialsで閉じるのが原則です。トークンはUUID v4が推奨で、1セッション限りの使い捨てになります。使い回すと、トークンが無いものとして1回ずつ課金されます。

### 住所補完の候補取得から選択後の詳細取得までを1つのトークンで閉じる例

候補取得と詳細取得に同じ`sessionToken`を渡します。`includedRegionCodes`では国を最大15か国まで絞れます。

```
TOKEN=$(uuidgen)

curl -X POST "https://places.googleapis.com/v1/places:autocomplete" \
  -H "Content-Type: application/json" \
  -H "X-Goog-Api-Key: ${PLACES_SERVER_KEY}" \
  -d "{\"input\": \"渋谷区道玄坂\", \"sessionToken\": \"${TOKEN}\", \"includedRegionCodes\": [\"jp\"], \"languageCode\": \"ja\"}"

# 利用者が選んだ候補の placePrediction.placeId を PLACE_ID に入れる
curl -X GET "https://places.googleapis.com/v1/places/${PLACE_ID}?sessionToken=${TOKEN}&languageCode=ja" \
  -H "X-Goog-Api-Key: ${PLACES_SERVER_KEY}" \
  -H "X-Goog-FieldMask: formattedAddress,addressComponents,location"
```

キーを守るため、ブラウザからは自社サーバーの中継エンドポイントを呼びます。入力の連打では、送信まで300ミリ秒ほど待つ設計です。1文字ごとに送ると、セッション内の12回をすぐ超えます。

## place\_idの保存と更新・帰属表示：施設データを顧客マスタに持つ規約

保存できる範囲と画面への出し方は、[Places APIのポリシーと帰属表示のページ](https://developers.google.com/maps/documentation/places/web-service/policies)が定めています。

### 保存できるのはplace\_idだけで座標は30日、12か月ごとの無料リフレッシュ

キャッシュ制限の例外として恒久保存が認められているのは`place_id`です。緯度経度は連続30日までの一時保存に限られます。施設名や電話番号を顧客マスタの列として持ち続ける設計は、この規約と衝突します。

[Place IDsのガイド](https://developers.google.com/maps/documentation/places/web-service/place-id)は、12か月を超えたIDの更新を勧めています。フィールドマスクを`id`だけにしたPlace DetailsならIDs Only扱いで無料です。閉店や移転でIDが変わると、古いIDには`NOT_FOUND`が返ります。月次バッチで古いIDから更新し、`NOT_FOUND`の行は担当者の確認待ちに回すと、店舗の統廃合に追随できます。

### Googleロゴと写真投稿者の表示など地図外で使うときの帰属要件

結果を地図に重ねるなら、その地図はGoogleマップに限られます。地図なしで一覧を出す場合はGoogleのロゴを添え、口コミと写真には投稿者名とリンクを含む帰属情報を表示する義務があります。

写真は[Place Photos (New)](https://developers.google.com/maps/documentation/places/web-service/place-photos)で、応答に含まれる写真名を使って取得します。`maxWidthPx`か`maxHeightPx`が必須で、上限は4,800ピクセルです。1枚ごとに1,000件あたり7ドルが掛かるため、一覧のサムネイルを全件取りに行く設計は避けます。

## Places APIを採用する業務システムと見送る場面：料金試算からの判断

Places APIの価値は、Googleが更新し続ける施設情報を自社で持たずに済む点にあります。自社データで足りる検索に使うと、割高なうえに規約の制約だけを背負います。

### 月2万件の住所入力でセッションの閉じ方ごとに比べた請求額の試算

会員登録が月2万件、1件あたり平均8回の入力補完が走る住所欄で、料金表の段階単価を当てはめました。2026年11月17日時点の単価による試算です。

| 構成                 | Autocomplete分 | Place Details分 | 月額の目安  |
| ------------------ | ------------- | -------------- | ------ |
| トークンなし             | 約391ドル        | 50ドル           | 約441ドル |
| Essentialsで閉じる     | 約391ドル        | 50ドル           | 約441ドル |
| displayNameを含めて閉じる | 0ドル           | 475ドル          | 約475ドル |

Autocomplete分は16万回のうち無料の1万回を除き、9万回が2.83ドル、6万回が2.27ドルの区間です。平均8回なら12回以内なので、セッションの有無で差は出ません。差が出るのは平均12回を超える場合と、終端にPro以上の項目を混ぜた場合です。住所欄では施設名を取らず、Essentialsで閉じます。

### 自社データで足りる検索と施設データの転載が要る案件は採用しない判断

採用するのは、利用者が自由に入力した店舗名や住所をGoogleの施設データと照合したい場面です。来店予約の店舗検索、訪問先の住所入力補完、営業リストへの所在地の付与が当てはまります。

自社の店舗や拠点を探させるだけなら採用しません。自社の店舗マスタを全文検索するほうが速く無料で、60件の上限もありません。施設名や口コミを自社のデータベースに蓄えて再利用したい案件も、保存規約と衝突するため見送ります。地図の見た目を作り込むなら[Mapboxの料金と実装手順](https://www.issoh.co.jp/tech/details/18675/)、AWS内で完結させるなら[Amazon Location Serviceの機能と料金](https://www.issoh.co.jp/tech/details/7221/)が比較対象です。

基幹システムや顧客管理へPlaces APIを組み込む設計、キー管理と中継サーバーの実装を外部に任せたい場合は、[API開発・システム連携](https://www.issoh.co.jp/service/system/api/)のサービスページで対応範囲を確認できます。

## よくある質問

Places API (New)の導入前によく確認される点を5つ取り上げます。

### Google Places APIは無料で使えますか？

SKUごとに月の無料枠があり、その範囲なら請求は発生しません。Place Details Essentialsは月1万件、検索系のProは月5,000件、Enterprise系は月1,000件が無料枠です。IDだけを返すText SearchとPlace Detailsは件数に関係なく無料です。無料枠内でも請求先アカウントの登録は必要なので、Google Cloudのクォータで1日あたりの上限を掛けておきます。

### フィールドマスクを省略するとどうなりますか？

検索系とPlace Detailsではフィールドマスクが必須で、省略するとエラーが返ります。指定は`X-Goog-FieldMask`ヘッダか、URLの`fields`パラメータで行います。`*`で全項目を取れますが、最上位のEnterprise + Atmosphereで課金されるため本番では使いません。フィールドマスクはGoogle APIに共通するAIP-161の仕組みで、[Google API設計ガイド（AIP）の主要規約](https://www.issoh.co.jp/tech/details/10557/)で書き方を整理しています。

### 旧Places APIのコードはそのまま動きますか？

既に有効化しているプロジェクトでは動き続けます。ただし2025年3月1日にレガシーとなり、新しいプロジェクトでは有効化しない運用が勧められています。入口は`maps.googleapis.com`から`places.googleapis.com`に変わり、パラメータ名と応答の構造も異なるため、書き換えが必要です。

### 口コミや評価の件数を取得するにはどうしますか？

評価の`rating`と件数の`userRatingCount`はEnterprise、口コミ本文の`reviews`はEnterprise + Atmosphereの区分で、Place Detailsでも取得できます。表示するときは投稿者名とリンクの帰属表示が義務です。自社サイトへ転載して保存し続ける使い方は、キャッシュ制限に抵触します。

### PythonやNode.jsの公式クライアントライブラリはありますか？

あります。[クライアントライブラリの案内](https://developers.google.com/maps/documentation/places/web-service/client-libraries)によると、Pythonは`google-maps-places`、.NETは`Google.Maps.Places.V1`、Node.jsはgooglemapsスコープのplacesパッケージです。認証はApplication Default Credentialsが基本で、課金とフィールドマスクの扱いはRESTと同じです。依存を増やしたくないサーバーなら、標準の`fetch`でRESTを呼ぶ構成で足ります。

## 関連記事

- [Google Maps APIの使い方｜料金・無料枠とAPIキー制限、実装コード](https://www.issoh.co.jp/tech/details/19873/)：APIキーの発行と制限、地図表示を含むMaps Platform全体の入口です
- [Google API設計ガイドとAIPとは｜主要規約の要点とapi-linterでの準拠チェック](https://www.issoh.co.jp/tech/details/10557/)：フィールドマスクなどGoogle APIに共通する設計規約を整理しています
- [Mapboxとは？料金・ライセンスとGL JS v3の実装手順、Google Mapsとの選び分け](https://www.issoh.co.jp/tech/details/18675/)：地図表示の費用と見た目の自由度で比べる対象です
- [Amazon Location Serviceとは？料金・APIキーの使い方・日本での制約とGoogle Mapsとの違い](https://www.issoh.co.jp/tech/details/7221/)：AWS上で施設検索を完結させる場合の選択肢です
- [ZENRIN Maps APIの料金と無料枠の実際｜PVの数え方・機能一覧・Google Maps Platform比較](https://www.issoh.co.jp/tech/details/5283/)：国内の住所・地図精度を重視する場合に比べられます

---

出典: [Google Places APIの使い方：Places API (New)のフィールドマスク課金と実装コード](<https://www.issoh.co.jp/tech/details/19922/>)（株式会社一創）
