housing-sentinel

---

目录

• これは何ですか
• 対象都市とデータ
• 主要な概念：進攻／防守の市場シグナル
• クイックスタート（3 ステップ）
  • 方式 A：MCP 接続（推奨）
  • 方式 B：REST API
  • 方式 C：Claude Skill
• API 一覧
• 変更駆動：since / ETag と Webhook
• MCP Prompts と Resources
• npm stdio パッケージ
• 接続レシピ recipes/
• サンプルとテンプレート
• 利用規則と制限
• FAQ
• English Summary

これは何ですか

房哨兵は、不動産市場データを監視する SaaS です。各都市の住宅・都市農村建設局／不動産管理局が公式に発表する住宅の成約数と在庫データを毎日自動で取得し、在庫消化期間を算出して、「防守／観察／進攻／快速进攻」の 4 段階の市場シグナルを出力し、住宅購入者や投資家が取引のタイミングを見極めるのを支援します。

このリポジトリは、その AI 接続センターです。MCP、REST API、または Claude Skill を通じて、これらのデータやシグナルを Claude、Cursor、扣子、Dify、n8n、あるいは自作のエージェントワークフローに接続できます。新規ユーザーは無料でお試しいただけます：ログインしてキーを生成すると、初回呼び出しから 3 日間、12 都市すべてを照会できます。試用期間終了後も、深圳の現在のシグナルは永久無料です。ポイントパックは ¥39/1000 回、またはサブスクリプションで全データを利用できます。キー不要の公開エンドポイント GET /api/v1/cities/{city}/card を使えば、任意の都市の当日の成約状況と市場段階を取得できます。

📌 このリポジトリには公開されている接続ドキュメントとサンプルのみが含まれ、房哨兵の実装コードは含まれません。

対象都市とデータ

12 都市：深圳 · 上海 · 北京 · 广州 · 杭州 · 南京 · 苏州 · 无锡 · 成都 · 重庆 · 东莞 · 厦门

データ項目	説明
新築／中古住宅のオンライン成約	毎日（成都／重庆の新築は週次の公式集計、广州の中古は月次の公式集計）
新築／中古住宅の在庫	毎日、または公式発表の頻度に準拠
在庫消化期間	在庫 ÷ 月平均成約数（月）、新築／中古を別々に表示
市場段階シグナル	防守／观察／进攻／快速进攻（閾値は都市ごとに返されます）

データは毎日 1 回更新されます（北京時間 07:00–23:59、都市によって異なります）。

主要な概念：進攻／防守の市場シグナル

判断の枠組みでは、中古住宅の在庫消化期間を中心に据えます。

在庫消化期間	市場段階	意味
≥ 18 月	🔴 防守期	供給過剰で、住宅価格の下落リスクが高いため、様子見します
12 – 18 月	🟠 观察期	下落が止まり安定しつつあります。資金を準備し、購入を急がないでください
8 – 12 月	🔵 进攻／買入期	需給の均衡が近づいており、中心エリアの割安物件を選べます
< 8 月	🟢 快速进攻期	需要が供給を上回っており、優良物件は上昇する可能性が高いです

在庫消化期間のデータがない都市では、月間成約数による判断に切り替わります（低迷ライン／急騰ライン。閾値は都市ごとに異なります。GET /api/v1/cities を参照してください）。新築と中古のシグナルが矛盾する場合は、中古を基準にします。

クイックスタート（3 ステップ）

1. ログイン：housingsentinel.cn または WeChat ミニプログラム「房哨兵」にログインします（サブスクリプションなしでも、12 都市すべてを 3 日間無料でお試しいただけます。終了後も深圳の現在のシグナルは永久無料です。ポイントパックは ¥39/1000 回/30 日。単一都市または全国プランのサブスクリプションで、完全な履歴データとより高い上限を利用できます）
2. キーを取得：ログイン後、我的 → 接入 AI Agent に進み、API Key（hs_live_...）を生成します
3. 接続（いずれかを選択）：

方式 A：MCP 接続（Claude / Cursor など、推奨）

インストール不要です。房哨兵 MCP はリモートサービスなので、URL とキーを入力すれば使えます。

Claude Code のワンライナー：

claude mcp add --transport http housing-sentinel https://api.housingsentinel.cn/mcp \
  --header "Authorization: Bearer hs_live_你的密钥"

