# Property24 — South Africa property listings (for sale & to rent)

> Search Property24 listings in any South African province, city, suburb or estate — for sale or to rent — with the portal's own filters. Give a place name in `location` (it is resolved against Property24's own area index) or an exact `area_id` from the `location` action. Returns 22 listings per page with numeric ZAR price, bedrooms, bathrooms, parking, floor and erf size, suburb, street address, agency, photo and the listing URL. Promoted (paid-placement) rows are returned too and are flagged `promoted: true`, so they can be kept or filtered out — they are never silently mixed in.
> ReefAPI engine `property24` · 3 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/property24/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http). Clients that add connectors by URL, such as ChatGPT and the Claude app, connect with OAuth 2.1 (the user pastes their key once on a ReefAPI page; discovery at `/.well-known/oauth-protected-resource/mcp`). Config files send the key as `Authorization: Bearer <key>`. `?key=<key>` in the URL also works as a last-resort fallback.

## Endpoints

### POST https://api.reefapi.com/property24/v1/search — 1 credit
Search Property24 listings in any South African province, city, suburb or estate — for sale or to rent — with the portal's own filters. Give a place name in `location` (it is resolved against Property24's own area index) or an exact `area_id` from the `location` action. Returns 22 listings per page with numeric ZAR price, bedrooms, bathrooms, parking, floor and erf size, suburb, street address, agency, photo and the listing URL. Promoted (paid-placement) rows are returned too and are flagged `promoted: true`, so they can be kept or filtered out — they are never silently mixed in.

**Parameters:**
- `location` (string, required) — South African province, city, suburb or estate name, e.g. 'Sea Point', 'Sandton', 'Umhlanga', 'Western Cape'. Resolved against Property24's own area index; if nothing matches the call succeeds with zero rows and `matched: false` rather than guessing a different place. Optional only when `area_id` is given.
- `area_id` (integer, optional) — Exact Property24 area id from the `location` action. Skips name resolution. Must be sent together with `area_type`, because the same number means a different place in each area level.
- `area_type` (enum, optional, default "suburb") — Which area level `area_id` belongs to. Required whenever `area_id` is used. [one of: province, city, suburb, estate]
- `listing_type` (enum, optional, default "sale") — Sale listings or rental listings. [one of: sale, rent]
- `property_type` (enum, optional) — Restrict to one property type. Omit for every type. Bedroom and bathroom filters do not apply to vacant_land, farm, commercial or industrial — Property24 publishes no bedroom count for those. [one of: house, apartment, townhouse, vacant_land, farm, commercial, industrial]
- `price_min` (integer, optional) — Lowest price in ZAR (rand). For rentals this is the rent, in the period Property24 publishes it.
- `price_max` (integer, optional) — Highest price in ZAR (rand).
- `bedrooms_min` (integer, optional) — At least this many bedrooms (Property24's own '3+' filter).
- `bathrooms_min` (integer, optional) — At least this many bathrooms.
- `parking_min` (integer, optional) — At least this many parking spaces / garages.
- `size_min` (integer, optional) — Smallest size in m², using Property24's own size filter (floor size for built property, erf size for land).
- `size_max` (integer, optional) — Largest size in m².
- `sort` (enum, optional, default "default") — Result order. 'default' is Property24's own ranking, which puts paid placements first. [one of: default, price_low, price_high, newest, type, size]
- `page` (integer, optional, default 1) — 1-based result page; 22 listings per page.
- `on_show` (boolean, optional, default false) — Only listings with a show day scheduled.
- `on_auction` (boolean, optional, default false) — Only listings going to auction.
- `repossessed` (boolean, optional, default false) — Only bank-repossessed listings.
- `retirement` (boolean, optional, default false) — Only retirement-village property.

**Returns:** {area:{area_id,name,parent_name,area_type}, matched, page, page_size, total_pages, listings:[{listing_number,url,title,price:{amount,currency,formatted,source_is_machine_value},bedrooms,bathrooms,parking_spaces,floor_size_m2,erf_size_m2,gross_lettable_area_m2,suburb,address,excerpt,primary_photo_url,agency:{name,profile_url},agent:{name},badges,promoted,boosted}]}. `price.formatted` is Property24's own rendered string, kept next to the parsed number so the two can be compared. A value Property24 does not publish is null.

**Example request body:**
```json
{
  "location": "Sea Point"
}
```

### POST https://api.reefapi.com/property24/v1/detail — 1 credit
Full record for one Property24 listing, by listing URL or by the listing number a search row returns. Adds what the result tile does not carry: the complete description, the feature list, levies, rates and taxes, price per m², listing date, street address, every photo, map coordinates and the agency. The agent's personal name and phone numbers are returned only with `include_pii`.

**Parameters:**
- `listing` (string, required) — A Property24 listing URL (https://www.property24.com/for-sale/…/117658301) or the bare listing number (117658301) from a search row.

**Returns:** {listing_number,url,title,listing_type,price:{amount,currency,formatted},address,property_type,listing_date,bedrooms,bathrooms,parking_spaces,erf_size_m2,floor_size_m2,price_per_m2,levies,rates_and_taxes,pets_allowed,description,features[],photos[],photo_count,latitude,longitude,agency:{name,profile_url},agent:{name,profile_url,phone_numbers},overview{}}. `overview` is Property24's own key/value table, verbatim, for anything not promoted to a named field.

**Example request body:**
```json
{
  "listing": "117658301"
}
```

### POST https://api.reefapi.com/property24/v1/location — 1 credit
Resolve free text to Property24's own area ids, so a search can be pinned to an exact place instead of a name. Returns the matching provinces, cities, suburbs and estates with their id, level and ready-made for-sale and to-rent search URLs. Property24's metro sub-regions (e.g. 'Pretoria East') are returned with `searchable: false` — they have an id but no working listing route, and are reported rather than silently pointed at another place.

**Parameters:**
- `query` (string, required) — Place name to resolve, e.g. 'Umhlanga', 'Sandton', 'Stellenbosch'.
- `limit` (integer, optional, default 10) — Maximum areas to return.

**Returns:** {query, matched, areas:[{area_id,name,parent_name,area_type,searchable,for_sale_url,to_rent_url}]}. `matched:false` with an empty list means Property24's area index has nothing for that text — the endpoint never falls back to an unrelated place.

**Example request body:**
```json
{
  "query": "Umhlanga"
}
```

## At scale
- **Volume:** 5M+ requests a day, measured at 60 requests a second across the fleet with no
  central bottleneck. Per-key limits are raised for high-volume accounts; volume pricing on request.
- **Missing a source:** tell us a site we do not cover and it becomes an engine. A customer asked
  for bestprice.gr on 21 Sep 2026 and it was in the catalog on 22 Sep.
- **Support:** 2 minute median time from a question in the live chat to the first answer. Setup
  help included, no support tier to buy.
- **One key, one credit pool** across every API. No per-site plans, no separate subscriptions.

## More
- Try it live, no code: https://reefapi.com/playground?engine=property24
- Human docs page: https://reefapi.com/docs/property24
- Overview page: https://reefapi.com/property24-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt
