# trademe-smart-search

> AI-powered TradeMe marketplace search. Fetches listings via API, then uses Claude to analyze descriptions and images to find the best matches for nuanced requirements like "good condition", "stylish", "looks safe for a beginner". Use when someone wants to find items on TradeMe with smarter filtering than keywords - e.g., "find a solid second-hand bike for my 9 year old near Mt Eden, good condition, pink if possible". Triggers: TradeMe, Trade Me, marketplace search, find listings, buy second-hand, NZ marketplace.

- Author: ezhang-quashed
- Repository: edmondzhang82/skill-trademe-search
- Version: 20260124223930
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/edmondzhang82/skill-trademe-search
- Web: https://mule.run/skillshub/@@edmondzhang82/skill-trademe-search~trademe-smart-search:20260124223930

---

---
name: trademe-smart-search
description: |
  AI-powered TradeMe marketplace search. Fetches listings via API, then uses Claude to analyze descriptions and images to find the best matches for nuanced requirements like "good condition", "stylish", "looks safe for a beginner". Use when someone wants to find items on TradeMe with smarter filtering than keywords - e.g., "find a solid second-hand bike for my 9 year old near Mt Eden, good condition, pink if possible". Triggers: TradeMe, Trade Me, marketplace search, find listings, buy second-hand, NZ marketplace.
---

# TradeMe Smart Search

Fetch TradeMe listings via API, then use AI to analyze text and images for intelligent matching.

## Workflow

### 1. Gather Requirements

Ask user for:
- **What** they want (item, size/age if relevant)
- **Location** (suburb for pickup distance)
- **Budget** (price range, flexibility)
- **Preferences** (colour, style, condition)
- **Deal-breakers** (must-haves or must-avoids)

### 2. Set Credentials (Required)

TradeMe API requires OAuth authentication even for basic searches. Set credentials:
```bash
export TRADEME_CONSUMER_KEY="your_key_here"
export TRADEME_CONSUMER_SECRET="your_secret_here"
```

API registration: https://www.trademe.co.nz/MyTradeMe/Api/MyApplications.aspx

Note: You only need consumer key/secret (app-level auth), not access tokens (user-level auth).

### 3. Fetch Listings

Run multiple search variations to cast a wide net:

```bash
python scripts/trademe_search.py "girls bike 24 inch" --region 2 --price-max 200 --rows 100 --json > results.json
```

**Strategy:** Use different keyword combinations, try with/without category filters, search broader than needed (AI will filter).

### 4. AI Analysis

This is the core step. For each candidate listing, analyze:

**From description text:**
- Does it match the requirements? (size, type, features)
- Seller communication quality (detailed = trustworthy)
- Red flags (vague descriptions, pressure tactics)
- Pickup/delivery options

**From images (fetch and view each listing's photos):**
- **Condition**: Wear, scratches, rust, damage, cleanliness
- **Colour**: Match user preference
- **Style**: Modern/classic, sporty/casual, kid-friendly
- **Completeness**: All parts present, accessories included
- **Photo quality**: Real photos vs stock images, multiple angles = trustworthy

**From metadata:**
- Distance from user (use `references/trademe_api.md` for suburb coordinates)
- Price vs value assessment
- Buy Now availability (convenience)

### 5. Rank and Recommend

Score each listing holistically based on user's stated priorities. Present top 5-10 with:

- Title, price, location
- **Why it's a good match** (specific reasons)
- **Concerns** (if any)
- Image observations
- Link: `https://www.trademe.co.nz/a/{ListingId}`

## Example Session

**User:** "Find a second-hand bike for my 9 year old daughter. We're in Grey Lynn. Budget $100-150. She wants pink or purple, and it needs to be in good condition - safe for a beginner."

**Step 1 - Parse requirements:**
- 9 years old → 20-24 inch wheels
- Grey Lynn → prioritize Auckland central/west
- $100-150 → search up to $180 for great matches
- Pink/purple → check images
- Good condition, beginner-safe → AI assessment of photos

**Step 2 - Fetch listings:**
```bash
python scripts/trademe_search.py "girls bike 24" --region 2 --price-max 180 --rows 50 --json > r1.json
python scripts/trademe_search.py "girls bike 20" --region 2 --price-max 180 --rows 50 --json > r2.json
python scripts/trademe_search.py "kids bike pink" --region 2 --price-max 180 --rows 50 --json > r3.json
```

**Step 3 - AI analysis for each promising listing:**

For listing with photos, fetch and assess:
- "Pink frame, appears well-maintained, minor scratches on pedals"
- "Has training wheel mounts - good for beginner"
- "Real photos from multiple angles - trustworthy seller"

**Step 4 - Recommend:**

"Based on your requirements, here are my top 3 picks:

1. **24" Girls Apollo Bike - $120** (Pt Chevalier, 3km away)
   - Pink frame, great condition in photos
   - Seller included 6 clear photos showing all angles
   - Has kickstand and bell included
   - [View listing](https://www.trademe.co.nz/a/12345)

2. **20" Princess Bike - $95** (Grey Lynn, 1km away)
   - Purple with white accents
   - Some wear on grips but frame looks solid
   - Very close to you for easy pickup
   - [View listing](https://www.trademe.co.nz/a/12346)

..."

## Quick Reference

### Bike Sizing
| Age | Wheel Size |
|-----|------------|
| 4-6 | 16" |
| 5-8 | 18" |
| 7-9 | 20" |
| 8-11 | 24" |
| 10+ | 26" |

### Common Categories
| Item | Category Code |
|------|---------------|
| Kids bikes | `0350-0369-4548-` |
| Furniture | `0329-1482-` |
| Electronics | `0002` |
| Baby gear | `0335` |

### Image Analysis Checklist

When viewing listing photos, assess:
- [ ] Condition (scratches, rust, wear, damage)
- [ ] Colour match to user preference
- [ ] Style/aesthetic fit
- [ ] All parts present
- [ ] Real photos (not stock)
- [ ] Multiple angles (trustworthy seller)
- [ ] Clean environment (well-cared-for item)

See `references/trademe_api.md` for full API details.