開発

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

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)は公式の概要ページのとおりplaces.googleapis.comを入口にしたREST APIです。APIキーの発行と制限は地図APIと共通なので、Google Maps APIのキー発行とリファラー・IP制限の手順で準備を済ませてください。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)のリファレンスに「変更の可能性あり」と添えて書かれています。チェーン店の全店舗一覧のように60件を超える取得は組めません。自社で店舗マスタを持つべき場面です。

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

レガシー製品の一覧では、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)です。移行ガイドは、2段目の料金区間に届く利用量なら月初に本番を切り替えるよう勧めています。月の途中で切り替えると新旧のSKUに件数が分かれ、割安な区間に届きにくくなるためです。

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

Places APIの課金ページは、指定したフィールドのうち最も高い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)と各リファレンスから抜き出した主な項目です。Nearby Searchは最低でもProになります。

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

Google Maps Platformの料金表から主な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から選びます。Table Bの種別は応答に出るだけです。語の解釈しだいで種別の絞り込みが外れるため、確実に絞るならstrictTypeFilteringをtrueにします。

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

Nearby Search (New)は、中心座標と半径で範囲を決めて種別で絞ります。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パッケージにあります。

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

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

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

Autocomplete (New)とセッション課金のページによると、セッションの終わり方で請求が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のポリシーと帰属表示のページが定めています。

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

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

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

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

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

写真はPlace Photos (New)で、応答に含まれる写真名を使って取得します。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の料金と実装手順、AWS内で完結させるならAmazon Location Serviceの機能と料金が比較対象です。

基幹システムや顧客管理へPlaces APIを組み込む設計、キー管理と中継サーバーの実装を外部に任せたい場合は、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)の主要規約で書き方を整理しています。

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

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

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

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

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

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

関連記事

お気に入りに入れた記事の一覧

一創の公式 SNS

X では毎朝の新着記事と IT ニュースの速報を、YouTube・TikTok・Instagram・LinkedIn・Facebook では記事の解説動画を配信しています。

この記事は以下の記事からリンクされています

資料請求

今日のトレンド記事 直近 24 時間で、いつもより多く読まれている記事

  1. 2026.11.13 テックブログ 宝くじ公式サイト不正アクセス:4,436名の対象確認とパスワード再設定、変更された仕組み
  2. 2025.04.09 コラム ダブルバーレル質問(二重質問)とは?例文と直し方、多重質問・誘導質問との違い
  3. 2026.11.14 テックブログ Gitの脆弱性6件:CVE-2026-111760の再帰クローン対策と2.56.1への更新手順
  4. 2026.11.14 テックブログ ImageMagickの脆弱性VU#580079:policy.xmlの許可リスト設定と影響判定の手順
  5. 2026.11.14 テックブログ Check Point脆弱性CVE-2026-123039:Gaiaのroot権限昇格を確かめるコマンドと侵害調査の手順

RELATED POSTS 関連記事

目次