# realestate.co.nz API scraper (New Zealand) - search NZ homes for sale and for rent, rural, commercial and business listings by region, district or suburb, bedrooms, bathrooms, price, land area, property type and sale method; full listings with address, coordinates, photos, open homes, agents with phone and email, and agency; recently sold properties with sale price, council valuation (CV) and the site's estimate; property sales history; agents and agencies. Prices in NZD. No account, no browser.

> Search realestate.co.nz listings: homes for sale (default) or for rent, rural, commercial or business. Filter by region, district or suburb (names or ids), price, bedrooms, bathrooms, land and floor area, car parks, property type, sale method (auction, tender, deadline sale, negotiation, asking price …), keyword, open homes, new builds, pets and furnishing for rentals, agent or agency. Every row carries the listing URL, address and coordinates, the price exactly as shown plus the figure in it, sale method and auction/tender/deadline date, bedrooms, bathrooms, land and floor area, photos, open homes, and the listing agents (name, phone, mobile, email) with their agency.
> ReefAPI engine `realestate-nz` · 7 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/realestate-nz/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/realestate-nz/v1/search — 2 credits
Search realestate.co.nz listings: homes for sale (default) or for rent, rural, commercial or business. Filter by region, district or suburb (names or ids), price, bedrooms, bathrooms, land and floor area, car parks, property type, sale method (auction, tender, deadline sale, negotiation, asking price …), keyword, open homes, new builds, pets and furnishing for rentals, agent or agency. Every row carries the listing URL, address and coordinates, the price exactly as shown plus the figure in it, sale method and auction/tender/deadline date, bedrooms, bathrooms, land and floor area, photos, open homes, and the listing agents (name, phone, mobile, email) with their agency.

