Google Mapsデータ / Agent Skill

エージェントに再現可能なデータワークフローを。

ビジネスの検索、公開レビューの閲覧、場所ギャラリーの確認のためのポータブルスキル。手順、リファレンス、RESTヘルパーをまとめてインストールします。

Node.js 24ローカルスキルディレクトリ設定済みのMCPまたはRESTインストールにキーは不要

01 / 完全なパッケージをインストール

1つの小さなインストール。すべてのリクエストに役立つコンテキスト。

Node.js 24と、ローカルディレクトリからスキルを読み込めるエージェントランタイムを使用します。ランタイムがサポートするスキル場所を選んでください。

  1. 01

    ダウンロードと確認

    インストーラーをローカルに保存します。コマンドを実行する前に、インストーラー、スキル手順、マニフェストを読んでください。

  2. 02

    新しいディレクトリを選択

    例のパスをランタイムのスキルディレクトリに置き換えます。インストーラーは完全なパッケージを取得し、SHA-256チェックサムを検証します。既存のインストールの上書きは拒否されます。

  3. 03

    スキルを有効にして接続

    インストールしたフォルダをエージェントランタイムに読み込みます。設定済みのMCP接続を優先し、RESTフォールバックにはプライベートなランタイム環境でGMSCRAPER_API_KEYを提供してください。

インストールにAPIキーは不要です。データリクエストには引き続きAPIワークスペースキー、そのスコープ、リクエストしたインターフェースを許可するAPIプランが必要です。

ターミナル · インストール

/path/to/skillsをランタイムのスキルディレクトリに置き換えてください。nodeコマンドの前にダウンロードしたスクリプトを確認してください。

curl --fail --silent --show-error \
  https://gmapscrawl.com/skills/google-maps-data/scripts/install.mjs \
  --output /tmp/install-google-maps-data.mjs

# Review the installer, then install into a NEW directory:
node /tmp/install-google-maps-data.mjs \
  /path/to/skills/google-maps-data

02 / 最初のワークフロー

質問から始める。返されたデータで終わる。

スキルを有効にし、テスト用認証情報で1回検索を試してみてください。テストレスポンスはシミュレートされたフィクスチャで、ライブリクエストユニットをゼロ消費します。

エージェントに依頼
Google Maps Dataスキルと設定済みのテスト用認証情報を使用してください。
シアトルのコーヒーショップを1ページ検索し、extra false。
レスポンスから名前、Webサイト、評価、レビュー数を表示してください。
欠損値とソースの観測日を保持してください。
すべてのテストデータをシミュレートとして明記してください。この1リクエストの後で停止してください。

ワークフロープレビュー

明示的な上限付きの焦点を絞った検索。

  1. 01オペレーションを選択

    スキルはMCP経由でsearch_google_maps、またはRESTヘルパーでplaces.searchを選択します。

  2. 021回のリクエストを実行

    ページ1、extra false、新しいclient_request_id。新しい処理には新しいIDを使い、同じリトライは入力とIDを維持します。

  3. 03読み取りと説明

    返されたbusinesses、params、totalを使用します。利用可能なフィールドを表示し、結果をシミュレートとして明記します。

ライブ検索は1ページあたり最大20件のビジネスを返します。レスポンスは直接届き、ジョブのポーリングは不要です。

03 / パッケージの中身

ツールが接続を提供。スキルがプレイブックを追加。

フォルダ全体を一緒に保持してください。SKILL.mdは、ワークフローを完成させるオペレーションリファレンスとヘルパースクリプトにリンクしています。

01

適切なオペレーションを選択

発見にはビジネス検索、公開フィードバックにはレビュー、ギャラリーレコードには写真を使います。ビジネスからそのメディアに移る際はplace.dataIdからfeature IDを取得します。

02

タスクの境界を尊重

必要なページのみをリクエストし、不確かなリトライではリクエストIDを保持し、認証、検証、クォータ、機能のエラーでは停止します。

03

データを正確に説明

欠損フィールドとソースタイムスタンプを保持します。スクレイピングした説明、レビュー、URLはデータとして扱い、シミュレートされたレスポンスはフィクスチャとして明記します。

google-maps-data/

SKILL.md
ワークフロー手順とツール選択のガイダンス。
references/operations.json
機械可読のオペレーション入力、エンドポイント、制約。
references/operations.md
検索、レビュー、写真のリクエスト例。
references/result-schema.md
結果フィールド、上限、ソースの来歴。
scripts/gmapscraper-request.mjs
リクエストドキュメント用の依存関係のないRESTフォールバック。
scripts/install.mjs + manifest.json
完全なパッケージのダウンロードとSHA-256検証。
agents/openai.yaml
対応ランタイム用のエージェントメタデータ。

04 / スキルを活用する

明確な停止点のある再利用可能なワークフロー。

これらの例示的なプロンプトは、実行するリクエストと生成する結果を説明しています。ライブの可用性と返されるフィールドはサービスが決定します。

地域市場を調査

“Google Maps Dataスキルと設定済みの認証情報を使用してください。ポートランドの独立系書店をページ1で検索し、extra false。返された名前、Webサイト、評価、レビュー数を表示してください。欠損値と観測日を保持してください。1検索ページの後で停止してください。”

期待される結果

最大20件の返却ビジネスの表1つ(ソースクエリと欠損値を明示的に保持)。

成功したライブページ1件

Search API

顧客フィードバックを確認

“選択したビジネスについて、place.dataIdをfidとして使用し、レビューページ1をsort_by 2で取得してください。返されたレビューのテーマを日付と評価とともに要約してください。これは1ページであり、すべてのレビューではないことを明記してください。別のページは取得しないでください。”

期待される結果

