連携

開発者ガイド

HeyYumi は、一人のキュレーターがまとめたノートのような API です。キー一つで精製された店舗(ワンセット)にアクセスできます。営業時間・メニュー・価格帯・評価・活動の最新性・信頼度はもちろん、駐車(種類・料金・案内)・ビーガン/ベジタリアンの食事インデックス・対応できる外国語・AI の一行要約まで、整理された状態で。座標がなくても「Hongje-dong」のような地域名を /regions でコード・座標に変換して、周辺検索にそのまま使えます(同名の洞は sido/sigungu で区別)。読み取りだけでなく、同じキーで予約リクエストや「今それ、在庫ありますか?」といったリアルタイムの問い合わせ(在庫・待ち時間・即時着席)まで送り、店主が 5 分以内に答えるようにできます。

このガイドは、API・MCP・CLI の 3 つの連携方法を一か所で扱います。連携の仕方は方法ごとに違い、その下のデータ・課金・スコア・エラーは 3 つとも共通です。

API キーを取得 →API リファレンス →プレイグラウンドですぐ呼び出し →MCP サーバー →CLI →OpenAPI 仕様

① 連携: 3 つ、それぞれ違う

何を作るにしても、以下の 3 つのいずれかでユミにつながります。それぞれ性格が違うので、連携の仕方も異なります。詳しい画面は各カードのリンクへ。

MCP運用中

Claude・Cursor・ChatGPT・Perplexity のようなエージェントに接続します。ChatGPT はプラグインから検索・接続、その他はサーバー URL。Google ログインまたは API キーで認証します。

01ChatGPT: プラグインで HeyYumi を検索・接続
02Claude・Cursor・Perplexity: MCP サーバー URL を追加
03Google ログイン(OAuth)または Bearer キー

server url

https://mcp.heyyumi.ai/mcp

MCP 連携を見る →

API運用中

製品・バックエンドに REST で組み込みます。サーバー間連携。

01ダッシュボードでキーを発行
02ヘッダーに Authorization: Bearer <KEY>
03/api/v1/places に最初の呼び出し

curl

curl -H "Authorization: Bearer hmp_xxx" \
  "https://api.heyyumi.ai/api/v1/places?keyword=burger"

API 連携をすべて見る →

CLI準備中

Claude Code・Codex のようなターミナルエージェント用。インストール → ログイン → MCP に自動登録。

01npm i -g @heyyumi/cli
02heyyumi login
03heyyumi mcp install

terminal

npm i -g @heyyumi/cli
heyyumi login
heyyumi mcp install

CLI 連携を見る →

② 共通: 3 つの方法すべて同じ

どの方法で連携しても、以下は同じように適用されます。ユミがどんなデータを返すか、フィールドに応じてトークンがどう消費されるか、スコアをどう読むか、エラーが何を意味するか。

フィールド選択 · 段階課金

一度にすべてのデータを返すわけではありません。fields パラメータで受け取るフィールドを選びます。ティア名(core/contact_hours/quality/edge/media)・all・個別のフィールド名をカンマで入れます。未指定の場合は core です。

core1 tokenCore (identity & location)
id, name, category, categoryLabel, location, address, regionCode, confidence, sourceCount, possiblyClosed, lastSeenAt
contact_hours2 tokensContact & hours
phone, homepage, bookingUrl, yumiReservable, reservationChannels, snsLinks, businessHours, temporaryClosures, is24h
quality2 tokensQuality & price
rating, reviewCount, latestReviewDate, freshnessScore, dataQuality, price, menuSummary, openNow, closureSignal, promotion, photoCount, nearestStation
edge4 tokensMoat (access & context)
accessHints, recommendedFor, atmosphere, menu, serviceAttributes, dietary, atmosphereScores, aiSummary, ownerIntro, influencerFeatures, culturalAssociations, legacy, reputation
media8 tokensPhotos (rich media)
photos

