/28hse/estates

POST /api/28hse/estates

Price: 20 credits

Get the full profile of a Hong Kong estate (屋苑) or of one of its phases by id. Returns the Chinese and English names, the street, the marketing description and the estate labels, the number of blocks and units, the year the estate was occupied, the developer, the management company and the clubhouse facilities, the primary and secondary school nets, the ninety-day sale statistics (average price per square foot with its change, the price a year earlier, deal volume, the share of resales at a profit and at a loss and the annual turnover rate), the current asking range with the number of listings and the asking price per square foot range, the matching ninety-day rental statistics (average rent per square foot, deal volume, rental yield and rental activity, asking rent range and rental listing count), the 2021 census population, household count and average household size together with the full census breakdown of the estate against the Hong Kong average (age, marital status, work status, sex, ethnicity, birthplace, household size and income, rooms, floor area, education, literacy, language, workplace and tenure), the list of phases with their own ids, and cat_id — the second id the source keys the same estate by on the listing search and the deal register.

How to use it

Get one 28Hse / Squarefoot Hong Kong estate, e.g. estate='1140' (太古城 / TaiKoo Shing). The '{name}-{id}' slug and the estate page URL are accepted too. Estate ids are shared between the two sites, so site only picks the language edition. Find ids with 28hse/estates/search, or read estate_id off any listing or transaction. Phase ids from the phases list can be passed back in as estate. cat_id in the answer is the id 28hse/properties/search takes in estate_cat_ids. Money is HKD, areas are square feet. lang switches text between traditional Chinese, simplified Chinese and English.

Parameters

• access-token string required

Request body

• timeout integer — Max scrapping execution timeout (in seconds) (default: 300; min: 20; max: 1500)
• site string — Which Hong Kong portal to read. Both run on the same platform but hold different listing inventories: 28hse is the larger Chinese-first marketplace, squarefoot is the English-first one. (default: "28hse"; one of: "28hse", "squarefoot")
• lang string — Language of names, addresses and descriptions. It also changes which listings exist: some categories are only published in the Chinese editions. (default: "tc"; one of: "tc", "cn", "en")
• estate string required — Estate id, the '{name}-{id}' slug, or the estate page URL. (examples: "1140")

Response

• @type string (default: "Hse28Estate")
• id string required
• cat_id string nullable
• url string nullable
• name string nullable
• name_en string nullable
• street string nullable
• region string nullable
• district string nullable
• description string nullable
• image string nullable
• labels array (default: [])
• block_count integer nullable
• unit_count integer nullable
• occupation_year integer nullable
• developer string nullable
• management_company string nullable
• clubhouse string nullable
• primary_school_net string nullable
• primary_school_net_id string nullable
• secondary_school_net string nullable
• secondary_school_net_id string nullable
• avg_price_per_sqft number nullable
• price_change_percent number nullable
• price_per_sqft_year_ago number nullable
• sale_transaction_count integer nullable
• profit_ratio_percent number nullable
• loss_ratio_percent number nullable
• turnover_rate_percent number nullable
• min_asking_price number nullable
• max_asking_price number nullable
• min_asking_price_per_sqft number nullable
• max_asking_price_per_sqft number nullable
• sale_listing_count integer nullable
• avg_rent_per_sqft number nullable
• rent_transaction_count integer nullable
• rental_yield_percent number nullable
• rental_activity_percent number nullable
• min_asking_rent number nullable
• max_asking_rent number nullable
• min_asking_rent_per_sqft number nullable
• max_asking_rent_per_sqft number nullable
• rent_listing_count integer nullable
• population integer nullable
• household_count integer nullable
• average_household_size number nullable
• census array (default: [])
  • @type string (default: "Hse28EstateCensusRow")
  • group string required
  • indicator string required
  • value number nullable
  • hong_kong_value number nullable
  • unit string nullable
• phases array (default: [])
  • @type string (default: "Hse28EstatePhase")
  • id string required
  • name string nullable
  • url string nullable

Errors

• 422 — The request body did not validate Check the fields against this schema. A URN with the wrong prefix is the most common cause.
• 408 — The request ran past its time limit Raise `timeout` in the request body, up to the maximum this endpoint documents. Lowering `count` or turning off the `with_*` flags also helps, because less work finishes sooner.
• 412 — No estate with this id. Retrying will not help: either the entity does not exist, or the input points at a different one.
• 429 — Too many requests: a rate limit or a usage window is exhausted When the response carries an X-Retry-After header, wait that many seconds and retry: the same number is in the body as `detail.retry_after`, and the limit clears once that window passes. The message in the body names the limit that was hit.
• 500 — Something broke on our side Retrying will not help. If it keeps happening, send us the X-Request-ID from the response headers.
• 529 — Rate limit reached, or the endpoint is overloaded Wait at least 30 seconds, then retry.

Response headers

• X-Error — Error message text (present only on error)
• X-Request-ID — Unique request identifier
• X-Execution-Time — Execution time in seconds
• X-Result-Count — How many records the body carries. 0 means an empty result, which is a normal answer and not by itself an error. A non-zero count can come back together with X-Error when the failure happened partway through — read this header and X-Error independently.
• X-Total-Available-Results — How many records exist for this query, when the endpoint can say. On a `dry_run` request this is the answer and the body is empty. It saturates: the endpoint's documented maximum means 'at least that many', any smaller number is exact.
• X-Warning — Present when the request body carried keys this endpoint does not document. They were ignored, so any filter you meant to apply through them did not apply. Check the spelling against this schema and retry.
• X-Retry-After — Seconds to wait before retrying. Present only on 429.