/28hse/estates/search

POST /api/28hse/estates/search

Price: 10 credits

Search the Hong Kong estate (屋苑) directory published by 28Hse and Squarefoot — residential estates as well as commercial and industrial buildings. Filter by ownership category (private estate, subsidised or public housing, detached house) or building category (industrial, office, shop), the three-level area tree and free text. Each card returns the estate id and page URL, the name, the district, the ninety-day deal volume, the number of listings for sale and to let, the rental yield, the average price per square foot, the cover photo and the estate labels such as the developer, the age band and activity markers. The total number of matching estates is returned in the X-Total-Available-Results header.

How to use it

Search 28Hse / Squarefoot Hong Kong estates (屋苑). Set count. Switch usage to 'office' for commercial and industrial buildings. Narrow with estate_kinds or commercial_kinds, regions, district_groups, districts and keyword. Each result carries id — pass it to 28hse/estates for the full profile, to 28hse/estates/transactions for its deal history; 28hse/estates also returns cat_id, which is what 28hse/properties/search takes in estate_cat_ids. The directory is shared between the two sites, so site only picks the language edition.

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")
• count integer required — Number of estates to return. (min: 1)
• usage string — Residential estates or commercial and industrial buildings. (default: "residential"; one of: "residential", "commercial")
• estate_kinds array nullable — Ownership categories. Applies to residential estates. (one of: "private_estate", "public_and_subsidised_housing", "detached_house")
• commercial_kinds array nullable — Building categories. Applies to commercial and industrial buildings. (one of: "industrial", "office", "shop")
• regions array nullable — Top-level Hong Kong regions. (one of: "hong_kong_island", "kowloon", "new_territories", "outlying_islands")
• district_groups array nullable — District groups (the second level of the area tree). (one of: "island_south", "aberdeen_ap_lei_chau_wong_chuk_hang", "chai_wan_siu_sai_wan_shek_o", "shau_kei_wan_heng_fa_chuen", "sai_wan_ho", "taikoo", "quarry_bay", "north_point_mid_levels", "north_point_fortress_hill", "tin_hau_tai_hang", "causeway_bay_happy_valley", "wan_chai_admiralty", "mid_levels", "central_sheung_wan", "sai_ying_pun_shek_tong_tsui", "kennedy_town", "whampoa", "hung_hom", "tsim_sha_tsui", "jordan", "yau_ma_tei", "mong_kok", "prince_edward", "tai_kok_tsui_olympic_kowloon_station", "lai_king", "mei_foo", "cheung_sha_wan", "lai_chi_kok", "sham_shui_po_shek_kip_mei_nam_cheong", "yau_yat_tsuen", "ho_man_tin", "kowloon_tong", "san_po_kong_wong_tai_sin", "kai_tak", "kowloon_city", "to_kwa_wan", "diamond_hill_lok_fu", "ngau_chi_wan", "kowloon_bay", "kwun_tong_ngau_tau_kok", "yau_tong", "lam_tin", "sha_tau_kok", "tsing_yi", "kwai_chung_kwai_fong", "tsuen_wan_tai_wo_hau", "tsuen_wan_sham_tseng", "tuen_mun_castle_peak_road", "tuen_mun", "tin_shui_wai", "yuen_long_hung_shui_kiu", "sheung_shui", "fan_ling", "tai_po_tai_wo_pak_shek_kok", "sha_tin_tai_wai_fotan", "ma_on_shan", "tseung_kwan_o", "sai_kung_clear_water_bay", "cheung_chau_other_islands", "lamma_island", "peng_chau", "south_lantau_island_tai_o", "tung_chung", "discovery_bay", "ma_wan", "greater_bay_area")
• districts array nullable — Individual districts (the third level of the area tree). (one of: "pok_fu_lam", "shouson_hill", "baguio_villa", "southern_district", "repulse_bay", "tai_tam", "stanley", "south_horizons", "parkview", "wong_chuk_hang", "ap_lei_chau", "aberdeen", "chai_wan", "shek_o", "siu_sai_wan", "shau_kei_wan", "heng_fa_chuen", "north_point", "fortress_hill", "tai_hang", "tin_hau", "jardines_lookout", "happy_valley", "happy_valley_mid_levels", "causeway_bay", "admiralty", "wan_chai", "shiu_fai_terrace", "western_mid_levels", "mid_levels_central", "the_peak", "sheung_wan", "central", "sai_ying_pun", "shek_tong_tsui", "tai_kok_tsui", "olympic", "kowloon_station", "sham_shui_po", "shek_kip_mei", "nam_cheong", "san_po_kong", "wong_tai_sin", "diamond_hill", "lok_fu", "ngau_tau_kok", "kwun_tong", "kwai_chung", "kwai_fong", "tsuen_wan", "tai_wo_hau", "yuen_long", "hung_shui_kiu", "tai_po", "tai_wo", "pak_shek_kok", "sha_tin", "tai_wai", "fotan", "tseung_kwan_o_town", "lohas_park", "hang_hau", "po_lam", "tiu_keng_leng", "sai_kung", "clear_water_bay", "cheung_chau", "other_islands", "south_lantau_island", "tai_o", "zhongshan", "zhuhai", "guangdong", "huizhou", "shenzhen", "jiangmen")
• keyword string nullable — Free text matched against the estate name and street.

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 — The entity was not found, or a precondition failed 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.