**Parameters:**
- `category` (enum, optional, default "residential_sale") — What to search: homes for sale (default) or for rent, rural, commercial sale or lease, businesses. `purpose`=sale|rent also works. [one of: residential_sale, residential_rent, rural_sale, commercial_sale, commercial_lease, business_sale]
- `region` (array, optional) — Region name or id (Auckland = 35, Wellington, Canterbury, Waikato, Bay of Plenty …). One or several. `locations` lists every region, district and suburb with ids.
- `district` (array, optional) — District name or id (Auckland City, North Shore City, Wellington City, Christchurch City …). One or several.
- `suburb` (array, optional) — Suburb name, id or fq_slug. One or several. A name used by several suburbs (e.g. Hillcrest) is chosen by the region/district you also give, otherwise the request lists the candidates. The narrowest level wins: region=Auckland + suburb=Ponsonby searches Ponsonby.
- `include_nearby_suburbs` (boolean, optional) — Also include the suburbs the site lists as neighbours of the given suburb(s).
- `price_min` (number, optional) — Lowest price, NZD (per week for residential rent). The site filters on the agent's search price, so listings shown as Auction / Negotiation can match.
- `price_max` (number, optional) — Highest price, NZD (per week for residential rent).
- `bedrooms_min` (integer, optional) — Fewest bedrooms.
- `bedrooms_max` (integer, optional) — Most bedrooms.
- `bathrooms_min` (integer, optional) — Fewest bathrooms.
- `bathrooms_max` (integer, optional) — Most bathrooms.
- `land_area_min` (number, optional) — Smallest land area in square metres (1 ha = 10000).
- `land_area_max` (number, optional) — Largest land area in square metres.
- `floor_area_min` (number, optional) — Smallest floor area in square metres.
- `floor_area_max` (number, optional) — Largest floor area in square metres.
- `carparks_min` (integer, optional) — Fewest car parks.
- `property_type` (array, optional) — One or several property types. Residential sale: house, apartment, townhouse, unit, section, lifestyle_property, lifestyle_section, home_and_income, studio, retirement_living, multiple_properties, carpark, boat_shed. Rent: house, apartment, unit, townhouse, studio, lifestyle_property, holiday_rental, section, retirement_living, carpark, boat_shed. Rural, commercial and business categories have their own types (the error for an unknown type lists them). [one of: age_care_facilities, apartment, bare_land, beauty_and_health, boat_shed, carpark, commercial_land, contractor, cropping, dairy, dairy_and_superette, distribution, education_and_training, finishing, forestry, franchise, grazing, high_country, holiday_rental, home_and_income, horticulture, hospitality, hotel_motel_leisure, hotels_motels_lodges_bnb, house, industrial_buildings, industrial_land, industrial_premises, investment_opportunities, leisure_and_entertainment, lifestyle_property, lifestyle_section, manufacturing_and_processing, multiple_properties, office_building, office_premises, professional, restaurant_and_cafe, retail_food_and_beverages, retail_non_food, retail_premises, retail_property, retirement_living, section, services_and_professional, showroom, specialist_livestock, sporting, studio, tourism, townhouse, transport_and_automotive, unit, unspecified, viticulture, warehouse, wholesale_and_distribution]
- `sale_method` (array, optional) — How it is being sold, one or several: price_shown (any listing that shows a price), negotiation, auction, tender, poa, offers, deadline_sale, asking_price, enquiries_over … Not for residential rent. [one of: price_shown, negotiation, auction, tender, poa, offers, deadline_sale, asking_price, buyer_budget_from, buyer_budget_over, buyer_enquiry_over, buyer_interest_from, enquiries_over, expression_of_interest, negotiable_from, offers_over]
- `keyword` (string, optional) — A word the listing must contain (matched by the site's own keyword filter).
- `open_homes_only` (boolean, optional) — Only listings with an open home scheduled.
- `mortgagee_sale` (boolean, optional) — Only mortgagee sales.
- `new_construction` (boolean, optional) — Only new builds.
- `coastal_waterfront` (boolean, optional) — Only coastal / waterfront properties.
- `swimming_pool` (boolean, optional) — Only properties with a swimming pool.
- `pets_allowed` (boolean, optional) — Rentals only: pets allowed.
- `has_floor_plans` (boolean, optional) — Only listings with floor plans.
- `has_videos` (boolean, optional) — Only listings with a video.
- `has_3d_tour` (boolean, optional) — Only listings with a 3D walkthrough.
- `furnished` (array, optional) — Rentals only: furnished, unfurnished, partly_furnished (one or several). [one of: furnished, unfurnished, partly_furnished]
- `price_changed_recently` (boolean, optional) — Only listings whose price changed in the last 28 days (the site's "pricing changes" filter; for sale only).
- `agent_id` (integer, optional) — Only this agent's listings (every row returns agents[].agent_id).
- `agency_id` (integer, optional) — Only this agency office's listings (every row returns agency.agency_id).
- `sort` (enum, optional, default "featured") — Order of results. [one of: featured, best_match, latest, oldest, lowest_price, highest_price, smallest_land, largest_land]
- `page` (integer, optional, default 1) — Result page, 1-based. page x limit can reach 10,000 results.
- `limit` (integer, optional, default 20) — Listings per page, 1-100 (default 20).
- `max_rotations` (integer, optional, default 3) — Advanced: how many times to retry a difficult request (1-5).

**Returns:** results[]{listing_id, url (realestate.co.nz listing page), title, category, category_code, property_type, status (active|sold|withdrawn), address{full_address, display_address, street_number, street_number_suffix, unit_number, street, suburb, district, region, postcode, suburb_fq_slug, latitude, longitude, geo_accuracy, address_published}, price_display (the site's own wording: "$479,000", "Auction", "Deadline Sale", "Asking Price $698,000", "Enquiries Over $540,000", "$620 per week"), price (the figure in that wording, NZD; null when none is shown), price_to (second figure of a range), price_period (week|month|year|sqm for rents and leases), sale_method (fixed_price|negotiation|auction|tender|poa|offers|deadline_sale|asking_price|enquiries_over|…), price_code, currency, auction{date, time, location}, tender{…}, deadline{…}, bedrooms, bathrooms, ensuites, toilets, living_areas, studies, storeys, parking{garage, covered, other}, land_area, land_area_unit (sqm|ha), land_area_m2, floor_area, floor_area_unit, floor_area_m2, title_type (Freehold|Leasehold|Cross Lease|Unit Title|Company), image, images[], image_count, floorplans[], videos[], virtual_tours[], open_homes[]{start, end, is_past}, agents[]{agent_id, name, first_name, last_name, phone, mobile, email, image, agency_name, listing_count, profile_url}, agency{agency_id, name, trading_name, phone, email, website, logo, brand_colour, profile_url}, listed_at, created_at, listing_reference, property_id (→ `property`), is_featured, is_new_construction, is_mortgagee_sale, is_coastal_waterfront, has_swimming_pool, is_private_listing, rates, rates_period; rentals add available_from, pets_allowed, smokers_allowed, bond, max_tenants, furnished, apply_url, viewing_url; private listings add private_owner{name, email, details}}, count, total_results, page, limit, has_more, property_type_counts[]{property_type, count}, filters{} (what was sent, with resolved location ids)

**Example request body:**
```json
{
  "region": "Auckland",
  "limit": 10
}
```

### POST https://api.reefapi.com/realestate-nz/v1/listing — 2 credits
One realestate.co.nz listing in full, live or ended (sold / withdrawn listings still resolve): everything a search row has plus the description, price change history, features, in-zone and nearby schools, early-childhood centres, links, and every agent's phone, mobile and email with the agency. include_property=true also attaches the property record (sales history, council valuation, estimate).

**Parameters:**
- `listing_id` (string, required) — Listing id (the number in a realestate.co.nz listing URL) or the URL.
- `include_property` (boolean, optional, default false) — Also return the property record: REINZ sales history, council valuation, the site's estimate, past listings with their prices, latest rental.
- `max_rotations` (integer, optional, default 3) — Advanced: how many times to retry a difficult request (1-5).

**Returns:** listing{listing_id, url (realestate.co.nz listing page), title, category, category_code, property_type, status (active|sold|withdrawn), address{full_address, display_address, street_number, street_number_suffix, unit_number, street, suburb, district, region, postcode, suburb_fq_slug, latitude, longitude, geo_accuracy, address_published}, price_display (the site's own wording: "$479,000", "Auction", "Deadline Sale", "Asking Price $698,000", "Enquiries Over $540,000", "$620 per week"), price (the figure in that wording, NZD; null when none is shown), price_to (second figure of a range), price_period (week|month|year|sqm for rents and leases), sale_method (fixed_price|negotiation|auction|tender|poa|offers|deadline_sale|asking_price|enquiries_over|…), price_code, currency, auction{date, time, location}, tender{…}, deadline{…}, bedrooms, bathrooms, ensuites, toilets, living_areas, studies, storeys, parking{garage, covered, other}, land_area, land_area_unit (sqm|ha), land_area_m2, floor_area, floor_area_unit, floor_area_m2, title_type (Freehold|Leasehold|Cross Lease|Unit Title|Company), image, images[], image_count, floorplans[], videos[], virtual_tours[], open_homes[]{start, end, is_past}, agents[]{agent_id, name, first_name, last_name, phone, mobile, email, image, agency_name, listing_count, profile_url}, agency{agency_id, name, trading_name, phone, email, website, logo, brand_colour, profile_url}, listed_at, created_at, listing_reference, property_id (→ `property`), is_featured, is_new_construction, is_mortgagee_sale, is_coastal_waterfront, has_swimming_pool, is_private_listing, rates, rates_period; rentals add available_from, pets_allowed, smokers_allowed, bond, max_tenants, furnished, apply_url, viewing_url; private listings add private_owner{name, email, details}, description, price_history[]{from, to, changed_at}, features{garages, carports, pool, other}, schools[]{name, school_id, in_zone, has_zone, distance, latitude, longitude}, early_childhood[]{…}, broadband, additional_links[], call_to_action_links[], whiteware, furnishing_details, app_share_url}, property{…} (include_property)

**Example request body:**
```json
{
  "listing_id": "43166838"
}
```

### POST https://api.reefapi.com/realestate-nz/v1/property — 2 credits
A property's record on realestate.co.nz (the address, whether or not it is listed now): every REINZ sale with price, date, method and days to sell; council valuations (capital, land and improvements value) over time; the site's estimated value range with its confidence and monthly history; past and current listings with the agent's listing price; the latest rental listing (weekly rent); bedrooms, bathrooms, land and floor area, building age; nearby recent sales.

**Parameters:**
- `property_id` (string, required) — Property id (every listing returns property_id; sold rows too) or a realestate.co.nz/property/... URL.
- `max_rotations` (integer, optional, default 3) — Advanced: how many times to retry a difficult request (1-5).

**Returns:** property{property_id, url, address{…}, land_use_code, bedrooms, bathrooms, ensuites, toilets, parking{}, land_area, land_area_unit, land_area_m2, floor_area, floor_area_unit, floor_area_m2, building_age, has_swimming_pool, image, latest_sale{date, price, net_price, price_display, method, days_to_sell, is_settled, property_category, capital_value_at_sale, comments, sale_id}, council_valuation{capital_value, land_value, improvements_value, valuation_date, recorded_at}, estimate{low, mid, high, confidence (1-5), as_of, computed_at}, current_listings[], latest_rent_listing{listing_id, url, title, category, status, listing_price (weekly rent), listed_at, days_listed}, sold_within_last_year, sales_history[], council_valuation_history[], estimate_history[], listing_history[]{listing_id, url, title, category, status, listing_price, listed_at, days_listed, image}, latest_sale_listing, nearby_recent_sales[]{address, property_id, sale_date, sale_price, days_to_sell, bedrooms, bathrooms, floor_area_m2, land_area_m2}}

**Example request body:**
```json
{
  "property_id": "hf1bc20mc"
}
```

### POST https://api.reefapi.com/realestate-nz/v1/sold — 2 credits
Recently sold properties in a region, district or suburb, from the REINZ sale records the site publishes: sale price, sale date, sale method, days to sell, plus each property's council valuation, the site's estimate, bedrooms, bathrooms, land and floor area. Filter by sale date, sale price, bedrooms, bathrooms, land and floor area; sort by sale date, sale price or estimate.

**Parameters:**
- `region` (array, optional) — Region name or id (Auckland = 35, Wellington, Canterbury, Waikato, Bay of Plenty …). One or several. `locations` lists every region, district and suburb with ids.
- `district` (array, optional) — District name or id (Auckland City, North Shore City, Wellington City, Christchurch City …). One or several.
- `suburb` (array, optional) — Suburb name, id or fq_slug. One or several. A name used by several suburbs (e.g. Hillcrest) is chosen by the region/district you also give, otherwise the request lists the candidates. The narrowest level wins: region=Auckland + suburb=Ponsonby searches Ponsonby.
- `sold_after` (string, optional) — Earliest sale date, YYYY-MM-DD (default: one year ago).
- `sold_before` (string, optional) — Latest sale date, YYYY-MM-DD.
- `price_min` (number, optional) — Lowest sale price, NZD.
- `price_max` (number, optional) — Highest sale price, NZD.
- `bedrooms_min` (integer, optional) — Fewest bedrooms.
- `bedrooms_max` (integer, optional) — Most bedrooms.
- `bathrooms_min` (integer, optional) — Fewest bathrooms.
- `bathrooms_max` (integer, optional) — Most bathrooms.
- `land_area_min` (number, optional) — Smallest land area in square metres (1 ha = 10000).
- `land_area_max` (number, optional) — Largest land area in square metres.
- `floor_area_min` (number, optional) — Smallest floor area in square metres.
- `floor_area_max` (number, optional) — Largest floor area in square metres.
- `sort` (enum, optional, default "latest_sale") — Order of results. [one of: latest_sale, oldest_sale, highest_sold_price, lowest_sold_price, highest_estimate, lowest_estimate]
- `page` (integer, optional, default 1) — Result page, 1-based. page x limit can reach 10,000 results.
- `limit` (integer, optional, default 20) — Properties per page, 1-50 (default 20).
- `max_rotations` (integer, optional, default 3) — Advanced: how many times to retry a difficult request (1-5).

**Returns:** results[]{property_id, url, address{…}, land_use_code, bedrooms, bathrooms, parking{}, land_area, land_area_m2, floor_area, floor_area_m2, building_age, image, latest_sale{date, price, price_display, method, days_to_sell, is_settled, …}, council_valuation{capital_value, land_value, improvements_value, valuation_date}, estimate{low, mid, high, confidence, as_of}, current_listings[], latest_rent_listing{…}}, count, total_results (the site caps it at 10,000), page, limit, has_more, filters{}

**Example request body:**
```json
{
  "suburb": "Ahipara",
  "sold_after": "2025-01-01"
}
```

### POST https://api.reefapi.com/realestate-nz/v1/locations — 1 credit
realestate.co.nz's own region → district → suburb list with ids: find a place by name (query), list a region's districts or a district's suburbs, or every region. Use the ids or names in search and sold.

**Parameters:**
- `query` (string, optional) — Place name or part of it; returns matching regions, districts and suburbs.
- `region` (string, optional) — List this region's districts.
- `district` (string, optional) — List this district's suburbs.
- `limit` (integer, optional, default 50) — Most results for a query (1-500).
- `max_rotations` (integer, optional, default 3) — Advanced: how many times to retry a difficult request (1-5).

**Returns:** results[]{type (region|district|suburb), id, name, slug, fq_slug, district_id, district, region_id, region}, count, total_matches

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

### POST https://api.reefapi.com/realestate-nz/v1/agent — 1 credit
A real-estate agent's profile on realestate.co.nz: name, phone, mobile, email, photo, agency, licence class, how many listings they have now / recently / in total, by category and suburb, and the suburbs they work. Their listings: search with agent_id.

**Parameters:**
- `agent_id` (string, required) — Agent id (search and listing rows return agents[].agent_id) or the realestate.co.nz/agent/... URL.
- `max_rotations` (integer, optional, default 3) — Advanced: how many times to retry a difficult request (1-5).

**Returns:** agent{agent_id, name, first_name, last_name, phone, mobile, email, image, profile_url, status, is_live, licence_class, agent_number, agency{agency_id, name, …}, agency_ids[], listing_count, recent_listing_count, all_time_listing_count, listings_by_category{}, active_listings[]{suburb, category, sub_type, count}, suburbs[], is_featured, updated_at, salesforce_id, salesforce_contact_id}

**Example request body:**
```json
{
  "agent_id": "1861787"
}
```

### POST https://api.reefapi.com/realestate-nz/v1/agency — 2 credits
A real-estate agency office on realestate.co.nz: name, trading name, phone, email, website, street and postal address, logo, listing counts by category, the suburbs it works, and every agent with phone, mobile and email. Its listings: search with agency_id.

**Parameters:**
- `agency_id` (string, required) — Agency office id (rows return agency.agency_id) or the realestate.co.nz/office/... URL.
- `max_rotations` (integer, optional, default 3) — Advanced: how many times to retry a difficult request (1-5).

**Returns:** agency{agency_id, name, trading_name, phone, email, enquiry_email, website, logo, brand_colour, profile_url, physical_address{}, postal_address{}, listing_count, recent_listing_count, all_time_listing_count, listings_by_category{}, categories[], suburbs[], is_property_manager, is_business_broker, subscription_type, updated_at, agents[]{agent_id, name, phone, mobile, email, image, listing_count, profile_url}, agent_count}

**Example request body:**
```json
{
  "agency_id": "267139"
}
```

## 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=realestate-nz
- Human docs page: https://reefapi.com/docs/realestate-nz
- Overview page: https://reefapi.com/realestate-nz-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt