Website logo

SuburbPulse unified property search

SuburbPulse unified property search returning listings across six sections: new, sold, withdrawn, over 90 days old, price changed, and sell type changed. Supports filtering by location (up to 10 suburbs/districts/regions), price, bedrooms, bathrooms, timeframe, and status. Uses per-section offset pagination. Internal-only POST endpoint.

URL: https://api.trademe.co.nz/v1/Search/Property/SuburbPulse.{file_format}
HTTP Method: POST
Requires Authentication? Yes
Permission Required: None
Supported Formats: XML, JSON
Rate Limited? Yes

URL parameters

file_format Enumeration (required) The format of the response.
xml Serialize responses into XML.
json Serialize responses into JSON.

POST Data

<SuburbPulseSearchRequest>

SearchLocations Collection of <SearchLocation> (optional)

Search locations - suburbs, districts, or regions (max 10)
SuburbId Integer (optional) SuburbId
DistrictId Integer (optional) DistrictId
RegionId Integer (optional) RegionId
PriceMin Number (optional)

Minimum price in NZD
PriceMax Number (optional)

Maximum price in NZD
BedroomsMin Integer (optional)

Minimum number of bedrooms
BedroomsMax Integer (optional)

Maximum number of bedrooms
BathroomsMin Integer (optional)

Minimum number of bathrooms
BathroomsMax Integer (optional)

Maximum number of bathrooms
Timeframe String (optional)

Calendar-day-based timeframe that scopes all filters, aligned to start of day in NZ time. Values: "today" (default), "last_2_days", "last_1_week", "last_2_weeks"
Statuses Collection of String (optional)

Which statuses to include. If empty/null, all statuses are included. Values: "new", "sold", "withdrawn", "over_90_days", "price_changed", "sell_type_changed"
PageSize Integer (optional)

Page size (number of items per page, default 20, max 100)
Offsets <PropertyStatusOffsets> (optional)

Offsets tracking progress through each status
New Integer (optional) New
Sold Integer (optional) Sold
Withdrawn Integer (optional) Withdrawn
Over90Days Integer (optional) Over90Days
PriceChanged Integer (optional) PriceChanged
SellTypeChanged Integer (optional) SellTypeChanged

Returns

<SuburbPulseSearchResponse>

The search results.

Items Collection of <SuburbPulseListing> or null Items
ListingId Integer ListingId
Title String or null Title
Address String or null Address
SuburbName String or null SuburbName
PhotoId Integer or null PhotoId
Agents Collection of <SuburbPulseAgent> or null Agents
AgentName String or null

Agent's full name
AgentMemberId Integer or null

Agent member ID - used to construct agent profile photo URL
AgentProfilePhotoVersion Integer or null

Agent profile photo version - used to construct agent profile photo URL
Office <Office> or null Office
AgencyName String or null

Agency name
BannerImage String or null

Banner image URL
BackgroundColor String or null

Background color (hex code)
TextColor String or null

Text color (hex code)
StartDate DateTime or null StartDate
EndDate DateTime or null EndDate
Bedrooms Integer or null Bedrooms
Bathrooms Integer or null Bathrooms
SoldPrice Number or null SoldPrice
DisplayPrice String or null DisplayPrice
StatusChangedEntry <SuburbPulseStatusChangedEntry> or null StatusChangedEntry
Status String or null

The type of status change
Date DateTime or null

When the status change occurred
OldValue String or null

The previous value before the change
NewValue String or null

The new value after the change
SoldPropertyId Integer or null

ID of the agent_sold_property record. Only present for listings sourced from agent sold property data.
Count Integer Count
NextOffsets <PropertyStatusOffsets> or null NextOffsets
New Integer New
Sold Integer Sold
Withdrawn Integer Withdrawn
Over90Days Integer Over90Days
PriceChanged Integer PriceChanged
SellTypeChanged Integer SellTypeChanged
HasMore Boolean HasMore
TotalCount Integer or null TotalCount
StatusCounts <PropertyStatusCounts> or null StatusCounts
New Integer New
Sold Integer Sold
Withdrawn Integer Withdrawn
Over90Days Integer Over90Days
PriceChanged Integer PriceChanged
SellTypeChanged Integer SellTypeChanged

Example XML Request (switch to JSON) 

