/midland/properties/search

POST /api/midland/properties/search

Price: 20 credits

Search Midland Realty Hong Kong residential listings for sale or rent. Filters cover the full site search surface: free text, sale or rent, ownership class (private / HOS / TPS), curated categories, the eight-level geography (region, sub-region, district, small district, internal districts, luxury districts), estate, phase, building and street ids, MTR station with walking time, primary school net, universities, price, gross and saleable area, price per area unit, building age, bedrooms, master bedrooms, bathrooms, other rooms, floor band, flat, orientation, outlook, special unit features, decoration, unit and estate facilities, nearby amenities, media types, developer, luxury star tier and lifestyle theme, holding branch or agent, publication and update recency, plus mortgage assumptions and result ordering. Each card carries prices and rents with per-area figures, areas and efficiency ratio, room counts, floor and flat, orientation, photos, media flags, tags, the full geography chain, estate / phase / building, unit features, estate facilities, nearby amenities, MTR stations, school net, coordinates and the listing agents.

How to use it

Search Midland Realty Hong Kong residential listings. Always set count, and lang / unit / currency to pick the output locale (zh-hk, zh-cn or en), area unit (feet or meter) and currency (HKD or CNY). Use transaction_type 'S' for sale and 'L' for rent; price fields are populated for sale listings and rent fields for rentals. Narrow by text, property_types, categories, geography ids, estate_ids, mtr_ids with walking_duration, school_net, university_ids, price / area / building-age ranges, bedrooms, floor_levels, orientations, views, garden_features, facilities, nearby_facilities, media, developer, star_ratings and lifestyles. Use midland/properties with a serial_no for the full listing page, midland/estates for the estate profile and midland/transactions/search for past deals.

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")
• min_building_age integer nullable — Minimum building age in years, counted from first occupation. (min: 0; max: 999)
• max_building_age integer nullable — Maximum building age in years, counted from first occupation. (min: 0; max: 999)
• count integer required — Max number of results to return (min: 1; max: 10000)
• transaction_type string nullable — Sale or rental listings. Unset returns both. (one of: "S", "L")
• text string nullable — Free-text query matched against estate, building, street and district names. (minLength: 1)
• property_types array nullable — Ownership class: private housing, HOS (subsidised) or TPS, with premium paid or unpaid. (one of: "private", "hos_prempaid", "hos_premunpaid", "tps_prempaid", "tps_premunpaid")
• categories array nullable — Curated listing themes such as pet-friendly, foreclosure or reduced. (one of: "pet", "university", "northern_metro", "tenancy", "below", "90ltv", "100ssd", "with_key", "property_exchange", "above_mtr", "deluxe", "high_rental_return", "sole", "invest_immi", "talent_hot_selection", "sale", "latest", "foreclosure", "hot")
• sort string — Result ordering. (default: "default"; one of: "default", "latest", "random", "price", "price_desc", "sale_perc", "sale_perc_desc", "area", "area_desc", "net_area", "net_area_desc", "ft_price", "ft_price_desc", "net_ft_price", "net_ft_price_desc")
• region_id string nullable — Region id: 10 Hong Kong Island, 20 Kowloon, 30 New Territories. (minLength: 1)
• subregion_ids array nullable — Sub-region ids (e.g. 3011 Tsuen Wan).
• district_ids array nullable — District ids (e.g. 301103 Ma Wan).
• sm_district_ids array nullable — Small district ids (e.g. 30110003).
• combined_district_ids array nullable — Combined district ids (e.g. 301103-30110003).
• int_district_ids array nullable — Internal district ids used by the map UI (e.g. 53ND30003).
• int_sm_district_ids array nullable — Internal small district ids, 130 neighbourhoods (e.g. 130ND30008).
• lux_district_ids array nullable — Luxury district ids (e.g. 3011003).
• estate_ids array nullable — Estate ids (e.g. E000004419).
• phase_ids array nullable — Estate phase ids (e.g. P000000889).
• building_ids array nullable — Building ids (e.g. B000047232).
• street_ids array nullable — Street ids.
• house_street_ids array nullable — Village-house street ids.
• mtr_ids array nullable — MTR station ids.
• walking_duration integer nullable — Max walking time in seconds to the selected MTR station. Only applied together with mtr_ids; the widest catchment the data holds is reached at 900. (min: 1)
• school_net string nullable — Primary school net code (e.g. 62 for Tsuen Wan). (minLength: 1)
• university_ids array nullable — Universities whose neighbourhoods should be covered. (one of: "U01", "U02", "U03", "U04", "U05", "U06", "U07", "U08", "U09", "U10", "U11", "U12", "U13")
• min_price number nullable — Minimum price. Only applied together with transaction_type. (min: 0)
• max_price number nullable — Maximum price. Only applied together with transaction_type. (min: 0)
• min_area number nullable — Minimum gross area. (min: 0)
• max_area number nullable — Maximum gross area. (min: 0)
• min_net_area number nullable — Minimum saleable area. (min: 0)
• max_net_area number nullable — Maximum saleable area. (min: 0)
• min_net_ft_price number nullable — Minimum price per saleable area unit. (min: 0)
• max_net_ft_price number nullable — Maximum price per saleable area unit. (min: 0)
• min_ft_price number nullable — Minimum price per gross area unit. (min: 0)
• max_ft_price number nullable — Maximum price per gross area unit. (min: 0)
• bedrooms array nullable — Bedroom counts (0 = studio). (one of: "0", "1", "2", "3", "4+")
• master_bedrooms array nullable — Master bedroom counts. (one of: "1", "2", "3+")
• bathrooms array nullable — Bathroom counts. (one of: "1", "2", "3+")
• other_rooms array nullable — Other room counts. (one of: "1", "2", "3+")
• floor_levels array nullable — Floor bands: high, middle, low. (one of: "H", "M", "L")
• flat string nullable — Flat letter or number within the floor. Only applied together with building_ids. (minLength: 1)
• orientations array nullable — Compass orientations. (one of: "N", "NE", "E", "SE", "S", "SW", "W", "NW")
• views array nullable — Outlook types such as sea, garden or mountain. (one of: "MISCF00037", "MISCF00039", "MISCF00036", "MISCF00035", "MISCF00042", "MISCF00049", "MISCF00047", "MISCF00041", "MISCF00050", "MISCF00051")
• garden_features array nullable — Special unit features such as balcony or rooftop. (one of: "MISCF00015", "MISCF00072", "MISCF00070", "MISCF00016", "MISCF00014", "MISCF00013", "MISCF00067", "MISCF00071", "MISCF00024", "MISCF00025", "MISCF00077", "MISCF00044", "MISCF00052", "MISCF00001", "MISCF00005", "MISCF00004")
• decorations array nullable — Decoration state. (one of: "MISCF00002", "MISCF00003")
• facilities array nullable — Unit-level facilities. (one of: "MISCF00009", "MISCF00007", "MISCF00011", "MISCF00010", "MISCF00048")
• facility_groups array nullable — Estate-level facility groups. (one of: "FM02", "FM12", "FM01", "FM07", "FM10", "FM05", "FM09", "FM13", "FM14")
• nearby_facilities array nullable — Required nearby amenities. (one of: "carpark", "mall", "recreation", "mtr", "hospital", "park")
• media array nullable — Only listings carrying these media types. (one of: "vr", "agent_video", "ai_decorate", "ai_talk")
• developer string nullable — Developer name (e.g. 新鴻基). (minLength: 1)
• star_ratings array nullable — Luxury star tiers for deluxe listings. (one of: "star4", "star5", "star6")
• lifestyles array nullable — Deluxe lifestyle themes. (one of: "LS01", "LS02", "LS03", "LS04", "LS05", "LS06", "LS07", "LS08", "LS09", "LS10", "LS11", "LS12", "LS13", "LS14", "LS15", "LS16", "LS17", "LS18")
• department_id string nullable — Only listings held by this Midland branch. (minLength: 1)
• licence_no string nullable — Only listings held by this agent EAA licence number. (minLength: 1)
• first_published string nullable — Only listings first published within this recency window. (one of: "7days")
• updated_after string nullable — Only listings updated on or after this date (YYYY-MM-DD).
• mortgage_percent integer nullable — Loan-to-value percentage used for the monthly payment estimate. (min: 1; max: 100)
• mortgage_term integer nullable — Mortgage term in years used for the monthly payment estimate. (min: 1; max: 40)

