/midland/estates

POST /api/midland/estates

Price: 20 credits

Get the full profile of one Hong Kong residential estate (屋苑) or estate phase by id (or estate URL). Returns the estate name in Chinese and English, type, address, generated description, developer, vendor, occupation dates per phase, land-lease term, block and storey breakdown, total units and blocks, live listing counts with price and rent ranges and averages per bedroom count, the saleable-area price index with month-on-month change and deal counts, the eight-level geography and coordinates, school nets with named primary and secondary schools, MTR lines and stations, walkable amenities, estate facilities and features such as pet policy, every phase with its buildings, photos, site plans, videos, the full floor plan library, nearby Midland branches, and the most recent sale and rental deals in the estate.

How to use it

Get one Hong Kong estate profile by id. Accepts an estate id ('E000004419', short form 'E00024') or a phase id ('P000000424'), and a full estate URL. Set lang / unit / currency for the output locale — note that per-area prices follow the chosen unit. Find ids with midland/estates/search, then use midland/properties/search with estate_ids for live listings and midland/transactions/search with estate_ids for the deal history.

Parameters

• access-token string required

Request body

• timeout integer — Max scrapping execution timeout (in seconds) (default: 300; min: 20; max: 1500)
• lang string — Output language. Districts, estates, buildings and feature names are all translated. (default: "zh-hk"; one of: "zh-hk", "zh-cn", "en")
• unit string — Area unit used for areas and per-area prices. (default: "feet"; one of: "feet", "meter")
• currency string — Currency used for prices, rents and monthly payments. (default: "HKD"; one of: "HKD", "CNY")
• estate string required — Midland estate or estate-phase id, or the full estate URL. (examples: "E000004419")

Response

• @type string (default: "MidlandEstate")
• id string required
• name string nullable
• name_en string nullable
• url string nullable
• url_zh_cn string nullable
• url_en string nullable
• estate_type string nullable
• building_type string nullable
• is_phase boolean nullable
• is_hos boolean nullable
• address string nullable
• description string nullable
• highlights string nullable
• facilities_text string nullable
• rating integer nullable
• developer string nullable
• vendor string nullable
• management_company string nullable
• op_date_text string nullable
• first_op_at integer nullable
• last_op_at integer nullable
• land_lease_text string nullable
• block_count_text string nullable
• storey_text string nullable
• total_flats_text string nullable
• total_phase_text string nullable
• sell_count integer nullable
• rent_count integer nullable
• min_price number nullable
• max_price number nullable
• min_rent number nullable
• max_rent number nullable
• avg_net_ft_price number nullable
• min_net_ft_price number nullable
• max_net_ft_price number nullable
• avg_net_ft_rent number nullable
• min_net_ft_rent number nullable
• max_net_ft_rent number nullable
• market_stat object nullable
  • @type string (default: "MidlandMarketStat")
  • net_ft_price number nullable
  • previous_net_ft_price number nullable
  • net_ft_price_change_percent number nullable
  • ft_price number nullable
  • previous_ft_price number nullable
  • ft_price_change_percent number nullable
  • net_ft_rent number nullable
  • transaction_count integer nullable
  • transaction_amount number nullable
• room_stats array (default: [])
  • @type string (default: "MidlandEstateRoomStat")
  • bedroom_count string required
  • sell_count integer nullable
  • rent_count integer nullable
  • min_price number nullable
  • max_price number nullable
  • avg_net_ft_price number nullable
  • min_net_ft_price number nullable
  • max_net_ft_price number nullable
  • min_rent number nullable
  • max_rent number nullable
  • avg_net_ft_rent number nullable
  • min_net_ft_rent number nullable
  • max_net_ft_rent number nullable
• room_market_stats array (default: [])
  • @type string (default: "MidlandEstateRoomMarketStat")
  • bedroom_count string required
  • avg_net_ft_price number nullable
  • avg_net_ft_rent number nullable
• census object nullable
  • @type string (default: "MidlandEstateCensus")
  • population integer nullable
  • median_age number nullable
  • age_0_14 integer nullable
  • age_15_24 integer nullable
  • age_25_44 integer nullable
  • age_45_64 integer nullable
  • age_65_plus integer nullable
  • education_primary_and_below integer nullable
  • education_secondary integer nullable
  • education_post_secondary integer nullable
  • household_count integer nullable
  • avg_household_size number nullable
  • median_household_income number nullable
  • median_active_household_income number nullable
  • median_mortgage_payment number nullable
  • mortgage_to_income_percent number nullable
  • median_rent number nullable
  • rent_to_income_percent number nullable
  • owner_with_mortgage_percent number nullable
  • owner_without_mortgage_percent number nullable
  • sole_tenant_percent number nullable
  • working_population integer nullable
  • managers_and_administrators integer nullable
  • professionals integer nullable
  • associate_professionals integer nullable
  • clerical_support_workers integer nullable
  • service_and_sales_workers integer nullable
  • other_occupations integer nullable