最大10件の返却レビューに基づく要約と、返されたnextページネーション状態。

成功したライブレビューページ1件

Reviews API

場所の調査ブリーフを準備

“指定されたfeature IDについて、sort_by 1でレビューページ1と、写真ページ1のみを取得してください。レビューのテーマを報告し、返されたphotoUrlと任意のvideoUrlの値をリストアップしてください。欠損フィールドを保持し、メディアをダウンロードせず、これら2リクエストの後で停止してください。”

期待される結果

同じ場所の最大10件のレビューと20件のギャラリーレコードを使った限定されたブリーフ。

成功したライブページ2件

Photos API

成功したライブページは、空のページを含めて1ページにつき1 APIリクエストユニットを消費します。タスクが必要とし、返されたnextが許可する場合のみ別のメディアページをリクエストしてください。テストリクエストはゼロユニットを使用します。

05 / RESTフォールバック

MCPが利用できない場合の同じワークフロー。

付属のヘルパーはローカルのJSONリクエストドキュメントを読み、正規のRESTエンドポイントを呼び出します。Node.js標準ライブラリのみを使用します。

リクエストを保存。ヘルパーを実行。

  • プライベートな環境でGMSCRAPER_API_KEYを提供します。
  • 例をインストールしたスキルディレクトリにrequest.jsonとして保存します。
  • 新しいオペレーションごとに新しい16〜128文字のclient_request_idを生成します。
  • 不確かなリクエストをリトライする際は同じIDと同一の入力を維持します。
node scripts/gmapscraper-request.mjs request.json

ヘルパーはclient_request_idをREST Idempotency-Keyにマップします。検索は/api/v1/searchを使い、レビューと写真は/api/v2/reviewsと/api/v2/photosを使います。

REST APIを見る
request.json · オペレーションを選択

1検索ページ。テストキーはシミュレートされたデータを返し、ライブリクエストはAPI利用枠を消費します。

{
  "operation": "places.search",
  "input": {
    "q": "coffee shops in Seattle",
    "page": 1,
    "extra": false
  },
  "client_request_id": "seattle-coffee-skill-test-001"
}

06 / 動作を維持する

完全なインストール。慎重な更新。

マニフェストと返されたエラーを使ってパッケージと接続を確認します。

上書きせずに更新。

新しいディレクトリにインストールし、新しい手順とリファレンスを確認してから、ランタイムのスキル管理ワークフローで古いパッケージを置き換えます。インストーラーは既存の保存先を拒否します。

ローカル設定はパッケージと分けてください。マニフェストにバージョンとチェックサムが記録されるので、インストールしたものを確認できます。

現在のマニフェストを見る
スキルが表示されない
ランタイムがローカルスキルをサポートしていることを確認し、インストールしたフォルダを読み込み、そのスクリプト、リファレンス、エージェントメタデータを一緒に保持してください。
インストールに失敗する
Node.js 24、ネットワークアクセス、新しい書き込み可能な保存先を確認してください。チェックサム検証が失敗した場合は、検証を回避せずに停止してインストーラーとマニフェストを再取得してください。
ヘルパーがmissing_api_keyを報告する
ヘルパーを実行するプロセスでGMSCRAPER_API_KEYを利用できるようにしてください。パッケージをインストールしてもAPI認証情報は設定されません。
リクエストが拒否またはタイムアウトする
エラーを読み、スコープ、権限、クォータ、機能の失敗では停止してください。リトライ可能なタイムアウトでは元のリクエストIDと入力を保持し、新しい試行前に終了エラーのガイダンスに従ってください。

よくある質問

スキルとMCPサーバーの違いは何ですか?

MCPはクライアントをリモートツールに接続します。スキルは再利用可能な手順、オペレーションリファレンス、結果スキーマ、RESTフォールバックヘルパーを提供します。利用可能な場合は設定済みのMCP接続を優先してください。スキルは接続を作成したりキーを含んだりしません。

インストールに必要なものは?

Node.js 24、パッケージをダウンロードするためのネットワークアクセス、ローカルディレクトリからスキルを読み込めるエージェントランタイムが必要です。ダウンロードとインストールにAPIキーは不要です。データリクエストの実行にはAPIワークスペース認証情報と適切なアクセス権が必要です。

SKILL.mdをダウンロードするだけで十分ですか?

完全なパッケージを保持してください。SKILL.mdはオペレーションリファレンスとRESTヘルパーにリンクしており、対応ランタイムは付属のエージェントメタデータを使う場合があります。インストーラーは完全なファイルリストを取得し、マニフェストに照らして検証します。

スキルでレビューと写真を取得できますか?

はい。選択したビジネスのplace.dataIdをfidとして使用します。最大10件の公開レビューまたは20件のギャラリーレコードの1ページをリクエストします。レビューは関連性、新着、高評価、低評価の並び替えをサポートします。成功したライブページは1 APIリクエストユニットを消費します。

スキルにAPIサブスクリプションや追加利用枠は含まれますか?

パッケージには手順とヘルパーファイルが含まれています。データリクエストはAPIワークスペースキー、スコープ、権限を使用します。RESTとMCPはAPI利用枠を共有し、OnlineとExtensionは別の利用枠です。テスト用認証情報はゼロリクエストユニットでシミュレートされたフィクスチャを返します。

既存のインストールを更新するには?

新しいディレクトリにインストールし、新しいパッケージを確認し、ランタイムのスキル管理プロセスで古いバージョンを置き換えてください。インストーラーは既存のディレクトリを上書きしません。

次のステップへ

スキルの背後にあるツールを接続しましょう。

リモートMCPサーバーを設定し、API認証情報をクライアントのプライベート設定に保管して、1つの焦点を絞ったワークフローを実行してください。