Response

• @type string (default: "MidlandPropertyCard")
• serial_no string required
• url string nullable
• transaction_types array (default: [])
• tags array (default: [])
• is_hos boolean nullable
• price number nullable
• previous_price number nullable
• price_hkd number nullable
• price_per_area number nullable
• price_per_net_area number nullable
• hos_price number nullable
• hos_price_hkd number nullable
• hos_price_per_area number nullable
• hos_price_per_net_area number nullable
• rent number nullable
• previous_rent number nullable
• rent_hkd number nullable
• rent_per_area number nullable
• rent_per_net_area number nullable
• monthly_payment number nullable
• monthly_payment_hkd number nullable
• hos_monthly_payment number nullable
• hos_monthly_payment_hkd number nullable
• mortgage_percent number nullable
• hos_mortgage_percent number nullable
• has_valuation boolean nullable
• area number nullable
• net_area number nullable
• net_area_ratio number nullable
• bedroom_count integer nullable
• sitting_room_count integer nullable
• floor_level object nullable
  • @type string (default: "MidlandRef")
  • id string nullable
  • name string nullable
• flat string nullable
• orientation object nullable
  • @type string (default: "MidlandRef")
  • id string nullable
  • name string nullable
• image string nullable
• images array (default: [])
• has_video boolean nullable
• has_agent_video boolean nullable
• has_photo360 boolean nullable
• feature_icons array (default: [])
• deluxe_star string nullable
• is_tenancy boolean nullable
• updated_at 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
• estate object nullable
  • @type string (default: "MidlandRef")
  • id string nullable
  • name string nullable
