はじめに
開発者ドキュメント
API キー 1 つで韓国の店舗データを取得できます。営業時間、メニュー、価格帯、レビュー数、駐車場、ベジタリアン対応、外国語対応、AI による一行要約がそろっていて、店舗ごとに最新性と信頼度のスコアが付きます。座標がない場合は、/regions に「Hongje-dong」のような地域名を渡して座標を取得し、周辺検索に使ってください。同じキーで予約をリクエストしたり、在庫や待ち時間など今の状況を問い合わせたりもできます。問い合わせると、5 分以内に答えてほしいという通知が店主に届きます。
まずキーを作成してください。1 つのキーで MCP、CLI、REST API のすべてを使えます。
3 つの接続方法
作りたいものに合った方法を選んでください。詳しい手順は各ページにあります。
Claude、Cursor、Codex、Gemini などの AI に案内文を 1 行貼り付けると、AI が接続まで済ませます。ChatGPT はプラグインから接続します。自分で設定する場合は、下のサーバー URL を追加し、Google ログインか API キーで認証してください。
https://mcp.heyyumi.ai/mcp
自社サービスのサーバーから HTTP で呼び出します。レスポンスは JSON です。
curl -H "Authorization: Bearer hmp_xxx" \ "https://api.heyyumi.ai/api/v1/places?keyword=burger"
Claude Code、Codex、Gemini CLI のようにターミナルで動くエージェント向けです。インストール不要で npx から実行でき、Google ログインを 1 回済ませれば検索と予約リクエストができます。
npx -y heyyumi login npx -y heyyumi search matcha --business_category cafe --region Euljiro
共通事項
どの方法で接続しても、認証、トークン、スコア、エラーコードは同じです。
認証
キーは作成したアカウントに属します。サーバーにはハッシュしか保存しないため、キーの文字列は作成時に一度だけ表示されます。REST は Authorization: Bearer <KEY> ヘッダーか X-API-Key ヘッダーで認証します。MCP サーバー(mcp.heyyumi.ai)はどちらの方法にも対応しています。Cursor のように Bearer キーを設定しても、ChatGPT、Claude、Perplexity のように Google ログイン(OAuth)でキーなしで接続してもかまいません。URL に ?api_key= を付ける方法はサーバーログにキーが残りやすいため、近く廃止する予定です。
フィールドの選択とトークン
fields パラメータで受け取るフィールドを選びます。ティア名(core, contact_hours, quality, edge, media)、all、フィールド名をカンマ区切りで指定してください。指定しない場合は core だけが返ります。
core1 tokenCore (identity & location)id, name, category, categoryLabel, location, address, regionCode, confidence, sourceCount, possiblyClosed, lastSeenAt, placeUrl
contact_hours2 tokensContact & hoursphone, homepage, yumiReservable, reservationChannels, snsLinks, businessHours, temporaryClosures, is24h
quality2 tokensQuality & pricereviewCount, latestReviewDate, freshnessScore, dataQuality, price, menuSummary, openNow, closureSignal, promotion, photoCount, nearestStation, michelin
edge4 tokensAccess & contextaccessHints, recommendedFor, atmosphere, menu, serviceAttributes, dietary, atmosphereScores, aiSummary, ownerIntro, ownerStory, influencerFeatures, culturalAssociations, legacy, reputation
media8 tokensPhotosphotos
トークンはリクエストごとに、リクエストしたフィールドのうち最も高いティアの分だけ消費されます。page_size はトークンに影響しません。すべてのアカウントで毎月 50,000 トークンを無料で使え、1 日あたりの上限はありません。無料アカウントの上限は、1 分あたり 30 リクエスト(超えると 429 と Retry-After が返ります)、1 回の検索で結果 100 件、直近 30 日間で異なる店舗 20,000 店です。同じ店舗は何度表示しても 1 店と数えます。データ全体が必要な場合は、ページ送りで集めずに Bulk Export かデータライセンスを利用してください(利用規約の許容利用ポリシー)。
スコアの読み方: 最新性と信頼度
スコアは 1 つにまとめず、別々に返します。おすすめするかどうかは、各サービスが自分の基準で決めてください。どのスコアも高いほど良い値です。
freshnessScore · 活動の最新性 (0〜1, 高いほど最近)店舗に最近どれだけ活動があったかを 0〜1 の値で表します。
0.8 – 1.0直近 4 か月以内に活動が多くあります。0.5 – 0.8最後の活動が 4〜9 か月ほど前です。0.2 – 0.5最後の活動が 9〜14 か月ほど前です。行く前に確認することをおすすめします。0 – 0.214〜18 か月以上、ほとんど活動がありません。null(なし)スコアを出すための情報が足りない場合です。閉店したという意味ではありません。
confidence · データ信頼度 (0.3〜0.98, 高いほど信頼できる)複数の情報源が同じ店舗を指し、電話番号、座標、住所、名前が一致するほど高くなります。最大値は 0.98 です。
0.9 – 0.98複数の情報源で同じ店舗だと確認できています。0.75 – 0.9情報源どうしの情報が一致しています。0.6 – 0.75情報源が 1 つだけか、識別情報が一部しかありません。情報源が 1 つだけの店舗は多いので、この範囲だからといって品質が低いわけではありません。0.3 – 0.6識別情報が少ないか、情報源によって名前が異なります。使う前に確認してください。
閉店が確認された店舗はおすすめから外してください。最新性や信頼度が低いだけで閉店と判断しないでください。今も営業している可能性があります。2 つのスコアは絞り込みの目安として使ってください。
エラーコード
400パラメータが正しくないか、リクエストした結果の範囲が大きすぎます(bulk_export_required)。401キーがないか、正しくありません。ヘッダーとキーを確認してください。404店舗が見つかりません。422まだ HeyYumi で予約やリアルタイムの問い合わせを受け付けていない店舗です(reservation_not_available、live_status_not_available)。再試行せず、ユーザーに伝えてください。予約の受付時間外なら reservation_requests_closed が返ります。次の受付時刻は retryAfter に入っています。リクエストした時刻が店舗の休業時間なら venue_closed_at_requested_time が返ります。4291 分あたりの上限か月間の上限を超えました。Retry-After に示された時間だけ待ってから再送するか、お問い合わせください。5xxサーバーエラーです。しばらくしてから再試行してください。