「近くのカフェを探して」——AIエージェント にこう頼んだとき、エージェントがやるべきことは意外と単純です。

1つは「検索したい意図」（例: coffee/ramen）。もう1つは「検索の起点になる位置」です。後者はOSの位置情報やアプリ側の設定、あるいはユーザー入力で用意して、エージェントに渡します（goplacesが勝手に現在地を特定するわけではありません）。

設定次第では、Claude やOpenCode 、Codex のようなエージェントがローカルでシェルコマンドを実行できます。つまり、位置を入力として受け取り、外部APIで検索/経路案内を返すCLIが1つあれば、それだけで「位置情報スキル」を組み込めます。

そこで今回は、Google Places/Routesを叩けるCLIであるgoplaces を使って、この部分を安定して回すための実装パターンをまとめます。CLIを「エージェントが呼び出すプロトコル」として設計する観点は、先に「Agentic CLI Design: CLIをAIエージェント向けプロトコルとして設計する7つの原則 」で整理しました。本記事はその具体例です。

goplaces とは

goplacesは、Google Places API (New) とRoutes API のためのモダンなCLIツールです。作者のPeter Steinberger氏 （@steipete）は、OpenClaw の作者としても知られています。

goplacesは、言ってしまえば「Google Maps PlatformのAPIラッパー」です。ここが大事で、位置情報の知識や独自データを持っているわけではありません。

それでもgoplacesを使う価値があるのは、ラッパー部分が「エージェントが呼び出す道具」としてちょうど良い厚みで整備されているからです。Agent Skills（エージェントが参照するスキル定義ファイルの仕組み）に載せるなら、CLIはかなり相性が良いです。

主な特徴:

• Agent Skills向け設計: --json出力、明確な終了コード（コマンドの成否を示す数値）、--helpによる自己文書化
• 最新API対応: Places API (New)とRoutes APIに最初から対応
• 豊富な機能: テキスト検索、近隣検索、ルート検索、経路案内、写真取得

自分の中での位置づけは「APIを直接叩く前の、安定したCLIの薄い層」です。

セットアップ

インストール

1
2
3
4
5

# Homebrew（macOS/Linux）
brew install steipete/tap/goplaces

# または Go
go install github.com/steipete/goplaces/cmd/goplaces@latest

APIキーの設定

Google Cloud Console で「Places API (New)」と「Routes API」を有効化し、APIキーを取得します。

1

export GOOGLE_PLACES_API_KEY="your-api-key-here"

⚠️ Places APIは従量課金です。料金ページ を確認し、予算アラートを設定してください。

AIエージェントからの利用例

基本: 場所の検索

AIエージェントが「渋谷周辺のカフェを探して」というリクエストを受けた場合、以下のコマンドを実行します。

ここで使う--lat/--lngは、ユーザーが明示的に渡した位置情報や、端末/アプリ側の位置情報機能（OSの位置情報、ブラウザのGeolocation APIなど）で取得した値を想定しています。

ここでの狙いは、出力をJSON（構造化されたデータ形式）にして、エージェント側が確実にパースできるようにすることです。

1
2
3
4
5
6
7
8

goplaces search "coffee" \
  --lat 35.6595 \
  --lng 139.7004 \
  --radius-m 500 \
  --min-rating 4.0 \
  --open-now \
  --limit 5 \
  --json

出力（JSON）:

以下はイメージです（フィールド名や構造はバージョンで変わる可能性があります）。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
  "places": [
    {
      "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4",
      "display_name": "Blue Bottle Coffee Shibuya",
      "formatted_address": "東京都渋谷区神南1-7-11",
      "rating": 4.5,
      "user_rating_count": 234,
      "types": ["cafe", "food", "point_of_interest"]
    }
  ]
}

AIエージェントはこのJSONを解析し、ユーザーに自然言語で回答します。

経路案内

「東京駅から渋谷駅への行き方を教えて」:

1
2
3
4
5

goplaces directions \
  --from "東京駅" \
  --to "渋谷駅" \
  --steps \
  --json

近隣検索

「現在地周辺のレストラン」:

1
2
3
4
5
6
7

