👌

Cursorで始める外部API連携：仕様理解から実装補助までAIの使いどころを探る

mikamik1218

2025/07/30に公開

 はじめにはじめまして、カンリーエンジニア部の三上です。

カンリーのメインプロダクトであるカンリー店舗集客の開発に携わってから早いもので3年目を迎えました。

カンリー店舗集客はGoogle Business Profileを主軸に様々な媒体の店舗情報を一元管理するシステムとして作られました。FacebookやInstagramの他にApple Business Connect、Yahoo!プレイスと、連携できる媒体がどんどん拡大してきています。

私自身Apple Business ConnectとYahoo!プレイスの連携機能の導入に携わり、リニューアルプロジェクトや運用を通してその他の媒体も一通り触ってきました。
媒体連携を実装するにあたって外部媒体のAPI仕様を把握することが不可欠です。当時はすべて自力でドキュメントを読み漁り、パラメーターを変えてAPIを叩きまくるという泥臭い手順で仕様理解を深めていました。
しかし昨今のAIの進化は凄まじく、社内でも気軽にAI開発支援ツールを利用できる環境になりました。

今ならもっと楽に色々なことができるのでは...？

そこで今回は、外部連携機能の開発においてAI開発支援ツールを活用することでどれだけ調査や開発が効率化出来るか検証してみたいと思います。

 前提





対象媒体
Google Business Profile

AIツール
Cursor バージョン: 1.2.4

CursorはVSCodeベースのエディタで、AIコーディングアシスタント機能が搭載されています。自然言語の指示からコード補完、ドキュメント理解の支援などが可能です。普段の開発で使っているため、今回はこのツールのAgentモードを利用します。

余計なコンテキストを読み込まないように、ワークスペースは空の状態にしておきます。

 Cursorで全体像を把握してみる
 概要を調べるいきなり詳細から入るのは辛いので、まずは公式ドキュメントからガイドページを渡してCursorに概要をまとめてもらいました。
@https://developers.google.com/my-business/content/overview?hl=ja

Google Business Profile APIについて知りたいです。公式ドキュメントの概要ページから主なエンドポイントと利用手順をまとめてください。
出力内容全文はこちらGoogle Business Profile APIsについて、公式ドキュメントの概要ページから主な情報をまとめさせていただきます。

 Google Business Profile APIs の概要Google Business Profile APIsは、ビジネスプロフィールアカウントとビジネスデータを管理するためのプログラミングインターフェースです。販売者や販売担当者が、Googleでのビジネスデータの表示方法や共同管理権限をプログラム的に管理できます。

 主な機能
ビジネス情報の管理: 写真、営業時間、ウェブサイトリンクなどの基本情報

投稿の作成: ビジネスに関する投稿の作成と管理

クチコミの管理: ユーザーレビューのデータ管理

メディアのアップロード: 写真や動画のアップロード

分析情報の取得: ビジネスのパフォーマンスデータ

管理者の管理: 共同管理者の権限管理

リアルタイム通知: 変更通知の管理

 利用条件APIにアクセスするには以下の条件を満たす必要があります：
有効なGoogleアカウント
ビジネス上の正当な理由
有効なGoogle Cloudプロジェクト
ビジネスのウェブサイトの有効なURL

 主なエンドポイント（推測される主要なAPI）公式ドキュメントから推測される主要なエンドポイント：

 アカウント管理アカウントの取得・作成
アカウントの更新・削除

 ビジネス情報管理ビジネス情報の取得・更新
場所情報の管理
営業時間の設定

 コンテンツ管理投稿の作成・更新・削除
メディアのアップロード
クチコミの取得・管理

 分析・レポートパフォーマンスデータの取得
分析情報の取得

 利用手順基本セットアップ
Google Cloudプロジェクトの作成
APIの有効化
OAuth認証のセットアップ
OAuth 2.0認証の実装
アクセストークンの取得
ビジネス情報のセットアップ
ビジネスアカウントの作成
場所情報の設定
APIの実装
クライアントライブラリの使用
APIエンドポイントの呼び出し

 制限事項APIにはレート制限が適用されます
利用には審査が必要です
ビジネス目的での使用が必須です

 関連するAPI
Google Maps Platform: ローカルビジネス情報の取得

AdWords API: 手動住所表示オプションの管理
このAPIは、ビジネスのオンラインプレゼンスを効率的に管理し、Google検索やGoogleマップでの可視性を向上させるために使用されます。
参考: Google Business Profile APIs 公式ドキュメント
操作できるコンテンツがなんとなくわかりました。

次にAPIリファレンスページを渡すとさらに詳細な情報を教えてくれました。
@https://developers.google.com/my-business/ref_overview?hl=ja

