# OneRoof API scraper (New Zealand) - homes for sale and for rent, recent sales, property value estimates with sale and valuation history, and suburb median price, median rent and rental yield. Prices in NZD. No account, no browser.

> New Zealand homes on OneRoof for sale, for rent or recently sold, by region, district or suburb(s): listing URL, address, coordinates, price or how it is being sold (asking price, negotiation, auction, tender, deadline sale, enquiries over) or weekly rent, bedrooms, bathrooms, parking, floor and land area, property type, photos, the listing agents with phone numbers and the agency, open homes, the site's value estimate and the council rating valuation. Sold returns sale price, date and method. Filter by property type, bedrooms, bathrooms, price and keyword; sort by newest or price.
> ReefAPI engine `oneroof` · 5 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/oneroof/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/oneroof/v1/search — 2 credits
New Zealand homes on OneRoof for sale, for rent or recently sold, by region, district or suburb(s): listing URL, address, coordinates, price or how it is being sold (asking price, negotiation, auction, tender, deadline sale, enquiries over) or weekly rent, bedrooms, bathrooms, parking, floor and land area, property type, photos, the listing agents with phone numbers and the agency, open homes, the site's value estimate and the council rating valuation. Sold returns sale price, date and method. Filter by property type, bedrooms, bathrooms, price and keyword; sort by newest or price.

**Parameters:**
- `purpose` (enum, optional, default "sale") — For sale (default), for rent, or recently sold. [one of: sale, rent, sold]
- `region` (enum, optional) — Region. district_id / suburb_id / location narrow it further. [one of: northland, auckland, waikato, bay_of_plenty, gisborne, hawkes_bay, taranaki, wellington, nelson_bays, west_coast, canterbury, otago, southland, coromandel, central_otago_lakes, marlborough, wairarapa, pacific_islands, central_north_island, manawatu_whanganui]
- `district_id` (array, optional) — One or more OneRoof district ids (225 = Auckland City). `suggest` returns them.
- `suburb_id` (array, optional) — One or more OneRoof suburb ids (3236 = Ponsonby). `suggest` returns them.
- `location` (string, optional) — A region, district or suburb by name; resolved to the site's own id (first match, returned in resolved_location). Use suburb_id for several suburbs.
- `include_surrounding_suburbs` (boolean, optional, default false) — Also return listings in the suburbs around the chosen suburb(s), as the site does.
- `property_type` (array, optional) — One or more property types. home_and_income, lifestyle_section and section exist for sale/sold only; holiday_rental for rent only. [one of: house, apartment, studio, townhouse, unit, home_and_income, lifestyle_property, lifestyle_section, section, holiday_rental]
- `bedrooms_min` (integer, optional) — Fewest bedrooms (5 = 5 or more).
- `bedrooms_max` (integer, optional) — Most bedrooms (5 = no upper limit).
- `bathrooms_min` (integer, optional) — Fewest bathrooms (5 = 5 or more).
- `bathrooms_max` (integer, optional) — Most bathrooms.
- `price_min` (number, optional) — Lowest price, NZD (rent: per week; sold: sale price). Listings without a shown price are matched on the price the agent gave the site.
- `price_max` (number, optional) — Highest price, NZD (rent: per week; sold: sale price).
- `keyword` (string, optional) — Words in the listing (title and description), as the site's keyword box.
- `sort` (enum, optional, default "featured") — Order of results. [one of: featured, newest, price_desc, price_asc, earliest_open_home]
- `page` (integer, optional, default 1)
- `limit` (integer, optional, default 20) — Rows per page (1-50).
- `max_rotations` (integer, optional, default 3) — How many fresh exits to try before giving up.

**Returns:** purpose, results[]{listing_id, url, title, address, street, address_withheld, suburb, district, region, suburb_id, district_id, region_id, latitude, longitude, price (NZD number parsed from the site's text; null when none), price_qualifier (asking|from|per_week), price_display (the site's own words), currency, sale_method (asking_price|negotiation|auction|tender|deadline_sale|set_date_of_sale|enquiries_over|offers_over|buyer_enquiry_over|buyers_from|negotiable_from|price_on_application|offers|for_sale|other), sale_method_code, sale_date_display, auction_at, listing_type, property_type, bedrooms, bathrooms, parking, floor_area_m2, land_area_m2, image, images[], floor_plan_images[], agents[]{agent_id, name, phone, photo}, agency{agency_id, name, logo}, open_homes[]{start, end}, listed_date, is_new_listing, is_new_build, estimate{value, low, high, confidence, confidence_label, rateable_value, estimate_vs_rateable_value, suburb_median_sale_price_12m, suburb_average_rateable_value, suburb_sale_vs_rateable_value_percent, currency}, rateable_value, rateable_value_date, decade_built, available_date, has_video} (purpose=sold: results[]{sale_id, property_id (for `property`), url, address, street, address_withheld, suburb, district, region, suburb_id, district_id, region_id, latitude, longitude, sold_price (null when withheld), sold_date, sold_date_is_future (the agent-entered date is after today), sale_method, sale_method_display, currency, price_verified_by, property_type, bedrooms, bathrooms, parking, image, agents[], agency}), count, total_results, page, limit, has_more, resolved_location{id, level, name, label}, filters{}

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

