Listing feed format

How a feed reaches us

• We fetch it. The agent gives us an https:// address; we read it about once an hour.
• You send it. The agent gets a private address (https://propertyhq.co.za/api/feeds/<secret>); your software POSTs the feed to it as often as you like - at most once a minute.
• Either way it's the same file, up to 10 MB and 2,000 listings. The agent needs an Agent plan, and switches the feed on themselves in My listings > Listing feed.

An example (JSON)

{
  "listings": [
    {
      "ref": "PC-10442",
      "status": "active",
      "kind": "sale",
      "title": "Family home with solar in Bryanston",
      "description": "Four bedrooms, pool, double garage, borehole.",
      "type": "house",
      "price": 4250000,
      "suburb": "Bryanston",
      "city": "Sandton",
      "province": "Gauteng",
      "address": "12 Main Road",
      "bedrooms": 4,
      "bathrooms": 3,
      "garages": 2,
      "floorSizeM2": 320,
      "standSizeM2": 1200,
      "tenure": "freehold",
      "powerWater": ["solar", "inverter", "borehole"],
      "mandate": "sole",
      "photos": ["https://cdn.example.com/10442/1.jpg", "https://cdn.example.com/10442/2.jpg"]
    },
    { "ref": "PC-10377", "status": "sold" }
  ]
}

The same listing as XML

<listings>
  <listing ref="PC-10442">
    <status>active</status>
    <kind>sale</kind>
    <title>Family home with solar in Bryanston</title>
    <type>house</type>
    <price>4250000</price>
    <suburb>Bryanston</suburb>
    <province>Gauteng</province>
    <bedrooms>4</bedrooms>
    <bathrooms>3</bathrooms>
    <powerWater><item>solar</item><item>borehole</item></powerWater>
    <photos><photo>https://cdn.example.com/10442/1.jpg</photo></photos>
  </listing>
  <listing ref="PC-10377"><status>sold</status></listing>
</listings>

Fields

ref

Required. Your system's own reference for the listing, up to 128 characters. How the next feed finds the same listing again - never change it.

status

active (default), under offer, sold, let or withdrawn. Sold, let and withdrawn only need the ref.

kind

sale (default) or rent. For rent, price is the monthly rent.

title, description

Title is required; description up to 4,000 characters.

type

Required: house, townhouse, flat, duet, commercial, land or student (apartment, cluster, simplex, vacant land and similar words are understood).

price, currency

Required price. Currency ZAR (default), USD, GBP, EUR or AUD.

suburb, city, province

Suburb and province are required. Province: the full name (Western Cape) or GP, WC, KZN, EC, LP, MP, NW, NC, FS.

address

Street address (optional). Shown to buyers when given.

bedrooms, bathrooms, garages

Bedrooms and bathrooms (at least 1 each) for everything except land and commercial.

floorSizeM2, standSizeM2

Optional, in square metres.

levies, ratesAndTaxes

Optional monthly amounts, in the listing's currency.

tenure

freehold, sectional title, share block or leasehold (optional).

deposit, leaseTermMonths, availableFrom, pets

Rentals: deposit, lease length, a date like 2026-12-01, and yes / no / by arrangement.

powerWater

A list from: solar, inverter, generator, borehole, water tank, solar geyser.

mandate

sole, open or joint - for a listing that differs from the agent's default.

videoUrl, tourUrl

YouTube or Vimeo video; Matterport, Kuula or Sketchfab tour. Others are left out.

photos

A list of https:// picture addresses (JPEG, PNG or WebP, each under 5 MB), best picture first.

What we do with it

• A listing with a ref we haven't seen is created; one we have is updated (price changes are kept in its price history).
• status of sold, let or withdrawn closes the listing. under offer adds the "Under offer" label.
• A listing that used to be in the feed and isn't any more is taken down - unless more than half of an agent's listings vanish at once, which looks like a broken feed, so we leave them up and tell the agent.
• Each listing is checked like one typed in by hand. One that can't be used is skipped with a plain sentence the agent sees on their Listing feed page; the rest carry on. A push answers with the same details.
• Photos are fetched from the https:// addresses, checked, and re-saved without location data (up to 8 per listing).
• The feed never changes a listing's type, suburb, province or currency once it is up - the agent withdraws and lists again if one of those was wrong.

Supplier of agency software?

We'd like your agents to be able to switch this on from inside your product. If your system already publishes a feed in another layout, tell us which and we'll look at reading it. Write to us through the contact form.