公式ドキュメントのAPIリファレンスからAPIを利用してできることとできないことをまとめてください。
出力内容全文はこちらGoogle Business Profile APIsについて、公式ドキュメントのAPIリファレンスを基に、できることとできないことをまとめます。

 Google Business Profile APIsでできること
 1. Account Management API
Googleでのビジネスアカウントの管理
ビジネスアカウントとビジネス情報にアクセスできるユーザーの管理
アカウントの作成、取得、一覧表示、更新
管理者の作成、削除、一覧表示、更新
招待の管理（承諾、拒否、一覧表示）

 2. Business Calls API
自社への電話問い合わせの管理
各種インサイトの収集（店舗への不在着信件数など）
通話履歴の管理
Google広告アカウントとの連携による「広告経由の通話数」コンバージョンの確認

 3. Lodging API
宿泊関連データの管理（施設の設備やポリシーなど）
ホテルなどの宿泊サービス提供ビジネス向け
宿泊施設情報の取得・更新

 4. Place Actions API
ビジネスの位置情報アクションリンクの管理
予約、席の予約、料理のデリバリー注文などの操作へのリダイレクト機能

 5. Notifications API
指定したアカウントの通知設定の管理

 6. Verifications API
ビジネスのオーナー確認
販売者の声の有無の確認
検証オプションの取得
検証の完了

 7. Business Information API
ビジネス情報の管理
ロケーション情報の作成、削除、取得、更新
属性の管理
カテゴリの管理
チェーンの検索・取得

 8. Q&A API
ビジネスに関する質問と回答の管理
質問の作成、削除、一覧表示、更新
回答の削除、一覧表示、更新

 9. Business Profile Performance API
ビジネスリスティングのパフォーマンス分析情報の取得
日次メトリクスの時系列データの取得
複数のDailyMetricsを1つのAPIリクエストでフェッチ

 10. Google My Business v4.9 API
ビジネスプロフィールに関連するその他の機能
投稿、レビュー、メディアなどの管理

 Google Business Profile APIsでできないこと
 1. 直接的なSEO操作
Google検索結果での順位を直接操作することはできません
検索アルゴリズムへの直接的な影響は制限されています

 2. 競合他社の情報取得
他のビジネスの詳細情報を取得することはできません
競合分析のための他社データへのアクセスは制限されています

 3. リアルタイムの顧客データ
個別の顧客の詳細情報や行動データへのアクセスは制限されています
プライバシー保護のため、個人情報の取得は制限されています

 4. 自動化された投稿
完全に自動化された投稿の作成は制限される場合があります
スパム防止のため、投稿の頻度や内容に制限があります

 5. 直接的な売上データ
実際の売上金額や取引データへのアクセスは提供されていません
パフォーマンス指標は提供されますが、具体的な売上データは含まれません

 6. 地理的制限の回避
特定の地域でのみ利用可能な機能を他の地域で使用することはできません
APIの利用可能地域は制限されています

 7. 無制限のAPI呼び出し
APIの使用には制限（クォータ）があります
過度なAPI呼び出しは制限される場合があります
これらのAPIは、ビジネス情報の管理とパフォーマンス分析に特化しており、Googleのポリシーとプライバシー保護の範囲内で利用することができます。
参考: Google Business Profile APIs公式ドキュメント
機能別に情報をまとめてくれているので全体を俯瞰して把握することができました。

 特定のリソースに絞ってまとめるさらに開発で利用しそうなAPIを絞り込めるようにしてみましょう。今回は例として、カンリー店舗集客で一番よく使うであろうv1.locationsリソースについて調べてみることにします。
@https://developers.google.com/my-business/reference/businessinformation/rest/v1/locations?hl=ja

v1.locationsリソースに関わるエンドポイントを一覧にしてください。
出力内容全文はこちらGoogle Business Profile APIのv1.locationsリソースに関わるエンドポイントを一覧にいたします。

 v1.locationsリソースのエンドポイント一覧
 メインのlocationsエンドポイント

メソッド
エンドポイント
説明


delete
DELETE /v1/locations/{name}
ビジネスを削除します

get
GET /v1/locations/{name}
指定したビジネスを返します

getAttributes
GET /v1/locations/{name}/attributes
指定したビジネスに設定されているすべての属性を検索します

getGoogleUpdated
GET /v1/locations/{name}/googleUpdated
指定したビジネスのGoogleによって変更されたバージョンを取得します

patch
PATCH /v1/locations/{name}
指定したビジネスを更新します

updateAttributes
PATCH /v1/locations/{name}/attributes
指定したビジネスの属性を更新します


 関連するサブリソースエンドポイント
 accounts.locations

メソッド
エンドポイント
説明


create
POST /v1/accounts/{parent}/locations
新しいビジネスを作成します

list
GET /v1/accounts/{parent}/locations
アカウント内のビジネス一覧を取得します


 locations.attributes

メソッド
エンドポイント
説明


getGoogleUpdated
GET /v1/locations/{name}/attributes/googleUpdated
Googleによって更新された属性を取得します


 その他の関連エンドポイント
 検索・カテゴリ関連
categories.list - 利用可能なビジネスカテゴリを取得

attributes.list - 利用可能な属性を取得

chains.search - チェーンビジネスを検索

googleLocations.search - Googleの場所データを検索

 認証・検証関連
locations.fetchVerificationOptions - 認証オプションを取得

locations.getVoiceOfMerchantState - 認証状態を取得

locations.verify - ビジネスを認証

locations.verifications.complete - 認証プロセスを完了

locations.verifications.list - 認証履歴を取得
これらのエンドポイントを使用することで、Google Business Profileのビジネス情報を包括的に管理できます。
参考: Google Business Profile API - locations リソース
一通り関連するAPIが網羅されていることが確認できました。

特に新しい媒体連携機能を導入する際は、ここまでに調べた情報をあらかじめチーム内で共有しておくと機能設計に役立ちそうです。
ただし、出力された情報の確認はきちんとやっておきましょう。上記のCursorの回答で一部のAPIの情報が欠けていたり、エンドポイントの表記が誤っている箇所がありました。完璧に網羅されているわけではないため、自身でドキュメントを読む際の足がかりとして活用するのが良さそうです。

 API実行に使えるPostman Collectionを生成する下調べが済んだところで、次は実際にAPIを動かしてみましょう。

普段の開発・運用の中でもAPIを直接実行したい場面があります。そんな時に備えてPostmanのCollectionを用意します。開発で利用している認証情報をそのまま使って実行できるようにお願いしてみました。
@https://developers.google.com/my-business/reference/businessinformation/rest/v1/locations?hl=ja

Google Business Profile APIsのリファレンスページを添付しました。このページの「メソッド」に記載されているエンドポイントをPostmanで実行できるようにしておきたいです。Collectionインポートできる形式でJSONファイルを作成してください。

APIアクセストークンの取得はRefresh Tokenを利用する形にしてください。

OAuth 2.0認証に必要なCredencialsは取得済みです。
いくつか改善点があり3往復くらいして出来上がったファイルがこちら。
https://github.com/mikamik1218/cursor-gbp-sample/tree/main/postman-collection
READMEの手順に沿ってセッティングし、弊社のGBPの情報を取得してみましょう。
うまく疎通できました🎉
各APIの実行前にアクセストークンを自動的に取得して、すぐに目的のAPIを手元で試せるようになっています。Postmanさえインストールしていれば特別な環境を用意せずともAPIを実行出来るので、オンボーディングにも役立ちそうです。

 Cursorに制約を踏まえて型定義をさせる最後に、設計・実装フェーズでの活用を試してみます。
GoogleではBusiness Profile APIsを含むAPIクライアントライブラリが提供されていますが、実際の開発要件に照らすと、ライブラリが用意しているデータ型では少し心許ないケースもあります。
例えば、店舗情報を扱ううえで厄介なのが住所です。

日本国内の店舗のみであればまだ扱いやすいですが、カンリー店舗集客では海外店舗も取り扱っているため、各国ごとに住所形式の違いを考慮する必要があります。
そこで今回は、Cursorに対して「この仕様に沿って、どんなクラス構造が適しているか？」という視点で問いかけてみることにしました。
日本とアメリカの住所に対応できるようにしたいです。

Google Business Profile APIが定義する住所項目は以下のドキュメントに記載されています：

@https://developers.google.com/my-business/reference/businessinformation/rest/v1/accounts.locations?hl=ja#postaladdress

また、住所の形式は以下のガイドラインに準拠する必要があります：

@https://support.google.com/business/answer/6397478?hl=ja
この情報をもとに、Go言語で住所型の構造体（Address）を定義してください。

日本とアメリカそれぞれの住所形式を扱えるようにしてください。

フィールドには適切なデータ型・コメントを付けてください。
作成した構造体は address/address.go に保存してください。必要に応じて address ディレクトリをワークスペース直下に作成してください。
コードが出来上がりました！

https://github.com/mikamik1218/cursor-gbp-sample/tree/main/address
ドキュメントの構造や仕様を元に、Goの構造体に自然にマッピングしてくれました。