Claude Desktop / Cursor の設定ファイル：

{
  "mcpServers": {
    "housing-sentinel": {
      "type": "http",
      "url": "https://api.housingsentinel.cn/mcp",
      "headers": { "Authorization": "Bearer hs_live_你的密钥" }
    }
  }
}

設定後、AI にそのまま質問できます：

「厦门は現在どの市場段階ですか？進攻すべきですか、それとも防守すべきですか？」 「サブスクリプションを利用している都市をすべて比較して、最も買入期に近い都市を教えてください」 「深圳の過去 90 日間の中古住宅の在庫消化期間の傾向を分析してください」

MCP ツール：list_cities · get_market_signal · get_metrics · get_history

方式 B：REST API（任意の言語 / n8n / 扣子 / Dify）

curl https://api.housingsentinel.cn/api/v1/signals \
  -H "Authorization: Bearer hs_live_你的密钥"

OpenAPI 3.0 の記述ファイル：openapi.yaml —— 扣子（Coze）プラグイン、Dify カスタムツール、n8n、Custom GPT Actionsに直接インポートできます。

方式 C：Claude Skill（判断方法論 + ツール、ワンクリックでインストール）

skills/housing-sentinel/SKILL.md を使うと、Claude が「在庫消化期間に基づく進攻／防守の判断フレームワーク」を習得します。API を呼び出せるだけでなく、データの読み解き方も把握できます。中古優先の原則、水準より傾向を重視する考え方、都市ごとの集計基準の違い、回答のガイドラインが含まれています。

# Claude Code 安装（复制到项目 skills 目录）
mkdir -p .claude/skills/housing-sentinel
curl -o .claude/skills/housing-sentinel/SKILL.md \
  https://raw.githubusercontent.com/SheldonZhuang/housing-sentinel-ai/main/skills/housing-sentinel/SKILL.md

API 一览

端点	说明
GET /api/v1/signals	主接口：所有已订阅城市的当前信号快照
GET /api/v1/cities/{city}/signal	单个城市的当前信号
GET /api/v1/cities/{city}/metrics?from=&to=	逐日指标时间序列（趋势分析，默认近 90 天）
GET /api/v1/cities/{city}/history?from=&to=	原始日度成交／库存数据（单次最多 400 条）
GET /api/v1/cities	已订阅城市列表＋阈值元数据
POST/GET /api/v1/webhooks、DELETE /api/v1/webhooks/{id}、POST /api/v1/webhooks/{id}/test	Webhook 管理（试用／点数包／订阅／机构版）

城市代码使用拼音全拼（xiamen、shenzhen…）。完整字段定义请参见 openapi.yaml。

信号响应示例（节选）：

{
  "cityCode": "xiamen", "city": "厦门", "dataDate": "2026-07-12",
  "phase": "观察期", "phaseSource": "cycle",
  "secondHand": { "inventoryCycle": 13.4, "inventory": 25495, "avgMonthly": 1901 },
  "firstHand":  { "inventoryCycle": 29.1, "inventory": 21058, "avgMonthly": 723 },
  "thresholds": { "cycleDefense": 18, "cycleWatch": 12, "cycleBuy": 8 }
}

变化驱动：since / ETag 与 Webhook

数据每天更新一次，无需每次都解析全部数据。

轮询（所有层级均可用）：首次调用 GET /api/v1/signals，之后附带上次响应中的 nextSince：

curl "https://api.housingsentinel.cn/api/v1/signals?since=2026-09-30T00:00:00.000Z" \
  -H "Authorization: Bearer hs_live_xxx" -H 'If-None-Match: W/"上次的ETag"'

• 附带 since 时，仅返回该时间之后有数据变动的城市；响应会增加 since、changedSince（变动城市代码数组）、nextSince（供下次使用）；每个城市对象都带有 updatedAt。无效的 since 会返回 400 BAD_SINCE。
• /signals 与 /cities/{city}/signal 会返回弱 ETag；附带 If-None-Match 且数据没有变化时，会返回 304。
• 完整脚本：recipes/polling-etag.sh、recipes/n8n-signals-since.json。

Webhook（试用／点数包／订阅／机构版；免费层与演示密钥会返回 403）：

