Bayleys APIbayleys.co.nz ↗
Access Bayleys NZ property listings, agent profiles, office details, auctions, news, and magazines via 12 structured API endpoints.
What is the Bayleys API?
The Bayleys NZ API covers 12 endpoints that expose property listings, agent profiles, office directories, upcoming auctions, news articles, and publications from bayleys.co.nz. You can query search_properties with filters for bedrooms, bathrooms, price range, and location keywords, then drill into any individual listing using get_property_details with the full URL slug. Each listing returns fields including address, saleInfo, images, icons, and features.
curl -X GET 'https://api.parse.bot/scraper/4574cfaa-dab1-4954-88c6-8df3ecce0f46/search_properties?page=1&bedrooms=3&keywords=Auckland&bathrooms=2&car_parks=1&max_price=5000000&min_price=100000&page_size=10®ion_id=1&order_type=LatestListing&suburb_ids=457&district_id=38&search_types=Residential' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace bayleys-co-nz-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Bayleys Real Estate API — bounded, re-runnable; every call capped."""
from parse_apis.bayleys_real_estate_api import Bayleys, SearchType, Order, ListingNotFound
client = Bayleys()
# Search residential listings sorted by latest, capped at 3 items
for listing in client.listings.search(
search_types=SearchType.RESIDENTIAL,
keywords="Auckland",
order_type=Order.LATEST_LISTING,
limit=3,
):
print(listing.heading, listing.marketing_address, listing.sale_info)
# Drill into one listing's icons (beds/baths/parking)
listing = client.listings.search(keywords="Devonport", limit=1).first()
if listing:
print(listing.heading, listing.region, listing.district)
for icon in listing.listing_icons:
print(f" {icon.name}: {icon.value}")
# Browse upcoming auctions
for auction in client.listings.list_auctions(limit=3):
print(auction.heading, auction.auction_date, auction.event_location)
# Search agents and browse their listings
agent = client.agents.search(keywords="Alice", limit=1).first()
if agent:
print(agent.first_name, agent.last_name, agent.specialty)
for ag_listing in agent.listings.list(limit=2):
print(f" {ag_listing.heading} - {ag_listing.marketing_address}")
# Search offices
for office in client.offices.search(keywords="Auckland", limit=3):
print(office.branch_name, office.address, office.number_of_listings)
# Get full listing details by slug
detail = client.listingdetails.get(slug="/listings/residential/auckland/north-shore/7a-matai-road-devonport-1470838")
print(detail.listing_id)
# Handle a not-found listing gracefully
try:
results = client.listings.search(keywords="nonexistent-xyz-99999", limit=1).first()
if results:
print(results.heading)
except ListingNotFound as exc:
print(f"Listing not found: {exc.slug}")
print("exercised: listings.search / listings.list_auctions / agents.search / agent.listings.list / offices.search / listingdetails.get / ListingNotFound")
Search for property listings with filters including location, price range, bedrooms, and property type. Returns paginated results ordered by the specified sort. Supports all property types (Residential, Commercial, Rural, Lifestyle, Business) via comma-separated search_types. Each result includes address, sale info, images, icons (beds/baths/parking), and features.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination. |
| bedrooms | integer | Minimum number of bedrooms. |
| keywords | string | Search keywords (e.g. location name, listing ID). |
| bathrooms | integer | Number of bathrooms. |
| car_parks | integer | Number of car parks. |
| max_price | integer | Maximum price filter. |
| min_price | integer | Minimum price filter. |
| page_size | integer | Number of results per page. |
| region_id | integer | Region ID to filter by. |
| order_type | string | Sort order type. |
| suburb_ids | string | Suburb IDs to filter by. |
| district_id | integer | District ID to filter by. |
| search_types | string | Property type filter. Comma-separated for multiple. |
{
"type": "object",
"fields": {
"page": "current page number",
"items": "array of property listing summaries",
"pageSize": "results per page",
"totalItems": "total number of matching listings",
"numberOfPages": "total pages available"
},
"sample": {
"data": {
"page": 1,
"items": [
{
"region": "Waikato",
"suburb": "Hamilton East",
"heading": "Spacious FURNISHED Apartment",
"district": "Hamilton",
"latitude": -37.7972835,
"saleInfo": "For Rent NZ$500",
"heroImage": "2431038_1.jpg",
"listingId": 2431038,
"longitude": 175.292101,
"auctionDate": null,
"listingIcons": [
{
"name": "bed",
"value": "2",
"suffix": null
}
],
"eventLocation": null,
"listingFeatures": [
"Furnishings",
"Layout",
"Parking"
],
"marketingAddress": "123 Main St, Springfield, IL 62704",
"listingTypeDescription": "Rental"
}
],
"pageSize": 10,
"totalItems": 4042,
"numberOfPages": 0
},
"status": "success"
}
}About the Bayleys API
Property Search and Listing Details
The search_properties endpoint accepts filters for min_price, max_price, bedrooms, bathrooms, car_parks, and free-text keywords. Results are paginated and each item in the items array includes listingId, address, saleInfo, images, icons, and features. A convenience endpoint, search_residential_properties, applies the Residential type filter automatically. Note that numberOfPages may return 0 in some responses due to a known upstream issue; use totalItems and pageSize to calculate page count independently.
For full listing details, get_property_details requires the complete slug path — including region, district, address, and listing ID segments — and returns a listing object with address, description, agents, images, and sale information, alongside an office object for the listing branch.
Agents and Offices
search_people accepts keywords and region_id to locate agents, returning personnelId, name, position, contact details, and branch information. From there, get_agent_profile fetches a full bio, awards, and current listings by slug in the format /agents/{firstname}-{lastname}-{personnelId}. The get_agent_listings endpoint takes a numeric agent_id and returns paginated property summaries for that agent.
Office lookup follows the same pattern: search_offices returns branchId, branchName, address, telephone, email, and numberOfListings. get_office_profile and get_office_listings accept a slug or office_id respectively and return full office details alongside current listing summaries.
Auctions, News, and Magazines
get_upcoming_auctions returns scheduled auction listings across all property types, with each item including auctionDate and eventLocation. get_news supports tag-based filtering (e.g., Residential, Commercial) and returns article objects with title, description, url, tags, and publishedDate. get_magazines returns Bayleys publication issues with issueDate, title, description, image, and url, along with pagingMetadata that includes totalRecords, currentPage, pageSize, and pageCount.
The Bayleys API is a managed, monitored endpoint for bayleys.co.nz — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when bayleys.co.nz changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official bayleys.co.nz API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a property search tool filtered by bedroom count, price range, and location using
search_properties. - Display upcoming auction schedules with dates and event locations from
get_upcoming_auctions. - Create an agent directory that surfaces contact details and current listings per agent via
search_peopleandget_agent_listings. - Track listing counts per Bayleys office across New Zealand using
search_officesand thenumberOfListingsfield. - Aggregate Bayleys market commentary and reports by tag using
get_newswith thetagsfilter. - Embed Bayleys magazine covers and issue links in a publications feed using
get_magazinesresponse fields. - Sync a CRM with full property details, agent assignments, and office data by chaining
search_properties,get_property_details, andget_agent_profile.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Bayleys have an official public developer API?+
How do I filter property searches by type — for example, residential only?+
search_residential_properties applies the Residential type filter automatically and accepts page and page_size parameters. For other property types, use search_properties with a relevant keywords value. The response items array includes saleInfo and features fields that further describe each listing.Why does `numberOfPages` sometimes return 0?+
search_properties, get_agent_listings, and get_upcoming_auctions. To determine total pages, divide totalItems by pageSize and round up. The totalItems field is reliably populated.Does the API cover sold or historical listings?+
search_properties, get_agent_listings, and get_office_listings all reflect current inventory. You can fork this API on Parse and revise it to add an endpoint targeting Bayleys' sold properties pages.Can I retrieve listings filtered by a specific geographic region ID?+
search_people and search_offices both accept a region_id parameter for region-scoped results. The get_agent_profile response includes a searchContext object with region and property type reference data that can be used to identify valid region IDs. Direct region filtering on search_properties is not currently exposed as a named parameter; keywords can be used to target a location by name. You can fork this API on Parse and revise it to add a dedicated region filter parameter to the property search endpoint.