課金はリクエストごとです。呼び出し単価 = リクエストしたフィールドの最上位ティア(page_size は単価に影響しません)。月間上限はトークンの合計で消費され、その範囲内では好きなだけ自由に使えます(1 日の上限なし)。乱用防止は価格ではなく上限で行います。プランごとの 1 分あたりリクエスト数(rpm)制限(超過時は 429 + Retry-After)、検索条件ごとの結果ウィンドウ(Starter 1,000 · Pro 5,000)、直近 30 日の distinct 店舗上限(Starter 10,000 店 · Pro 40,000 店; 無料 3,000 店)。distinct 上限は「異なる店舗数」だけを数えるので、同じ店舗を何度返しても 1 店としてカウントされます(繰り返しの提供は累積されず、データセットを丸ごと収集するときだけ引っかかります)。全体・大量のデータはページネーションではなく Bulk Export · データライセンスの対象です(規約の許容利用ポリシーを参照)。

スコアの読み方: 最新性・信頼度

ユミは「おすすめしてよい店か」を一つの合算スコアに決めつけません。代わりに判断に必要な素材スコアを透明に示し、最終的なおすすめの可否は受け取る側がサービスのポリシーに合わせて決めます。すべてのスコアは、高いほど良いように統一されています。

freshnessScore · 活動の最新性 (0〜1, 高いほど最近)

店舗の最近の活動シグナルがどれだけ新しいかを、ユミが 0〜1 で算出した値です。満点は 1.0。

0.8 – 1.0最近(約 4 か月以内)の活動シグナルが明確で活発。
0.5 – 0.8約 4〜9 か月、普通。
0.2 – 0.5約 9〜14 か月。直接の確認をおすすめします。
0 – 0.2約 14〜18 か月以上。活動シグナルが弱い。
null(なし)最新性を算出するシグナルが不足していたという意味であって、閉店シグナルではありません。

confidence · データ信頼度 (0.3〜0.98, 高いほど信頼)

複数の出所が同じ店舗にまとまり、識別情報(電話・座標・住所・名前)が噛み合うほど高くなる、クロス検証スコアです。上限は 0.98。

0.9 – 0.98複数の出所でクロス確認、非常に高い。
0.75 – 0.9クロス確認済み、高い。
0.6 – 0.75単一の出所、または識別情報の一部で普通。韓国の地図の特性上、片方にしか載らない店舗が多いため、単一の出所がそのまま低品質を意味するわけではありません。
0.3 – 0.6識別情報が少ない、または出所間で名前が食い違うため、使用前の確認をおすすめします。

閉店が確認された店舗は、おすすめの対象から除外することを原則としています。ただし最新性・信頼度が低いからといって閉店と決めつけないでください。実際に営業中の店舗であることもあります。この 2 つのスコアは「ふるい分けの基準」であって「閉店の判定」ではありません。

認証

キーはアカウントに属します。キーはハッシュでのみ保存され、平文は発行時に一度だけ表示されます。REST は Authorization: Bearer <KEY>(または X-API-Key)で認証します。MCP(mcp.heyyumi.ai · 専用リポジトリ map3-mcp)は両方に対応します。Cursor のように同じ Bearer キーを入れても、ChatGPT(プラグインディレクトリで HeyYumi を検索・接続)・Claude・Perplexity(カスタムコネクターにサーバー URL)のように Google ログイン(OAuth)でキーなしで接続しても構いません。URL の ?api_key= はログに残りやすいため非推奨・廃止予定です。

エラーコード

400不正なパラメータ / bulk_export_required。結果ウィンドウが大きすぎます。
401キーがない/無効。ヘッダーとキーを確認してください。
404該当する店舗がありません。
422予約・リアルタイム問い合わせを受けられない店舗(reservation_not_available / live_status_not_available)。ユミパートナー・店主アプリの店舗のみ可能 — 再試行せず、案内してください。
429レート制限 · 月間上限の超過。Retry-After の分だけ待つか、プランを上げてください。
5xxサーバーエラー。しばらくしてから再試行してください。