<SuburbPulseSearchRequest xmlns="http://api.trademe.co.nz/v1">
  <SearchLocations>
    <SearchLocation>
      <SuburbId>123</SuburbId>
      <DistrictId>123</DistrictId>
      <RegionId>123</RegionId>
    </SearchLocation>
    <SearchLocation>
      <SuburbId>123</SuburbId>
      <DistrictId>123</DistrictId>
      <RegionId>123</RegionId>
    </SearchLocation>
  </SearchLocations>
  <PriceMin>123.0</PriceMin>
  <PriceMax>123.0</PriceMax>
  <BedroomsMin>123</BedroomsMin>
  <BedroomsMax>123</BedroomsMax>
  <BathroomsMin>123</BathroomsMin>
  <BathroomsMax>123</BathroomsMax>
  <Timeframe>ABC</Timeframe>
  <Statuses>
    <string>ABC</string>
    <string>ABC</string>
  </Statuses>
  <PageSize>123</PageSize>
  <Offsets>
    <New>123</New>
    <Sold>123</Sold>
    <Withdrawn>123</Withdrawn>
    <Over90Days>123</Over90Days>
    <PriceChanged>123</PriceChanged>
    <SellTypeChanged>123</SellTypeChanged>
  </Offsets>
</SuburbPulseSearchRequest>

Example JSON Request (switch to XML) 

{
  "SearchLocations": [
    {
      "SuburbId": 123,
      "DistrictId": 123,
      "RegionId": 123
    },
    {
      "SuburbId": 123,
      "DistrictId": 123,
      "RegionId": 123
    }
  ],
  "PriceMin": 123.0,
  "PriceMax": 123.0,
  "BedroomsMin": 123,
  "BedroomsMax": 123,
  "BathroomsMin": 123,
  "BathroomsMax": 123,
  "Timeframe": "ABC",
  "Statuses": [
    "ABC",
    "ABC"
  ],
  "PageSize": 123,
  "Offsets": {
    "New": 123,
    "Sold": 123,
    "Withdrawn": 123,
    "Over90Days": 123,
    "PriceChanged": 123,
    "SellTypeChanged": 123
  }
}

Example XML Response (switch to JSON) 

<SuburbPulseSearchResponse xmlns="http://api.trademe.co.nz/v1">
  <Items>
    <SuburbPulseListing>
      <ListingId>123</ListingId>
      <Title>ABC</Title>
      <Address>ABC</Address>
      <SuburbName>ABC</SuburbName>
      <PhotoId>123</PhotoId>
      <Agents>
        <SuburbPulseAgent>
          <AgentName>ABC</AgentName>
          <AgentMemberId>123</AgentMemberId>
          <AgentProfilePhotoVersion>123</AgentProfilePhotoVersion>
        </SuburbPulseAgent>
        <SuburbPulseAgent>
          <AgentName>ABC</AgentName>
          <AgentMemberId>123</AgentMemberId>
          <AgentProfilePhotoVersion>123</AgentProfilePhotoVersion>
        </SuburbPulseAgent>
      </Agents>
      <Office>
        <AgencyName>ABC</AgencyName>
        <BannerImage>ABC</BannerImage>
        <BackgroundColor>ABC</BackgroundColor>
        <TextColor>ABC</TextColor>
      </Office>
      <StartDate>2018-01-01T00:00:00Z</StartDate>
      <EndDate>2018-01-01T00:00:00Z</EndDate>
      <Bedrooms>123</Bedrooms>
      <Bathrooms>123</Bathrooms>
      <SoldPrice>123.0</SoldPrice>
      <DisplayPrice>ABC</DisplayPrice>
      <StatusChangedEntry>
        <Status>ABC</Status>
        <Date>2018-01-01T00:00:00Z</Date>
        <OldValue>ABC</OldValue>
        <NewValue>ABC</NewValue>
      </StatusChangedEntry>
      <SoldPropertyId>123</SoldPropertyId>
    </SuburbPulseListing>
    <SuburbPulseListing>
      <ListingId>123</ListingId>
      <Title>ABC</Title>
      <Address>ABC</Address>
      <SuburbName>ABC</SuburbName>
      <PhotoId>123</PhotoId>
      <Agents>
        <SuburbPulseAgent>
          <AgentName>ABC</AgentName>
          <AgentMemberId>123</AgentMemberId>
          <AgentProfilePhotoVersion>123</AgentProfilePhotoVersion>
        </SuburbPulseAgent>
        <SuburbPulseAgent>
          <AgentName>ABC</AgentName>
          <AgentMemberId>123</AgentMemberId>
          <AgentProfilePhotoVersion>123</AgentProfilePhotoVersion>
        </SuburbPulseAgent>
      </Agents>
      <Office>
        <AgencyName>ABC</AgencyName>
        <BannerImage>ABC</BannerImage>
        <BackgroundColor>ABC</BackgroundColor>
        <TextColor>ABC</TextColor>
      </Office>
      <StartDate>2018-01-01T00:00:00Z</StartDate>
      <EndDate>2018-01-01T00:00:00Z</EndDate>
      <Bedrooms>123</Bedrooms>
      <Bathrooms>123</Bathrooms>
      <SoldPrice>123.0</SoldPrice>
      <DisplayPrice>ABC</DisplayPrice>
      <StatusChangedEntry>
        <Status>ABC</Status>
        <Date>2018-01-01T00:00:00Z</Date>
        <OldValue>ABC</OldValue>
        <NewValue>ABC</NewValue>
      </StatusChangedEntry>
      <SoldPropertyId>123</SoldPropertyId>
    </SuburbPulseListing>
  </Items>
  <Count>123</Count>
  <NextOffsets>
    <New>123</New>
    <Sold>123</Sold>
    <Withdrawn>123</Withdrawn>
    <Over90Days>123</Over90Days>
    <PriceChanged>123</PriceChanged>
    <SellTypeChanged>123</SellTypeChanged>
  </NextOffsets>
  <HasMore>false</HasMore>
  <TotalCount>123</TotalCount>
  <StatusCounts>
    <New>123</New>
    <Sold>123</Sold>
    <Withdrawn>123</Withdrawn>
    <Over90Days>123</Over90Days>
    <PriceChanged>123</PriceChanged>
    <SellTypeChanged>123</SellTypeChanged>
  </StatusCounts>