goplaces nearby \
  --lat 35.6812 \
  --lng 139.7671 \
  --radius-m 500 \
  --type restaurant \
  --limit 10 \
  --json

コマンドの組み合わせ

Unixパイプ（|）を使って、検索結果をさらに処理できます。ここではjq （JSONを加工するCLI）を使います。

jqが入っていない場合は先にインストールしてください（macOSなら以下で入ります）。

1

brew install jq

1
2
3
4
5
6
7

# 評価4.5以上のカフェだけ抽出
goplaces search "coffee" --lat 35.6595 --lng 139.7004 --json | \
  jq '.places[] | select(.rating >= 4.5)'

# 検索結果の場所への経路を取得
PLACE=$(goplaces search "Blue Bottle Coffee" --lat 35.6595 --lng 139.7004 --json | jq -r '.places[0].formatted_address')
goplaces directions --from "渋谷駅" --to "$PLACE" --json

Claude Code / OpenCode / Codex での活用

※コマンド実行の可否は、利用しているエージェント/設定/権限に依存します（サンドボックスや承認フローが入る場合もあります）。

ここで言うClaude Codeは、Claude Code を指します。

AGENTS.md への追記例

プロジェクトの指示ファイル（例: AGENTS.md）に以下を追記することで、AIエージェントにgoplacesの使い方を教えられます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

## 位置情報スキル

位置情報が必要な場合は `goplaces` コマンドを使用してください。

### 場所の検索
```bash
goplaces search "検索クエリ" --lat 緯度 --lng 経度 --radius-m 半径 --json
```

### 経路案内
```bash
goplaces directions --from "出発地" --to "目的地" --json
```

### 利用可能なオプション
- `--min-rating`: 最低評価（例: 4.0）
- `--open-now`: 現在営業中のみ
- `--limit`: 最大結果数
- `--type`: 場所の種類（cafe, restaurant, etc.）

詳細は `goplaces --help` を参照。

実際の対話例

ユーザー: 「渋谷駅周辺で評価4以上のラーメン屋を3件教えて」

AIエージェント（内部でコマンド実行）:

1
2
3
4
5
6
7

goplaces search "ramen" \
  --lat 35.6580 \
  --lng 139.7016 \
  --radius-m 500 \
  --min-rating 4.0 \
  --limit 3 \
  --json

AIエージェント（ユーザーへの回答）:

渋谷駅周辺で評価4以上のラーメン屋を3件見つけました：

1. 一蘭 渋谷店 ⭐4.3 (1,234件)

   • 住所: 東京都渋谷区宇田川町25-5
   • 現在営業中

2. AFURI 渋谷 ⭐4.5 (892件)

   • 住所: 東京都渋谷区神南1-20-5
   • 現在営業中

3. 麺屋武蔵 渋谷店 ⭐4.2 (567件)

   • 住所: 東京都渋谷区道玄坂2-6-1
   • 現在営業中

トラブルシューティング

APIキーエラー

Error: GOOGLE_PLACES_API_KEY environment variable is required

→ 環境変数を設定してください。

APIが有効化されていない

Error: Google Places API (New) is not enabled

→ Google Cloud Console でAPIを有効化してください。

デバッグ

詳細なログを出力:

1

goplaces search "coffee" --lat 35.6595 --lng 139.7004 --verbose

まとめ

goplaces は、位置（緯度・経度や地点名など）を入力として、周辺検索や経路案内を実行できるCLIツールです。

• シンプル: brew installしてすぐ使える
• Agent Skills向け: JSON出力、明確な終了コード、自己文書化
• 保守不要: ツールのアップデートで自動的に最新API対応

Agent Skills としてスキルディレクトリ（例: .agents/skills/ や ~/.agents/skills/）に配置すれば、Claude CodeやOpenClawから位置情報スキルとして利用できます。

参考リンク

• goplaces GitHub リポジトリ
• goplaces 公式サイト
• Google Places API (New) ドキュメント
• Google Routes API ドキュメント
• Claude Code
• OpenCode
• Codex
• OpenClaw
• Agent Skills
• anthropics/skills
• jq