接入

开发者指南

HeyYumi 是一个读起来像一位策展人笔记的 API。一把密钥即可访问精选后的店铺(oneset):营业时间、菜单、价格区间、评分、活动新鲜度和可信度,还有停车(类型/费用/说明)、素食/纯素饮食索引、店铺能接待的语言,以及 AI 一句话摘要,全部已整理好。没有 GPS?用 /regions 把像 "Hongje-dong" 这样的街区名解析成编码和坐标(同名的洞按 sido/sigungu 区分),直接用于附近搜索。除了读取,同一把密钥还能发送预订请求和'现在有货吗?'这类实时提问(库存、等位、即时入座),店主会在 5 分钟内回复。

本指南在一处涵盖三种接入方式(API、MCP 和 CLI)。接入方式各不相同;下面的数据、计费、评分和错误对三者都是通用的。

获取 API 密钥 →API 参考 →在体验区直接调用 →MCP 服务器 →CLI →OpenAPI 规范

① 接入:三种方式,各不相同

无论你在构建什么,都可以通过以下三种方式之一接入 Yumi。每种方式性质不同,接入方法也不同。点击每张卡片的链接查看完整界面。

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 接入 →

② 通用:三种方式完全相同

无论你以哪种方式接入,其余部分都相同:Yumi 返回哪些数据、字段如何消耗 token、如何解读评分,以及错误代表什么含义。

字段选择 · 分级计费

我们不会一次性返回所有数据。用 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 不影响 token)。每月额度按 token 扣减,在当月内可以自由使用(没有每日上限)。防滥用靠限额而非价格:各套餐的每分钟请求数(rpm)、每次查询的结果窗口(Starter 1,000 · Pro 5,000),以及 30 天内不同店铺上限(Starter 10,000 · Pro 40,000;免费版 3,000)。不同店铺上限只统计唯一店铺,同一家店铺返回多次仍只计为一家(重复返回不会累加,只有整体抓取数据集时才会触及)。完整或大批量数据通过 Bulk Export · 数据授权提供,而非分页(参见条款中的可接受使用政策)。

如何解读评分:新鲜度 · 可信度

Yumi 不会把"这个地方是否值得推荐"压成一个单一的综合分数。相反,我们透明地给出构成判断的各项信号,让接收方按自己的策略来决定。所有分数都统一为越高越好。

freshnessScore · 活动新鲜度 (0–1,越高越近)

Yumi 以 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标识信息较少,或不同来源间名称不一致,建议使用前先确认。

对已确认歇业的店铺,原则上从推荐对象中排除。但不要因为新鲜度或可信度低就断定为歇业,它可能仍在正常营业。这两个分数是"筛选标准",而不是"歇业判定"。

认证

密钥归属于账户。密钥仅以哈希形式存储,明文只在创建时显示一次。REST 使用 Authorization: Bearer <KEY>(或 X-API-Key)进行认证。MCP(mcp.heyyumi.ai,专用仓库 map3-mcp)两种方式都支持:可以填入同一个 Bearer 密钥(例如 Cursor),也可以通过 Google 登录(OAuth)免密钥连接。ChatGPT 从插件目录连接,Claude 和 Perplexity 通过自定义连接器。URL 中的 ?api_key= 已弃用,因为 URL 很容易被记录到日志中。

错误代码

400参数错误 / bulk_export_required。结果窗口过大。
401缺少或无效的密钥。请检查请求头和密钥。
404未找到该店铺。
422该店铺无法接受预订或实时提问(reservation_not_available / live_status_not_available)。仅限 Yumi Partner 或店主 App 的店铺。请不要重试,直接向用户说明。
429触发限流或超出每月额度。请按 Retry-After 等待,或升级套餐。
5xx服务器错误。请稍后重试。