• phase object nullable
  • @type string (default: "MidlandRef")
  • id string nullable
  • name string nullable
• building object nullable
  • @type string (default: "MidlandBuilding")
  • id string nullable
  • name string nullable
  • address string nullable
  • first_op_at integer nullable
  • floor_count integer nullable
  • building_type string nullable
  • latitude number nullable
  • longitude number nullable
  • streetview_latitude number nullable
  • streetview_longitude number nullable
  • streetview_angle integer nullable
• features array (default: [])
  • @type string (default: "MidlandRef")
  • id string nullable
  • name string nullable
• facility_groups array (default: [])
  • @type string (default: "MidlandRef")
  • id string nullable
  • name string nullable
• amenities array (default: [])
  • @type string (default: "MidlandAmenity")
  • type string nullable
  • name string nullable
  • walking_minutes integer nullable
• mtr_stations array (default: [])
  • @type string (default: "MidlandMtrStation")
  • id string nullable
  • name string nullable
  • exit string nullable
  • walking_seconds integer nullable
• primary_school_net string nullable
• location object nullable
  • @type string (default: "MidlandLocation")
  • latitude number nullable
  • longitude number nullable
• agents array (default: [])
  • @type string (default: "MidlandAgent")
  • licence_no string nullable
  • name string nullable
  • name_en string nullable
  • nickname string nullable
  • job_title string nullable
  • image string nullable
  • phone string nullable
  • mobile_phone string nullable
  • china_mobile_phone string nullable
  • wechat_id string nullable
  • wechat_qr string nullable
  • department_id string nullable
  • url string nullable
  • is_owner boolean 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.