BDS Chat API Reference

Getting Started

Start using the BDS Chat API in three steps. Endpoints return JSON over HTTPS and expose rate-limit headers for integration testing.

Authentication

The BDS Chat API uses Bearer token authentication. Include your API key in the Authorization header of every request.

Access Tiers

Auth Header Format

Authorization: Bearer bds_live_abc123def456...

Rate Limiting

Every API response includes rate limit headers so you can track usage in real time.

Response Headers

Handling 429 Too Many Requests

When you exceed your rate limit, the API returns 429 with a Retry-After header. Implement exponential backoff.

Search and filter real estate listings across Ho Chi Minh City. Supports district, price, area, legal status, and seller type filters with configurable sorting and pagination.

Query Parameters

Retrieve complete details for a single listing including trust_grade, quality_score, risk_score, risk_band, gov_price_per_m2, market_gov_ratio, images, and provenance data.

Path Parameters

Create a new listing. Requires Partner tier. Automatic deduplication on source + source_listing_id returns 409 Conflict if duplicate.

Request Body

Look up state land prices from NQ 87/2025. Covers 30,775 street-level records across HCMC with price per m² by street, position, and road width.

Query Parameters

Compare a listing's asking price against the state land-price benchmark. Returns ratio, differential, and assessment.

Query Parameters

Query zoning and urban planning data for a geographic coordinate. Returns zone code, LBCS classification, DGT road risk, and development constraints.

Query Parameters

Check zoning for a specific listing. Combines listing coordinates with zoning data to assess land use compatibility and planning constraints.

Query Parameters

Full risk assessment with 9 subscores and 5 blocking risk flags. Returns a final risk band from low to critical. Checks price reasonableness, location quality, listing completeness, source reputation, gov price alignment, and more.

Query Parameters

Ask a natural-language question about a specific listing. Returns a streaming SSE response with AI-generated analysis grounded in listing data, government benchmarks, and zoning info.

Path Parameters

Request Body

Health check endpoint. Returns service status and version. No authentication required.

Returns the full OpenAPI 3.1.0 specification. Useful for code generation, client SDKs, and API exploration. No authentication required.

Normalize ward names with 2025 ward reform awareness. Maps old ward names to current administrative units.

Query Parameters

Look up legal references (decisions, decrees, circulars) relevant to real estate transactions.

Query Parameters

Streaming (SSE)

POST /listings/{id}/chat uses Server-Sent Events to stream listing-scoped responses. The answer should stay within returned listing data, citations, and visible gaps.

Event Types

Handling SSE in JavaScript

const res = await fetch(url, {
  method: "POST",
  headers: { "Authorization": `Bearer ${key}`, "Content-Type": "application/json" },
  body: JSON.stringify({ "question": "Pháp lý listing này thế nào?" })
});

const reader = res.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const chunk = decoder.decode(value);
  // Parse SSE lines: event: type\ndata: {...}
}

Error Handling

The API uses standard HTTP status codes. Error responses include JSON fields your integration can log and show without exposing internal details.

Status Codes

Error Response Format

{
  "error": "forbidden",
  "message": "Pro tier required for /meta/* endpoints",
  "request_id": "019726a3-4b5c-7d8e-9f0a-1b2c3d4e5f6a"
}