curl -X POST https://api.housingsentinel.cn/api/v1/webhooks \
  -H "Authorization: Bearer hs_live_xxx" -H "Content-Type: application/json" \
  -d '{"url":"https://your.domain/hs-webhook","cities":["shenzhen"],"events":["data.updated","phase.changed"]}'
# → 201，响应里的 secret（whsec_...）只返回这一次

• 事件：data.updated（城市有新数据）、phase.changed（市场阶段变化，另外带有 previousPhase/phase）；服务端每 5 分钟检测一次。
• 请求体 { id, event, createdAt, cityCode, signal }，其中 signal 与 /cities/{city}/signal 的响应相同。
• 请求头 X-HS-Event、X-HS-Delivery、X-HS-Signature: t=<unix秒>,v1=<hex>，v1 = HMAC-SHA256(secret, "<t>.<原始请求体>")。
• 要求：url 必须为 https（拒绝内网／回环地址）；5 秒内返回 2xx，且不跟随重定向；连续失败 10 次会自动停用（POST /webhooks/{id}/test 成功后可重新激活）；每个账号最多 5 个；订阅／试用过期后停止推送。
• 验签示例：Node.js / Python。

MCP Prompts 与 Resources

MCP サーバー 1.3.0 除 4 个工具外，还提供：

类型	名称	说明
Prompt	daily_brief	每日房市简报；参数 cities 可选，使用逗号分隔
Prompt	compare_cities	多城市对比；参数 cities
Resource	housing://llms.txt	接入说明（与 llms.txt 相同）
Resource	housing://thresholds	各城市的判档阈值（JSON）

npm stdio 包

仅支持 stdio 的 MCP 客户端可使用 housing-sentinel-mcp，它会将 stdio 消息原样转发至远程 MCP：

{ "mcpServers": { "housing-sentinel": { "command": "npx", "args": ["-y", "housing-sentinel-mcp"], "env": { "HOUSING_SENTINEL_API_KEY": "hs_live_xxx" } } } }

在中国大陆网络环境下，可在 env 中添加 "HOUSING_SENTINEL_URL": "https://housingpi-proxy-anirmyfaea.cn-shanghai.fcapp.run/mcp"。

接入配方 recipes/

recipes/ 中的每个文件都可直接复制使用：Claude Code 每日 08:00 简报、Claude Desktop/Cursor 配置、n8n since+ETag 轮询、扣子工作流、Dify OpenAPI 导入、OpenAI Agents SDK、Webhook 验签（Node/Python）、curl 轮询脚本。

示例与模板

文件	场景
examples/python-example.py	Python 获取全城市信号＋阶段跨越检测（可通过 cron 运行）
examples/n8n-daily-alert.json	n8n 工作流：每天 8 点巡检，阶段跨越时推送至企业微信（导入即可使用）
examples/claude-agent.md	Claude Code 房产投资监控 subagent 定义＋每日自动巡检

使用规则与限制

项目	说明
数据授权	API 数据仅限订阅者／试用者本人使用，不得对外提供数据服务
认证	Authorization: Bearer hs_live_...；密钥可在「接入 AI Agent」页面随时重置（旧密钥立即失效）
免费试用	无订阅账号自首次调用起 3 天内可查询全部 12 个城市；历史数据仅限最近 30 天
免费层	试用结束后永久可用：深圳当前信号（/cities /signals /cities/shenzhen/signal、MCP list_cities / get_market_signal），10 次／分钟、50 次／天；metrics / history 返回 403（FREE_TIER_LIMIT）
点数包	¥39 / 1000 次 / 30 天，覆盖全部 12 个城市，历史数据仅限最近 90 天；用完或到期后恢复至免费层；不参与推荐返利
公开端点	GET /api/v1/cities/{city}/card 无需密钥：当日成交、当月累计、二手去化周期与市场档位（不含库存原值），缓存 60 秒
订阅价格	单城市 ¥299/年，全国 12 城 ¥1888/年（完整历史、60 次／分钟、2000 次／天）；订阅／点数包入口 housingsentinel.cn/agent（登录后「我的 → 接入 AI Agent」），付款后密钥立即生效；403/429 响应附带 subscribeUrl 与 pricing
机构/企业版	更高限额（300 次／分钟、20000 次／天）、全部城市、多席位，线下签约；请联系微信 SheldonZhuang
限流	订阅：60 次／分钟、2000 次／天；点数包：60 次／分钟；试用：10 次／分钟、100 次／天；免费层：10 次／分钟、50 次／天（按账号计算，重置密钥不会重置限额）
轮询建议	数据每天更新一次，建议轮询间隔 ≥ 1 小时
权限	订阅用户可查询已订阅的城市；试用期可查询全部 12 个城市；试用结束后，免费层仅提供深圳当前信号；点数包可查询全部 12 个城市；订阅到期后恢复至免费层，续订／购买后即可恢复
免责声明	信号是基于官方成交数据的市场时机参考，不构成投资建议