特に「国ごとの必須項目の違い」や「文字列の形式制約」に対して、手動でやると見落としがちな点もカバーされている印象です。
例えばアメリカの住所であれば以下のように 郵便番号が XXXXX または XXXXX-XXXX の形式のみを許容します。
// validateUSAddress validates US address format
func (a *Address) validateUSAddress() []ValidationError {
	var errors []ValidationError

	// Validate postal code format (5 digits or 9 digits: XXXXX or XXXXX-XXXX)
	postalCodeRegex := regexp.MustCompile(`^\d{5}(-\d{4})?$`)
	if a.PostalCode != "" && !postalCodeRegex.MatchString(a.PostalCode) {
		errors = append(errors, ValidationError{
			Field:   "PostalCode",
			Message: "US postal code must be in format XXXXX or XXXXX-XXXX",
		})
	}
    ...
}
Google Business Profileに対してAPIリクエストする際は、以下のようにするだけでAPIのフォーマットに変換できます。
// 日本の住所を設定
addr.SetJapaneseAddress(prefecture, city, address, postalCode, building)

apiFormat := addr.ToGoogleBusinessProfile()
もちろん細かい点は調整する必要がありますが、基本的な実装方針としては問題なく利用できそうです。

現在は日本とアメリカに限定してハードコードしてしまっているので、これをベースにファクトリーパターンなどを取り入れることでより拡張性が高く実用的になると感じました。

 今回のまとめCursorを使って以下のようなことができることがわかりました。
ドキュメントを渡すだけでAPIの概要や設計方針を効率的に把握
Postman Collectionも実行可能な形に落とし込める
データ構造のクラス設計にも初期足場として十分有用

 特に効果があったところAPI仕様の全体像の把握
パラメーターやエンドポイントの洗い出し
構造体の雛形生成

 注意したい点出力結果の精度には限界があるので最終的な確認・精査は不可欠
特に「抜け漏れ」「用語の曖昧さ」には要注意

 AIツールの使いどころを見極めようCursorはあくまで「優秀な助手」として活用するようにしましょう。

すべてを任せるのではなく、自分の思考を補強するツールとしてうまく活用することで、開発効率も理解の深さも大きく変わると実感しました。

 おわりにまだまだ発展途上の部分もありますが、同じように外部APIの仕様に悩んでいる方にとって、少しでも役立てば嬉しいです！


対象媒体	Google Business Profile
AIツール	Cursor バージョン: 1.2.4

メソッド	エンドポイント	説明
delete	`DELETE /v1/locations/{name}`	ビジネスを削除します
get	`GET /v1/locations/{name}`	指定したビジネスを返します
getAttributes	`GET /v1/locations/{name}/attributes`	指定したビジネスに設定されているすべての属性を検索します
getGoogleUpdated	`GET /v1/locations/{name}/googleUpdated`	指定したビジネスのGoogleによって変更されたバージョンを取得します
patch	`PATCH /v1/locations/{name}`	指定したビジネスを更新します
updateAttributes	`PATCH /v1/locations/{name}/attributes`	指定したビジネスの属性を更新します

メソッド	エンドポイント	説明
create	`POST /v1/accounts/{parent}/locations`	新しいビジネスを作成します
list	`GET /v1/accounts/{parent}/locations`	アカウント内のビジネス一覧を取得します

メソッド	エンドポイント	説明
getGoogleUpdated	`GET /v1/locations/{name}/attributes/googleUpdated`	Googleによって更新された属性を取得します

カンリーテックブログPublication

株式会社カンリーは「店舗経営を支える、世界的なインフラを創る」をミッションに、店舗アカウントの一括管理・分析SaaS「カンリー店舗集客」の開発・提供、他複数のサービスを提供しております。技術系以外のnoteはこちらから note.com/canly

はじめに

前提

Cursorで全体像を把握してみる

概要を調べる

Google Business Profile APIs の概要

主な機能

利用条件

主なエンドポイント（推測される主要なAPI）

アカウント管理

ビジネス情報管理

コンテンツ管理

分析・レポート

利用手順

制限事項

関連するAPI

Google Business Profile APIsでできること

1. Account Management API

2. Business Calls API

3. Lodging API

4. Place Actions API

5. Notifications API

6. Verifications API

7. Business Information API

8. Q&A API

9. Business Profile Performance API

10. Google My Business v4.9 API

Google Business Profile APIsでできないこと

1. 直接的なSEO操作

2. 競合他社の情報取得

3. リアルタイムの顧客データ

4. 自動化された投稿

5. 直接的な売上データ

6. 地理的制限の回避

7. 無制限のAPI呼び出し

特定のリソースに絞ってまとめる

v1.locationsリソースのエンドポイント一覧

メインのlocationsエンドポイント

関連するサブリソースエンドポイント

accounts.locations

locations.attributes

その他の関連エンドポイント

検索・カテゴリ関連

認証・検証関連

API実行に使えるPostman Collectionを生成する

Cursorに制約を踏まえて型定義をさせる

今回のまとめ

特に効果があったところ

注意したい点

AIツールの使いどころを見極めよう

おわりに

Discussion