开始使用

开发者文档

用一个 API 密钥获取韩国门店数据。营业时间、菜单、价格区间、评论数、停车、素食菜单、外语接待和 AI 一句话摘要都已整理好,每家门店还附有时效性和可信度评分。没有坐标时,先把“Hongje-dong”这样的街区名传给 /regions 换成坐标,再用于附近搜索。同一个密钥还能发送预订请求,或询问库存、等位这类实时情况。店主会收到提醒,需要在 5 分钟内回复。

先创建密钥。一个密钥就能同时用于 MCP、CLI 和 REST API。

三种接入方式

按你要做的东西选一种。详细步骤见各自的页面。

把一行说明粘贴到 Claude、Cursor、Codex、Gemini 等 AI 里,AI 会自己完成连接。ChatGPT 通过插件连接。想手动设置的话,填入下面的服务器地址,再用 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 登录一次就能搜索并发送预订请求。

npx -y heyyumi login
npx -y heyyumi search matcha --business_category cafe --region Euljiro

通用说明

无论用哪种方式接入,认证、token、评分和错误代码都一样。

认证

密钥属于创建它的账户。服务器只保存哈希值,所以密钥原文只在创建时显示一次。REST 用 Authorization: Bearer <KEY> 请求头或 X-API-Key 请求头认证。MCP 服务器(mcp.heyyumi.ai)两种方式都支持:可以像 Cursor 那样填入 Bearer 密钥,也可以像 ChatGPT、Claude、Perplexity 那样用 Google 登录(OAuth),不用密钥。在 URL 后加 ?api_key= 的方式容易让密钥留在服务器日志里,即将停用。

选择字段与 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, placeUrl

  • contact_hours2 tokensContact & hours

    phone, homepage, yumiReservable, reservationChannels, snsLinks, businessHours, temporaryClosures, is24h

  • quality2 tokensQuality & price

    reviewCount, latestReviewDate, freshnessScore, dataQuality, price, menuSummary, openNow, closureSignal, promotion, photoCount, nearestStation, michelin

  • edge4 tokensAccess & context

    accessHints, recommendedFor, atmosphere, menu, serviceAttributes, dietary, atmosphereScores, aiSummary, ownerIntro, ownerStory, influencerFeatures, culturalAssociations, legacy, reputation

  • media8 tokensPhotos

    photos

每次请求扣一次 token,扣多少由所请求字段中最高的等级决定。page_size 不影响 token。每个账户每月可免费使用 50,000 个 token,没有每日上限。免费账户的限额是每分钟 30 次请求(超出返回 429 和 Retry-After)、每次搜索最多 100 条结果、最近 30 天内最多 20,000 家不同门店。同一家门店展示多少次都只算 1 家。需要全部数据时,请不要靠翻页收集,改用 Bulk Export 或数据授权(见条款中的可接受使用政策)。

如何看评分:时效性和可信度

评分分开给出,不合成一个总分。要不要推荐,由各个服务按自己的标准决定。所有评分都是越高越好。

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只有一个来源,或只有部分识别信息。只有一个来源的门店很多,落在这个区间不代表质量低。
  • 0.3 – 0.6识别信息少,或各来源的名称不一致。使用前请确认。

已确认歇业的门店请不要推荐。时效性或可信度低,不代表一定歇业,它可能仍在营业。这两个评分请当作筛选条件来用。

错误代码

  • 400参数有误,或请求的结果范围太大(bulk_export_required)。
  • 401没有密钥或密钥不对。请检查请求头和密钥。
  • 404未找到该店铺。
  • 422该门店暂时还不能通过 HeyYumi 接受预订或实时询问(reservation_not_available、live_status_not_available)。请不要重试,直接告诉用户。不在预订受理时间内会返回 reservation_requests_closed,下次受理时间在 retryAfter 里。请求的时间门店不营业时,返回 venue_closed_at_requested_time。
  • 429超出了每分钟或每月的限额。请按 Retry-After 给出的时间等待后重试,或联系我们。
  • 5xx服务器错误。请稍后重试。