</SuburbPulseSearchResponse>

Example JSON Response (switch to XML) 

{
  "Items": [
    {
      "ListingId": 123,
      "Title": "ABC",
      "Address": "ABC",
      "SuburbName": "ABC",
      "PhotoId": 123,
      "Agents": [
        {
          "AgentName": "ABC",
          "AgentMemberId": 123,
          "AgentProfilePhotoVersion": 123
        },
        {
          "AgentName": "ABC",
          "AgentMemberId": 123,
          "AgentProfilePhotoVersion": 123
        }
      ],
      "Office": {
        "AgencyName": "ABC",
        "BannerImage": "ABC",
        "BackgroundColor": "ABC",
        "TextColor": "ABC"
      },
      "StartDate": "\/Date(1514764800)\/",
      "EndDate": "\/Date(1514764800)\/",
      "Bedrooms": 123,
      "Bathrooms": 123,
      "SoldPrice": 123.0,
      "DisplayPrice": "ABC",
      "StatusChangedEntry": {
        "Status": "ABC",
        "Date": "\/Date(1514764800)\/",
        "OldValue": "ABC",
        "NewValue": "ABC"
      },
      "SoldPropertyId": 123
    },
    {
      "ListingId": 123,
      "Title": "ABC",
      "Address": "ABC",
      "SuburbName": "ABC",
      "PhotoId": 123,
      "Agents": [
        {
          "AgentName": "ABC",
          "AgentMemberId": 123,
          "AgentProfilePhotoVersion": 123
        },
        {
          "AgentName": "ABC",
          "AgentMemberId": 123,
          "AgentProfilePhotoVersion": 123
        }
      ],
      "Office": {
        "AgencyName": "ABC",
        "BannerImage": "ABC",
        "BackgroundColor": "ABC",
        "TextColor": "ABC"
      },
      "StartDate": "\/Date(1514764800)\/",
      "EndDate": "\/Date(1514764800)\/",
      "Bedrooms": 123,
      "Bathrooms": 123,
      "SoldPrice": 123.0,
      "DisplayPrice": "ABC",
      "StatusChangedEntry": {
        "Status": "ABC",
        "Date": "\/Date(1514764800)\/",
        "OldValue": "ABC",
        "NewValue": "ABC"
      },
      "SoldPropertyId": 123
    }
  ],
  "Count": 123,
  "NextOffsets": {
    "New": 123,
    "Sold": 123,
    "Withdrawn": 123,
    "Over90Days": 123,
    "PriceChanged": 123,
    "SellTypeChanged": 123
  },
  "HasMore": false,
  "TotalCount": 123,
  "StatusCounts": {
    "New": 123,
    "Sold": 123,
    "Withdrawn": 123,
    "Over90Days": 123,
    "PriceChanged": 123,
    "SellTypeChanged": 123
  }
}