• geo object nullable
  • @type string (default: "MidlandGeo")
  • region object nullable
    • @type string (default: "MidlandRef")
    • id string nullable
    • name string nullable
  • subregion object nullable
    • @type string (default: "MidlandRef")
    • id string nullable
    • name string nullable
  • district object nullable
    • @type string (default: "MidlandRef")
    • id string nullable
    • name string nullable
  • sm_district object nullable
    • @type string (default: "MidlandRef")
    • id string nullable
    • name string nullable
  • combined_district object nullable
    • @type string (default: "MidlandRef")
    • id string nullable
    • name string nullable
  • int_district object nullable
    • @type string (default: "MidlandRef")
    • id string nullable
    • name string nullable
  • int_sm_district object nullable
    • @type string (default: "MidlandRef")
    • id string nullable
    • name string nullable
  • lux_district object nullable
    • @type string (default: "MidlandRef")
    • id string nullable
    • name string nullable
• location object nullable
  • @type string (default: "MidlandLocation")
  • latitude number nullable
  • longitude number nullable
• school_net object nullable
  • @type string (default: "MidlandSchoolNet")
  • kindergarten_id string nullable
  • kindergarten_name string nullable
  • primary_id string nullable
  • primary_name string nullable
  • secondary_id string nullable
  • secondary_name string nullable
• primary_schools array (default: [])
• secondary_schools array (default: [])
• mtr_lines array (default: [])
• mtr_stations array (default: [])
• amenities array (default: [])
  • @type string (default: "MidlandAmenity")
  • type string nullable
  • name string nullable
  • walking_minutes integer nullable
• facility_groups array (default: [])
  • @type string (default: "MidlandRef")
  • id string nullable
  • name string nullable
• features array (default: [])
  • @type string (default: "MidlandRef")
  • id string nullable
  • name string nullable
• top_estates array (default: [])
• phases array (default: [])
  • @type string (default: "MidlandEstatePhase")
  • id string nullable
  • name string nullable
  • url string nullable
  • latitude number nullable
  • longitude number nullable
  • buildings array (default: [])
    • @type string (default: "MidlandEstateBuilding")
    • id string nullable
    • name string nullable
    • address string nullable
    • building_type string nullable
    • first_op_at integer nullable
    • latitude number nullable
    • longitude number nullable
    • has_floor_plan boolean nullable
• other_phases array (default: [])
  • @type string (default: "MidlandRef")
  • id string nullable
  • name string nullable
• photos array (default: [])
  • @type string (default: "MidlandEstatePhoto")
  • url string nullable
  • name string nullable
• site_plans array (default: [])
• videos array (default: [])
  • @type string (default: "MidlandPropertyVideo")
  • id string nullable
  • url string nullable
  • stream_url string nullable
  • thumbnail string nullable
• floor_plans array (default: [])
  • @type string (default: "MidlandFloorPlan")
  • id string nullable
  • name string nullable
  • url string nullable
  • source string nullable
  • phase_id string nullable
  • phase_name string nullable
  • building_id string nullable
  • building_name string nullable
  • floor_from string nullable
  • floor_to string nullable
  • floor_text string nullable
• branches array (default: [])
  • @type string (default: "MidlandBranchContact")
  • name string nullable
  • phone string nullable
• recent_sale_transactions array (default: [])
  • @type string (default: "MidlandNearbyTransaction")
  • price number nullable
  • net_area number nullable
  • bedroom_count integer nullable
  • estate_name string nullable
  • phase_name string nullable
  • building_name string nullable
  • floor string nullable
  • floor_name string nullable
  • flat string nullable
  • gain_percent number nullable
  • holding_period_years number nullable
• recent_rent_transactions array (default: [])
  • @type string (default: "MidlandNearbyTransaction")
  • price number nullable
  • net_area number nullable
  • bedroom_count integer nullable
  • estate_name string nullable
  • phase_name string nullable
  • building_name string nullable
  • floor string nullable
  • floor_name string nullable
  • flat string nullable
  • gain_percent number nullable
  • holding_period_years number nullable
• sale_listings_url string nullable
• rent_listings_url string nullable
• transactions_url string nullable
• transaction_history_url string nullable
• news_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 or phase 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.