canonical: https://jentic.com/apis/housingsentinel.cn/housingsentinel

# Housingsentinel Cn Housing Sentinel Open API（房哨兵开放API）

The Housing Sentinel API turns official daily property transaction records for 12 major Chinese cities, including Shenzhen, Shanghai, Beijing, and Guangzhou, into a market phase signal for each city. Each signal reports a phase such as 防守期 (defensive) or 进攻/买入期 (buy), the rule that set it, and first-hand and second-hand stats like inventoryCycle, inventory, and avgMonthly against the city's thresholds. Daily metric series and raw transaction history support trend analysis, and webhooks push data.updated and phase.changed events so a client does not have to poll.

## For AI agents

Read daily housing market phase signals, inventory cycles, and transaction history for 12 Chinese cities, and register webhooks for data updates and phase changes.

## Scope

Does not list individual properties, provide prices per home, or cover cities outside its 12 supported codes. Use for city-level Chinese housing transaction data and market phase signals only.

## Capabilities

- Read the current market phase signal for every city your plan can access, with a since cursor that returns only cities that changed
- Fetch one city's signal with first-hand and second-hand inventoryCycle, inventory, and avgMonthly figures
- Pull a city's daily metric series between from and to dates for trend analysis
- Retrieve up to 400 raw daily transaction and inventory records for a city
- Read a public daily card for a city without an API key
- Register, list, test, and delete webhooks for data.updated and phase.changed events

## Use cases

### Agent property market briefings

An AI agent preparing a daily Chinese property market note needs each city's current phase and the reason behind it. Through Jentic it calls the signals snapshot, reads each city's phase and phaseSource, and summarises which cities sit in a defensive or buying phase, with the key held by your own instance rather than the agent.

Example prompt: Call GET /signals, then list each city's phase and inventoryCycle from the firstHand stats in a short briefing

### Change-driven monitoring

Data updates once a day, so polling every minute wastes quota. A client stores the nextSince value from GET /signals and passes it back as since, getting only cities whose data changed, or sends If-None-Match with the last ETag to receive a 304 when nothing moved.

Example prompt: Call GET /signals with since set to the stored nextSince value and report only the cities returned

### Phase change alerts by webhook

An investor wants to hear when Shenzhen or Hangzhou leaves a defensive phase. POST /webhooks registers an https url with a cities list and events such as phase.changed, the push carries previousPhase and the new phase, and the test endpoint sends a ping to confirm delivery.

Example prompt: Call POST /webhooks with url set to an https endpoint, cities set to shenzhen and hangzhou, and events set to phase.changed, then call POST `/webhooks/{id}/test`

### Inventory cycle trend analysis

An analyst comparing cities needs a daily series, not a snapshot. GET `/cities/{city}/metrics` returns daily inventory cycle, inventory, and average monthly sales between from and to dates, and GET `/cities/{city}/history` returns raw daily transaction and inventory rows, so the analyst can chart how fast stock is clearing.

Example prompt: Call GET `/cities/{city}/metrics` with city set to guangzhou and a from and to date range covering the last quarter, then chart the inventory cycle

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/signals` | Market signal snapshot for all accessible cities |
| GET | `/cities/{city}/signal` | One city's current market signal |
| GET | `/cities/{city}/metrics` | Daily metric series |
| GET | `/cities/{city}/history` | Raw daily transaction and inventory records |
| GET | `/cities/{city}/card` | Public daily card, no key |
| POST | `/webhooks` | Register a webhook |

## Key resources

- **Signals** — Snapshot of every accessible city's market phase, and one city's signal with thresholds
- **Cities** — Accessible city list, public daily card, daily metric series, and raw history
- **Webhooks** — Register, list, test, and delete webhooks for data.updated and phase.changed

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 68 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 100 / 100
  - Developer Experience & Jentic Compatibility: 64 / 100
  - AI-Readiness & Agent Experience: 49 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 75 / 100
- **View full report:** https://jentic.com/apis/housingsentinel.cn/housingsentinel/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Housing Sentinel by hand means generating an hs_live_ bearer key, handling tier-dependent city access and history depth, and managing since cursors and ETags to avoid wasted polls. Through Jentic you install once, import Housing Sentinel from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Housing Sentinel puts the city code in the URL path (`/cities/{city}/...`), so a rule can pin your agent to one city such as `/cities/shenzhen` and the operations you pick. You choose the operations it may call, so webhook registration and deletion are not included unless you add them.
- **Credential handling:** Your Housing Sentinel key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'china housing market signal' or 'alert on phase change', and Jentic returns the matching Housing Sentinel operation with its input schema so the agent passes a valid city code without reading the Chinese-language reference.

## Related APIs

- **ATTOM Property API** — US property records, ownership, value, and tax data
- **RentCast API** — US property records, sale listings, and rental market data
- **Lark** — Team messaging where a phase change alert can be posted

## FAQ

### What authentication does the Housing Sentinel API use?

Per its OpenAPI spec, the Housing Sentinel API uses HTTP bearer authentication with an API key in the hs_live_ format, generated from your housingsentinel.cn account under the AI Agent access page. The bearer key is the default security requirement, while GET `/cities/{city}/card` is declared public and needs no key. Through Jentic the key is stored by your own instance and attached at call time.

### Which cities does the Housing Sentinel API cover?

The city path parameter accepts 12 codes: shenzhen, shanghai, beijing, guangzhou, hangzhou, nanjing, suzhou, wuxi, chengdu, chongqing, dongguan, and xiamen. Which of them you can query depends on your tier: per the spec, the free tier keeps Shenzhen's current signal, the trial and credits pack open all 12 cities, and paid subscriptions cover a single city or all 12.

### What are the rate limits for the Housing Sentinel API?

The OpenAPI spec states limits per tier: the trial allows 10 calls a minute and 100 a day, the free tier 10 a minute and 50 a day, paid subscriptions 60 a minute and 2000 a day, and the institution tier 300 a minute and 20000 a day. The spec also notes data updates once a day and recommends polling no more than hourly.

### Is there a Housing Sentinel MCP server?

You don't need an MCP server to give your agent Housing Sentinel. Jentic connects it directly from the API Directory: import it, store your API key once, and your agent calls the signal, metrics, and webhook operations on demand without loading another server's tool definitions into its context.

### How do I get a city's market signal through Jentic?

Search Jentic for 'china housing market signal', load GET `/cities/{city}/signal`, and pass a city code such as shenzhen. The response carries the phase, phaseSource, firstHand and secondHand stats, and thresholds. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with the Housing Sentinel API?

Yes. For example, allow only GET `/cities/shenzhen/signal` and GET `/cities/shenzhen/metrics`, and the agent can read Shenzhen's phase and trend but cannot register or delete webhooks or query other cities, and every call it makes is logged.