本仓库的文档与示例代码可自由用于接入房哨兵服务；房哨兵名称、判断框架内容与数据服务的权利由 housingsentinel.cn 保留。

よくある質問

Q：サブスクリプションに登録しなくても試せますか？ はい。ログイン後に API Key を生成すると、初回の呼び出しから 3 日間、全 12 都市のデータを無料で照会できます（シグナル、指標の時系列、直近 30 日間の生データを含む。上限は 10 回／分、100 回／日）。試用期間終了後も、深圳の現在のシグナルは永久に無料です。ログインしたくない場合は、公開エンドポイント GET /api/v1/cities/{city}/card を直接呼び出すこともできます。さらに利用したい場合は、ポイントパックが ¥39（1000 回／30 日、全都市、過去 90 日分）、またはサブスクリプション（1 都市 ¥299／年、全国 12 都市 ¥1888／年、全履歴とより高い上限）をご利用ください。

Q：キーが漏えいした場合はどうすればよいですか？ ログイン後、「マイページ → AI Agent 接続」で「キーをリセット」をクリックしてください。古いキーは直ちに無効になります。新しいキーを Agent の設定に反映してください。

Q：成都／重慶の新築物件の在庫消化期間が null なのはなぜですか？ この 2 都市の新築物件について、公式の指標は週次の成約件数と当月の販売承認済み戸数（累計販売可能在庫ではありません）です。在庫消化期間を計算すると誤解を招くため、正直に null を返しています。判断には中古物件の指標と成約件数をご確認ください。

Q：データソースの信頼性はどの程度ですか？ すべて各市の住宅・都市建設局／不動産管理局が公式に発表する情報源から取得し、毎日自動で収集しています。複数のフォールバック検証も行っています（詳しくは製品内の説明をご覧ください）。

Q：希望する都市が一覧にありません。 公式サイトから都市の追加をリクエストしてください。サブスクリプションの需要量を、新しい都市の追加を決める最優先の基準としています。

英語の概要

Housing Sentinel は、中国の主要 12 都市（深圳、上海、北京、広州、杭州、南京、蘇州、無錫、成都、重慶、東莞、厦門）の住宅取引データと、市場の強気・弱気シグナルを毎日提供します。シグナルは中古物件の在庫消化期間に基づいています：18 か月以上＝守り、12～18 か月＝様子見、8～12 か月＝買い、8 か月未満＝強く買い。

利用開始： housingsentinel.cn にログイン → マイページ → AI Agent で API キーを生成 → リモート MCP サーバー（https://api.housingsentinel.cn/mcp、Bearer 認証。stdio クライアントの場合は npx -y housing-sentinel-mcp）または REST（/api/v1/signals。仕様は openapi.yaml）経由で接続してください。新規ユーザーは、初回の API 呼び出しから 全 12 都市を 3 日間無料で試用できます。試用期間終了後も、深圳の現在のシグナルは永久に無料で、サブスクリプションは不要です。キー不要の公開エンドポイント GET /api/v1/cities/{city}/card では、任意の都市の最新の取引情報と市場局面を取得できます。用意済みの Claude Skill を使うと、エージェントに API と判断のフレームワークの両方を習得させられます。変更ベースのアクセス：/signals?since= ＋ ETag/304、および HMAC 署名付き Webhook（data.updated / phase.changed）。コピーしてすぐ使える連携例は recipes/ にあります。

データは毎日更新されます。レート制限は、サブスクライバーが 60 回／分、2,000 回／日（ポイントパックは ¥39／1,000 回／30 日、試用期間中は 10 回／分、100 回／日、無料プランは 10 回／分、50 回／日）です。データのライセンスはサブスクライバー／試用ユーザー自身の利用に限られ、データサービスとしての再配布は禁止されています。

---