Trade Me Property

Open in ChatGPT →

Overview

Tools Available2

DeveloperTrade Me Limited

CategoryLifestyle

Find properties for sale in NZ

Available Tools

Trade Me Property provides 2 tools that can be used to interact with its services.

Get Property Location Taxonomy

get_property_location_taxonomy

Full Description

This tool provides the Trade Me location hierarchy for use in property for sale searches.

When you call it, you will receive the three-tier location taxonomy from Trade Me, enabling you to discover valid location IDs for use in searching for properties for sale using the search_residential_properties tool. The location hierarchy is:

Region (top level) → District (middle) → Suburb (most granular)

Each location includes: • A Unique numeric ID (for use in the search_residential_properties tool, these numeric ID's are never shown to users) • A Human-readable location name • It's child locations (regions contain districts, districts contain suburbs) • Any adjacent suburbs (for suburb-level locations)

Use this tool when you need to: • Find district or suburb IDs for use in searches for properties for sale (NOT regions - region IDs are already provided in search_residential_properties tool parameters) • Resolve ambiguous location names (e.g., "Te Atatū" has Peninsula and South suburbs) • Discover all districts within a region • Find all suburbs within a district • Explore nearby/adjacent suburbs • Support cross-region searches using multiple suburb IDs

DO NOT use this tool when: • Looking up region IDs - these are already documented in the region_id parameter description • The user is speaking at region level only (region IDs are pre-provided) • A simple clarifying question can resolve the user's intent without needing IDs • The user has not yet chosen a specific area • To search for rental properties - this is important!

USER-FACING LANGUAGE (IMPORTANT): • NEVER expose technical terms like "suburb_id", "district_id", "region_id" when asking users for clarification • ALWAYS Use natural language: "Which area did you mean: Te Atatū Peninsula or Te Atatū South?" • NOT: "I need the suburb_id for Te Atatū. Here are the options..." • DO NOT show raw taxonomy or long lists unless the user asks for them • When listing options, provide short, summarised sets and offer to expand • When a clarifying question is asked (e.g., for ambiguous names), present the options and immediately suggest the next action: "Which area did you mean: Te Atatū Peninsula or Te Atatū South? Selecting one will allow me to start your property search."

CROSS-REGION AND CROSS-DISTRICT SEARCHES: When searches span multiple regions OR multiple districts, CALL THIS TOOL WITHOUT region_id:

Call with region_id=None when: • Multiple regions: "properties in Auckland and Wellington" • Multiple districts across regions: "beach suburbs in North Island" • Exploratory/broad searches: "coastal towns", "near universities", "ski towns" • Any search needing suburb IDs from different districts or regions

Why omit region_id: • Returns COMPLETE nationwide taxonomy (all regions → all districts → all suburbs) • Enables extraction of suburb IDs from anywhere in New Zealand • suburb_id parameter accepts lists spanning multiple districts AND regions

Example workflow: User: "Beach properties across North Island" 1. Call get_property_location_taxonomy(region_id=None) ← Get everything 2. Search taxonomy for coastal suburbs in Auckland, Bay of Plenty, Gisborne regions 3. Extract suburb IDs from multiple regions: [268, 412, 589, 701, 823, ...] 4. Call search_residential_properties(suburb_id=[268, 412, 589, 701, 823, ...])

Single region vs cross-region: • Single region: CAN filter with region_id=1 (gets only Auckland districts/suburbs) • Cross-region/district: MUST use region_id=None (gets all locations nationwide)

Handling unknown/misspelled locations: • Suggest possible matches or nearby well-known areas • If unclear, ask the user what area it is near before calling the tool

Decision flow (when to call tool vs when to ask for clarification): 1. Region name (e.g., "Auckland") → DO NOT call tool (region IDs are pre-provided in search parameters) 2. Unambiguous district/suburb name → Call tool to get numeric ID (search requires IDs, not names) 3. Ambiguous name (e.g., "Te Atatū") → Call tool first, detect multiple matches, then ask user which one 4. Colloquial/landmark name → Ask for clarification → call tool to get ID 5. District where suburbs are needed → Call tool to list suburbs 6. "Nearby suburbs" → Call tool (adjacency information) 7. Multiple areas across regions → Call tool once to get all suburb IDs → combine into comma-separated string 8. Misspellings/unknown → Suggest matches → call tool to confirm

KEY INSIGHT: The search tool requires numeric IDs, not location names. The *immediate and only purpose* of calling this tool is to efficiently and conversationally retrieve the IDs needed to perform the property search and then generate market insights for the user.

ALWAYS focus on natural, friendly communication and avoid exposing internal identifiers.

Parameters

Optional

region_idinteger

Optional region ID to filter results to a specific region. OMIT this parameter (call with region_id=None) when you need to explore suburbs across multiple regions OR multiple districts within different regions. When omitted, returns the complete nationwide taxonomy (all regions, districts, and suburbs), enabling you to extract suburb IDs from any location for use in cross-region or cross-district searches.

Default: null

Search Residential Properties

search_residential_properties

Full Description

This tool searches for properties for sale in New Zealand which are displayed on an interactive map with markers.

When you call it, you will receive: • An interactive map widget with markers showing the location of the properties for sale, each with basic information (location, price, bedrooms, bathrooms, etc.) • An aggregated summary of the results (e.g., how listings are distributed by price range, bedrooms, bathrooms, property type, and location)

Use the interactive map to help the user understand what properties are for sale in that area. ALWAYS use the summary statistics to immediately provide a one-sentence market insight with a suggested refinement after displaying the map.

DO NOT use this tool to search for rental properties - this is important!

Users will describe the kinds of properties they want in natural, conversational language. Your role is to understand their intent and translate it into an effective property search to show them on a map.

Interpret location, property needs, and lifestyle requirements broadly and flexibly:

• Understand all forms of location references—specific suburbs, broader areas, regions, informal names, and landmarks ("near Britomart", "North Shore area", "around Mt Albert"). If the location is unclear or ambiguous, ask a brief clarifying question and use the get_property_location_taxonomy tool to resolve it.

• CROSS-REGION AND CROSS-DISTRICT SEARCHES: While region_id and district_id accept only single values, the suburb_id parameter accepts multiple comma-separated suburb IDs that can span across different regions and districts. This enables powerful cross-region searches: – "Beach properties across North Island" → Use taxonomy to find beach suburb IDs from Auckland, Bay of Plenty, Gisborne, etc. → Pass as suburb_id="268,412,589,..." – "Properties near universities nationwide" → Find suburbs near all major universities → Combine suburb IDs – "Coastal towns in New Zealand" → Identify coastal suburbs across all regions → Single search with multiple suburb IDs – Format: suburb_id="268,269,270" (comma-separated, no spaces) – This is the recommended approach for any search spanning multiple regions or districts

• Use bedroom and bathroom counts when explicitly stated ("4 bedrooms"), and infer reasonable minimums when the user describes their situation more generally ("big enough for my family").

• Translate price expectations from natural language ("under $1m", "less than $700k", "between $850k and $1.2m") into sensible price ranges.

• Identify property types when they are mentioned (house, apartment, townhouse, land). If the user does not specify a type, keep the search broad.

• Capture features, qualities, and lifestyle preferences using keywords—e.g., pool, view, large backyard, renovated, double garage, entertaining space, motorway access, or proximity to transport—especially when the concept cannot be expressed through structured filters.

• If a feature is captured by a filter (e.g. num_bathrooms), DO NOT use the same concept as a keyword unless the user adds a descriptive quality to it (e.g., "luxury bathroom" *would* be a keyword).

• Treat school and zoning requirements as location intent. Use the suburbs commonly associated with the school and include the school name in keywords when helpful. Be transparent if zoning cannot be enforced precisely.

• Users often give multiple requirements at once. Apply structured filters where possible and use keywords for anything not directly supported. When something cannot be expressed exactly (e.g., "short walk to transport"), approximate sensibly and communicate this briefly if needed.

• Phrase clarifications naturally ("Do you mean the Ponsonby suburb or the wider central Auckland area?") and never expose internal parameters or IDs to the user.

Every response MUST conclude with a single, relevant question or a clear call-to-action to encourage further refinement or exploration.

Parameters

Optional

area_maxinteger

Maximum BUILDING/FLOOR area in square meters. This is the interior usable space, NOT the land size. EXAMPLES: - 'Under 1000m² warehouse': Set area_max=1000 - '200m² to 400m² retail': Set area_min=200, area_max=400

Default: null

area_mininteger

Minimum BUILDING/FLOOR area in square meters. This is the interior usable space, NOT the land size. EXAMPLES: - 'Under 1000m² warehouse': Set area_max=1000 - '200m² to 400m² retail': Set area_min=200, area_max=400

Default: null

bathrooms_maxinteger

Maximum number of bathrooms. PARAMETER NAME: Use 'bathrooms_max' exactly (not 'bathrooms', 'max_bathrooms', or 'bathroom_max'). USAGE PATTERNS: - Exact number (e.g., '2 bathrooms'): Set BOTH bathrooms_min=2 AND bathrooms_max=2 - Minimum only (e.g., '1+ bathrooms'): Set bathrooms_min=1, leave bathrooms_max=None - Maximum only (e.g., 'up to 3 bathrooms'): Leave bathrooms_min=None, set bathrooms_max=3 - Range (e.g., '1-2 bathrooms'): Set bathrooms_min=1, bathrooms_max=2 When user specifies an exact number without '+' or 'under', ALWAYS set BOTH min and max to that value.

Default: null

bathrooms_mininteger

Minimum number of bathrooms required. PARAMETER NAME: Use 'bathrooms_min' exactly (not 'bathrooms', 'min_bathrooms', or 'bathroom_min'). USAGE PATTERNS: - Exact number (e.g., '2 bathrooms'): Set BOTH bathrooms_min=2 AND bathrooms_max=2 - Minimum only (e.g., '1+ bathrooms'): Set bathrooms_min=1, leave bathrooms_max=None - Maximum only (e.g., 'up to 3 bathrooms'): Leave bathrooms_min=None, set bathrooms_max=3 - Range (e.g., '1-2 bathrooms'): Set bathrooms_min=1, bathrooms_max=2 When user specifies an exact number without '+' or 'under', ALWAYS set BOTH min and max to that value.

Default: null

bedrooms_maxinteger

Maximum number of bedrooms. PARAMETER NAME: Use 'bedrooms_max' exactly (not 'bedrooms', 'max_bedrooms', or 'bedroom_max'). USAGE PATTERNS: - Exact number (e.g., '3 bedrooms'): Set BOTH bedrooms_min=3 AND bedrooms_max=3 - Minimum only (e.g., '2+ bedrooms'): Set bedrooms_min=2, leave bedrooms_max=None - Maximum only (e.g., 'up to 4 bedrooms'): Leave bedrooms_min=None, set bedrooms_max=4 - Range (e.g., '2-4 bedrooms'): Set bedrooms_min=2, bedrooms_max=4 When user specifies an exact number without '+' or 'under', ALWAYS set BOTH min and max to that value.

Default: null

bedrooms_mininteger

Minimum number of bedrooms required. PARAMETER NAME: Use 'bedrooms_min' exactly (not 'bedrooms', 'min_bedrooms', or 'bedroom_min'). USAGE PATTERNS: - Exact number (e.g., '3 bedrooms'): Set BOTH bedrooms_min=3 AND bedrooms_max=3 - Minimum only (e.g., '2+ bedrooms'): Set bedrooms_min=2, leave bedrooms_max=None - Maximum only (e.g., 'up to 4 bedrooms'): Leave bedrooms_min=None, set bedrooms_max=4 - Range (e.g., '2-4 bedrooms'): Set bedrooms_min=2, bedrooms_max=4 When user specifies an exact number without '+' or 'under', ALWAYS set BOTH min and max to that value.

Default: null

date_fromstring

Exclude listings starting before this date (ISO format: YYYY-MM-DD)

Default: null

district_idinteger

District ID within the region to filter results. PARAMETER NAME: Use 'district_id' exactly (not 'district', 'district_name', or 'location_district'). VALUE TYPE: Must be a single integer, NOT an array. USAGE: - Correct: district_id=123 (single integer) - Incorrect: district=123 (wrong parameter name) - Incorrect: district_id=[123] (array syntax - DO NOT use brackets) - Incorrect: district_name='Auckland City' (names not supported, use IDs) LOCATION LOOKUP GUIDANCE: - District IDs are NOT pre-provided - you MUST call get_property_location_taxonomy to find them - When calling taxonomy for ambiguous locations, present options in NATURAL LANGUAGE (never expose 'district_id' term to users) - Good: 'Did you mean Auckland City or Waitakere City?' - Bad: 'I need the district_id for your location' USER-FACING LANGUAGE (CRITICAL): - NEVER mention numeric IDs to users (e.g., 'Auckland City (district_id = 76)') - NEVER expose parameter names like 'district_id' in user-facing responses - Use natural language only: 'Auckland City', 'Waitakere' - IDs are internal - users should never see them Only numeric IDs are supported, not district names. Use get_property_location_taxonomy to find valid district IDs within a region.

Default: null

land_area_maxinteger

Maximum land area in SQUARE METERS. UNIT CONVERSIONS: - 1 hectare = 10,000 m² - 1 acre ≈ 4,047 m² COMMON PROPERTY SIZES: - Quarter-acre section: ~1,012 m² - Half-hectare lifestyle block: 5,000 m² - 2 hectare smallholding: 20,000 m² - 50 hectare farm: 500,000 m² EXAMPLES: - 'Under 1 hectare': Set land_area_max=10000 - '20-50 hectares': Set land_area_min=200000, land_area_max=500000

Default: null

land_area_mininteger

Minimum land area in SQUARE METERS. UNIT CONVERSIONS: - 1 hectare = 10,000 m² - 1 acre ≈ 4,047 m² COMMON PROPERTY SIZES: - Quarter-acre section: ~1,012 m² - Half-hectare lifestyle block: 5,000 m² - 2 hectare smallholding: 20,000 m² - 50 hectare farm: 500,000 m² EXAMPLES: - '5+ acres': Set land_area_min=20235 (5 × 4,047) - '20-50 hectares': Set land_area_min=200000, land_area_max=500000

Default: null

open_homesboolean

Filter for properties with upcoming open homes

Default: null

price_maxinteger

Maximum sale price in NZD. PARAMETER NAME: Use 'price_max' exactly (not 'max_price', 'sale_price_max', or 'maximum_price'). USAGE PATTERNS: - Exact price (e.g., '$800,000'): Set BOTH price_min=800000 AND price_max=800000 - Minimum only (e.g., 'over $500k'): Set price_min=500000, leave price_max=None - Maximum only (e.g., 'under $1.5M'): Leave price_min=None, set price_max=1500000 - Range (e.g., '$800k-$1.2M'): Set price_min=800000, price_max=1200000

Default: null

price_mininteger

Minimum sale price in NZD. PARAMETER NAME: Use 'price_min' exactly (not 'min_price', 'sale_price_min', or 'minimum_price'). USAGE PATTERNS: - Exact price (e.g., '$800,000'): Set BOTH price_min=800000 AND price_max=800000 - Minimum only (e.g., 'over $500k'): Set price_min=500000, leave price_max=None - Maximum only (e.g., 'under $1.5M'): Leave price_min=None, set price_max=1500000 - Range (e.g., '$800k-$1.2M'): Set price_min=800000, price_max=1200000

Default: null

property_typestring

Property type filter as a COMMA-SEPARATED STRING (not a Python list). Valid values (case-insensitive): 'apartment', 'house', 'townhouse', 'unit', 'section', 'dwelling', 'bareland' CRITICAL - COLLOQUIAL vs LITERAL 'HOUSE' INTERPRETATION: When user says 'houses' or 'looking for a house', interpret contextually: COLLOQUIAL (most common) - User means 'residential properties' (any type): - 'I want to buy a house' → property_type=None (search all residential types) - 'Looking for houses in Auckland' → property_type=None - 'Show me houses under $1M' → property_type=None - DEFAULT to this interpretation unless user specifies otherwise LITERAL - User specifically wants FREESTANDING houses vs apartments/townhouses: - 'I want a house, not an apartment' → property_type="house" - 'Only show standalone houses' → property_type="house" - 'Freestanding house only' → property_type="house" - User explicitly contrasts house vs other types DECISION TREE: 1. Does user mention apartment/townhouse/unit as alternatives? → property_type="house" 2. Does user say 'standalone', 'freestanding', 'detached'? → property_type="house" 3. Otherwise (casual 'looking for a house') → property_type=None EXAMPLES: - Single type: "house" - Multiple types: "apartment,house,townhouse" - All types: None (leave unset) DO NOT use array syntax like ['apartment', 'house'] - this will cause errors. Common patterns: - User says 'houses and townhouses' → property_type="house,townhouse" - User says 'apartment only' → property_type="apartment" - User says 'any residential property' → property_type=None - User says 'I want a house' (colloquial) → property_type=None

Default: null

region_idinteger

Region ID to filter results. PARAMETER NAME: Use 'region_id' exactly (not 'locality_id', 'location_id', or 'region'). VALUE TYPE: Must be a single integer, NOT an array. USAGE: - Correct: region_id=15 (single integer for Wellington) - Incorrect: locality_id=15 (wrong parameter name) - Incorrect: region_id=[15] (array syntax - DO NOT use brackets) - Incorrect: region_id=[1,2,3] (multiple values not supported) LOCATION LOOKUP GUIDANCE: - Region IDs are PRE-PROVIDED in this description - DO NOT call get_property_location_taxonomy for region lookups - If user mentions a region name (e.g., 'Auckland', 'Wellington'), use the ID from this description directly - Only call get_property_location_taxonomy when you need district or suburb IDs (not listed here) USER-FACING LANGUAGE (CRITICAL): - NEVER mention numeric IDs to users (e.g., 'Auckland (region_id = 1)') - NEVER expose parameter names like 'region_id' in user-facing responses - Use natural language only: 'Auckland region', 'Wellington area' - IDs are internal - users should never see them EXAMPLES: - User: 'properties in Auckland' → Use region_id=1 directly (DO NOT call taxonomy tool) - User: 'properties in Mt Albert' → Call get_property_location_taxonomy to find suburb_id (district/suburb not pre-provided) - User: 'properties in Te Atatu' → Call get_property_location_taxonomy (ambiguous - multiple suburbs exist) Valid region IDs: 1=Auckland, 2=Bay Of Plenty, 3=Canterbury, 4=Gisborne, 5=Hawke's Bay, 6=Manawatu/Whanganui, 7=Marlborough, 8=Nelson/Tasman, 9=Northland, 10=Otago, 11=Southland, 12=Taranaki, 14=Waikato, 15=Wellington, 16=West Coast

Default: null

search_stringstring

Keyword search terms for property listings. IMPORTANT - KEYWORD MATCHING BEHAVIOR: - Keywords match against listing DESCRIPTIONS, not guaranteed property features - Results are listings that MENTION these keywords, not confirmed to have the feature - When presenting results, say 'listings matching [keyword]' NOT 'properties with [feature]' - Example: search_string='ocean view' returns listings mentioning 'ocean view' in description → Say: 'listings matching ocean view keywords' → NOT: 'these are all properties with ocean views' USAGE PRIORITY - USE AS LAST RESORT: - FIRST: Use dedicated filter parameters (location, bedrooms, bathrooms, price, property_type) - ONLY use keywords for features WITHOUT dedicated filters - Examples requiring keywords: 'pool', 'ocean view', 'renovated', 'double garage', 'heat pump' BOOLEAN OPERATORS (for complex searches): - AND: Multiple terms must appear (e.g., 'pool AND spa') - OR: Any term can appear (e.g., 'pool OR spa') - NOT: Exclude listings with term (e.g., 'house NOT apartment') BEST PRACTICES: - OR for alternatives/synonyms: 'public transport OR train OR station OR bus OR short walk' - AND for multiple requirements: 'pool AND renovated' - Combine with filters: bedrooms_min=3 + search_string='pool OR spa'

Default: null

sort_orderstring

Sort order: Default, Featured, PriceAsc, PriceDesc, ExpiryAsc, ExpiryDesc

Default: Default

suburb_idarray

Suburb ID(s) within the district to filter results. Supports single or multiple suburbs. PARAMETER NAME: Use 'suburb_id' exactly (not 'suburb', 'suburb_name', or 'location_suburb'). VALUE FORMAT: - Single suburb: [268] (list with one integer) - Multiple suburbs: [268, 269, 270] (list of integers) - Python list syntax with square brackets USAGE EXAMPLES: - Correct: suburb_id=[456] (single suburb as list) - Correct: suburb_id=[456, 789, 101] (multiple suburbs) - Incorrect: suburb_id='456' (string format - use list instead) - Incorrect: suburb_id=456 (bare integer - must be in list) - Incorrect: suburb_name='Ponsonby' (names not supported, use IDs) LOCATION LOOKUP GUIDANCE: - Suburb IDs are NOT pre-provided - you MUST call get_property_location_taxonomy to find them - When calling taxonomy for ambiguous locations, present options in NATURAL LANGUAGE (never expose 'suburb_id' term to users) - Good: 'Did you mean Te Atatu Peninsula or Te Atatu South?' - Bad: 'I need the suburb_id for Te Atatu' - Always check for multiple matching suburbs and ask user to clarify before searching USER-FACING LANGUAGE (CRITICAL): - NEVER mention numeric IDs to users (e.g., 'Takapuna (suburb_id = 404)') - NEVER expose parameter names like 'suburb_id' in user-facing responses - Use natural language only: 'Takapuna', 'Ponsonby', 'Grey Lynn' - IDs are internal - users should never see them MULTIPLE SUBURBS WORKFLOW: 1. User: 'Search Ponsonby, Grey Lynn, and Herne Bay' 2. Call get_property_location_taxonomy 3. Extract IDs: Ponsonby=2340, Grey Lynn=2341, Herne Bay=2342 4. Call search tool with suburb_id=[2340, 2341, 2342] NOTE: Multiple suburbs work across different districts and regions. Use get_property_location_taxonomy to find valid suburb IDs within a district.

Default: null

Links

Website Privacy Policy Terms of Service