### POST https://api.reefapi.com/oneroof/v1/listing — 2 credits
One OneRoof listing in full, for sale or for rent: everything in a search row plus the description, every photo and floor plan, the listing agents with phone, email and job title, the agency's phone, email and address, open homes, bond for rentals, the council valuation (land, improvements, capital value and date), title type, legal description, zoning and construction, the property's sale, listing and valuation history, and the suburb's median sale price, median rent and yield.

**Parameters:**
- `listing_id` (string, required) — Listing id from search, or the listing URL on oneroof.co.nz.
- `max_rotations` (integer, optional, default 3) — How many fresh exits to try before giving up.

**Returns:** listing{listing_id, url, title, address, street, address_withheld, suburb, district, region, suburb_id, district_id, region_id, latitude, longitude, price (NZD number parsed from the site's text; null when none), price_qualifier (asking|from|per_week), price_display (the site's own words), currency, sale_method (asking_price|negotiation|auction|tender|deadline_sale|set_date_of_sale|enquiries_over|offers_over|buyer_enquiry_over|buyers_from|negotiable_from|price_on_application|offers|for_sale|other), sale_method_code, sale_date_display, auction_at, listing_type, property_type, bedrooms, bathrooms, parking, floor_area_m2, land_area_m2, image, images[], floor_plan_images[], agents[]{agent_id, name, phone, photo}, agency{agency_id, name, logo}, open_homes[]{start, end}, listed_date, is_new_listing, is_new_build, estimate{value, low, high, confidence, confidence_label, rateable_value, estimate_vs_rateable_value, suburb_median_sale_price_12m, suburb_average_rateable_value, suburb_sale_vs_rateable_value_percent, currency}, rateable_value, rateable_value_date, decade_built, available_date, has_video, description, agents[]{agent_id, name, phone, email, job_title, photo, profile_url, sold_count, recent_sold_count}, agency{agency_id, name, branch, phone, email, address, website, logo}, property_id, property_url, bond, council_valuation{land_value, improvements_value, capital_value, valuation_date, previous_valuation_date, land_value_change_percent, improvements_value_change_percent, capital_value_change_percent, currency}, property_records[]{key, label, value}, history[]{event (listed|valuation|sold|built|building_consent), date, label, value, detail, sale_type}, suburb_market{median_sale_price, median_rent_per_week, rental_yield_percent, capital_growth_percent, currency}, updated_at, listing_code}

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

### POST https://api.reefapi.com/oneroof/v1/property — 2 credits
Any New Zealand property on OneRoof, listed or not, by property id, address or URL: the site's value estimate with low-high range and confidence, the council valuation (land, improvements, capital value and date, change since the last valuation), the last sale price and date, the full sale, listing, valuation and building-consent history, bedrooms, bathrooms, floor and land area, title, zoning and construction records, the current listing if it is on the market, and the suburb's median sale price, median weekly rent, rental yield and capital growth.

**Parameters:**
- `property_id` (string, optional) — Property id (from suggest, sold search rows or a listing).
- `address` (string, optional) — A street address; the best match is used and returned in matched_address.
- `url` (string, optional) — A oneroof.co.nz property or listing URL.
- `max_rotations` (integer, optional, default 3) — How many fresh exits to try before giving up.

**Returns:** property{property_id, url, address, street, suburb, district, region, suburb_id, district_id, region_id, latitude, longitude, property_category, bedrooms, bathrooms, parking, floor_area_m2, land_area_m2, estimate{value, low, high, confidence, confidence_label, rateable_value, …}, council_valuation{…}, last_sale{price, date, sale_type, source}, history[]{…}, property_records[]{key, label, value}, current_listing{listing_id, url, listing_type, price, price_qualifier, price_display, sale_method, listed_date}, suburb_market{…}, image, images[]}, matched_address, other_matches[]

**Example request body:**
```json
{
  "url": "https://www.oneroof.co.nz/property/auckland/freemans-bay/36-spring-street/l7moE"
}
```

### POST https://api.reefapi.com/oneroof/v1/suburb — 1 credit
A New Zealand suburb's property market on OneRoof: median sale price, median weekly rent, rental yield and capital growth, with the census median age, median income, years in home and home ownership split. By suburb id or name.

**Parameters:**
- `suburb_id` (integer, optional) — OneRoof suburb id (from suggest or search rows).
- `name` (string, optional) — Suburb name; the first suburb match is used.
- `max_rotations` (integer, optional, default 3) — How many fresh exits to try before giving up.

**Returns:** suburb{suburb_id, name, label, district, district_id, region, region_id, url, latitude, longitude, market{median_sale_price, median_rent_per_week, rental_yield_percent, capital_growth_percent, currency}, description, demographics{median_age, median_income, average_years_in_home, ownership[]{category, percent}, age[]{category, percent}}}

**Example request body:**
```json
{
  "suburb_id": 3236
}
```

### POST https://api.reefapi.com/oneroof/v1/suggest — 1 credit
OneRoof's own location and address lookup: regions, districts and suburbs with their ids and live listing counts (for search), streets, and matching properties with property and listing ids (for property and listing).

**Parameters:**
- `query` (string, required) — Start of a place name or an address.
- `purpose` (enum, optional, default "sale") — Which listing counts and properties to match. [one of: sale, rent, sold, estimate]
- `max_rotations` (integer, optional, default 3) — How many fresh exits to try before giving up.

**Returns:** query, locations[]{id, level (region|district|suburb), name, label, listing_count, latitude, longitude}, surrounding_suburbs[], streets[]{street_id, label, latitude, longitude}, properties[]{property_id, listing_id, address, url, latitude, longitude}, count

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

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