Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 49 additions & 33 deletions LLMS.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,6 @@ Create a JSON file with the listing details:
"price": 25,
"categoryPath": ["BOOKSFILMANDMUSIC", "NON_FICTION_BOOKS"],
"postCode": "8010",
"locationId": 117458,
"location": "Jakomini",
"condition": "gebraucht",
"delivery": ["PICKUP", "Versand"]
Expand All @@ -88,55 +87,50 @@ Create a JSON file with the listing details:
| `price` | number | Price in EUR (use 0 for "Zu verschenken") |
| `categoryPath` | string[] | Category path codes from `categories list` |
| `postCode` | string | Austrian postal code (e.g., "8010") |
| `locationId` | number | District ID (see Location IDs below) |
| `location` | string | District name |

#### Optional Fields

| Field | Type | Description |
|-------|------|-------------|
| `location` | string | Location name, required if the postcode has several locations (see below) |
| `locationId` | number | Location id, looked up automatically from `postCode` + `location` |
| `condition` | string | `"neu"`, `"gebraucht"`, or `"defekt"` |
| `delivery` | string[] | `["PICKUP"]`, `["Versand"]`, or both |
| `images` | string[] | Image files (jpg, png, gif, webp), relative to the template file. First is the cover |
| `street` | string | Street address |
| `attributes` | object | Category-specific attributes |
| `contactInfo.name` | string | Contact name override |
| `skipValidation` | boolean | Skip client-side validation |

#### Common Location IDs (Graz)

| District | locationId | postCode |
|----------|------------|----------|
| Innere Stadt | 117451 | 8010 |
| St. Leonhard | 117452 | 8010 |
| Geidorf | 117453 | 8010 |
| Lend | 117454 | 8020 |
| Gries | 117455 | 8020 |
| Jakomini | 117458 | 8010 |
| Liebenau | 117459 | 8041 |
| St. Peter | 117460 | 8042 |
| Waltendorf | 117461 | 8010 |
| Ries | 117462 | 8010 |
| Mariatrost | 117463 | 8043 |
| Andritz | 117464 | 8045 |
| Gösting | 117465 | 8051 |
| Eggenberg | 117466 | 8020 |
| Wetzelsdorf | 117467 | 8052 |
| Straßgang | 117468 | 8053 |
| Puntigam | 117469 | 8055 |

For other cities, use the postCode and a general locationId for the area.
#### Locations

`publish` resolves the location from `postCode`. If a postcode has several locations (e.g. the districts of Graz under 8010), set `location` to one of the names listed by:

```bash
willhaben locations 8010
willhaben locations 8010 --json
```

### Step 3: Publish the Listing

`publish` saves a draft, uploads the template's `images`, then puts the listing live. If an image upload fails, the listing stays a draft and the error contains its ID.

```bash
# Publish from template file
willhaben publish listing.json

# Save as draft only, so the user can review it in the willhaben app first
willhaben publish listing.json --draft
# ...then put it live
willhaben activate <listing-id>

# Output as JSON (for programmatic use)
willhaben publish listing.json --json
```

### Step 4: Upload Images
Prefer `--draft` when the user hasn't explicitly asked to publish right away.

### Step 4: Manage Images Later

```bash
# Upload single image
Expand Down Expand Up @@ -175,6 +169,9 @@ willhaben update <listing-id> --description "Updated description"
willhaben delete <listing-id>
willhaben delete <listing-id> --force # Skip confirmation

# Put a draft live
willhaben activate <listing-id>

# Deactivate (take offline temporarily)
willhaben deactivate <listing-id>

Expand All @@ -189,6 +186,25 @@ willhaben unreserve <listing-id>
willhaben sold <listing-id>
```

## Searching Listings

Search works without login. Use it to check comparable prices before setting a price.

```bash
willhaben search nintendo switch --json
willhaben search fahrrad --min 100 --max 300 --state steiermark --private --sort price-asc --json

# List available filters (categories, condition, delivery, ...) with their url params
willhaben search fahrrad --facets --json
# Apply one with --filter <param>=<value> (repeatable), e.g. condition "Neu":
willhaben search fahrrad --filter treeAttributes=22 --json
```

`--category` takes the search category id from the `category` facet (`ATTRIBUTE_TREE`). These ids are not the `categoryPath` codes used for publishing.

States: burgenland, kaernten, niederoesterreich, oberoesterreich, salzburg, steiermark, tirol, vorarlberg, wien.
Sort: newest, nearest, price-asc, price-desc, relevance.

## Example: Complete Listing Creation Flow

```bash
Expand All @@ -210,18 +226,18 @@ cat > listing.json << 'EOF'
"price": 15,
"categoryPath": ["BOOKSFILMANDMUSIC", "NON_FICTION_BOOKS"],
"postCode": "8010",
"locationId": 117458,
"location": "Jakomini",
"condition": "gebraucht",
"delivery": ["PICKUP", "Versand"]
"delivery": ["PICKUP", "Versand"],
"images": ["buch_cover.jpg", "buch_rueckseite.jpg"]
}
EOF

# 5. Publish
willhaben publish listing.json
# 5. Save as draft with images, let the user review it in the app
willhaben publish listing.json --draft

# 6. Upload images (use listing ID from publish output)
willhaben upload-image <listing-id> buch_cover.jpg buch_rueckseite.jpg
# 6. Put it live (use listing ID from publish output)
willhaben activate <listing-id>
```

## JSON Output Mode
Expand Down
72 changes: 55 additions & 17 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,11 @@
- Republish expired listings
- Bulk operations support

**Search**
- Search marketplace listings without logging in
- Filter by price, state, seller type, condition, delivery, and category
- Postcode to location lookup for listing templates

**Image Support**
- Upload single or multiple images
- View listing images
Expand Down Expand Up @@ -135,18 +140,21 @@ Create a template file `my-item.json`:
"description": "Selling my iPhone 14 Pro 256GB in excellent condition...",
"price": 799,
"postCode": "1010",
"locationId": 900,
"location": "Wien",
"categoryPath": ["MOBILE_ELECTRONICS", "MOBILE_PHONES", "IPHONE"],
"condition": "gebraucht",
"delivery": ["PICKUP", "Versand"]
"delivery": ["PICKUP", "Versand"],
"images": ["photo1.jpg", "photo2.jpg"]
}
```

Then publish:

```bash
willhaben publish my-item.json

# Or save a draft first, check it in the app, then put it live
willhaben publish my-item.json --draft
willhaben activate <id>
```

---
Expand All @@ -166,16 +174,24 @@ willhaben publish my-item.json
| Command | Description |
|---------|-------------|
| `willhaben list` | List all your listings |
| `willhaben get <id>` | Get details of a listing |
| `willhaben publish <file>` | Create a new listing from JSON |
| `willhaben get <id>` | Get details of a listing (yours or any public one) |
| `willhaben publish <file>` | Create a new listing from JSON, with images (`--draft` to review first) |
| `willhaben update <id>` | Update listing properties |
| `willhaben delete <id>` | Delete a listing |
| `willhaben activate <id>` | Put a draft live |
| `willhaben republish <id>` | Republish an expired listing |
| `willhaben deactivate <id>` | Take a listing offline |
| `willhaben reserve <id>` | Mark as reserved |
| `willhaben unreserve <id>` | Remove reservation |
| `willhaben sold <id>` | Mark as sold |

### Search

| Command | Description |
|---------|-------------|
| `willhaben search [keyword...]` | Search marketplace listings (no login required) |
| `willhaben locations <postcode>` | Look up location ids for a postcode |

### Images

| Command | Description |
Expand Down Expand Up @@ -224,6 +240,32 @@ willhaben get 123456789 --cached
willhaben get 123456789 --json
```

### Search Listings

```bash
# Keyword search
willhaben search nintendo switch

# Filters: price range, state, private sellers only, newest first
willhaben search fahrrad --min 100 --max 300 --state steiermark --private --sort newest

# Show the available filters (categories, condition, delivery, ...) with hit counts
willhaben search fahrrad --facets

# Apply a filter from --facets, e.g. condition "Neu"
willhaben search fahrrad --filter treeAttributes=22

# Output as JSON
willhaben search iphone --rows 50 --json
```

### Look Up Locations

```bash
# Find the location for a postcode (used by listing templates)
willhaben locations 8010
```

### Update Listing

```bash
Expand Down Expand Up @@ -269,17 +311,18 @@ willhaben upload-image 123456789 photo1.jpg photo2.jpg photo3.jpg
| `description` | string | Detailed description |
| `price` | number | Price in EUR |
| `postCode` | string | Postal code (e.g., "8010") |
| `locationId` | number | Willhaben location ID |
| `location` | string | District/city name |
| `categoryPath` | string[] | Category path from root to leaf |

### Optional Fields

| Field | Type | Description |
|-------|------|-------------|
| `location` | string | Location name from `willhaben locations <postcode>`. Needed if the postcode has several locations |
| `locationId` | number | Location id. Looked up from `postCode` and `location` if omitted |
| `street` | string | Street address |
| `condition` | string | `"neu"`, `"gebraucht"`, or `"defekt"` |
| `delivery` | string[] | `["PICKUP"]`, `["Versand"]`, or both |
| `images` | string[] | Image files, relative to the template file. Uploaded before the listing goes live |
| `attributes` | object | Category-specific attributes |
| `contactInfo` | object | Contact information override |
| `skipValidation` | boolean | Skip attribute validation |
Expand All @@ -295,7 +338,6 @@ willhaben upload-image 123456789 photo1.jpg photo2.jpg photo3.jpg
"description": "Verkaufe meinen HP LaserJet Pro Drucker...",
"price": 120,
"postCode": "8010",
"locationId": 117458,
"location": "Jakomini",
"categoryPath": [
"COMPUTER_SOFTWARE",
Expand All @@ -321,8 +363,6 @@ willhaben upload-image 123456789 photo1.jpg photo2.jpg photo3.jpg
"description": "DJI Mini 3 Pro mit allem Zubehör...",
"price": 750,
"postCode": "1010",
"locationId": 900,
"location": "Wien",
"categoryPath": [
"LEISURE_INSTRUMENTS_CULINARY",
"MODEL_MAKING",
Expand All @@ -348,8 +388,6 @@ willhaben upload-image 123456789 photo1.jpg photo2.jpg photo3.jpg
"description": "Buch in sehr gutem Zustand...",
"price": 15,
"postCode": "5020",
"locationId": 30501,
"location": "Salzburg",
"categoryPath": [
"BOOKSFILMANDMUSIC",
"NON_FICTION_BOOKS"
Expand Down Expand Up @@ -497,11 +535,11 @@ The API was reverse-engineered from the willhaben mobile app using [mitmproxy](h
<details>
<summary><strong>How do I find my locationId?</strong></summary>

Location IDs can be found in the category tree response or by inspecting the willhaben app traffic. Common IDs:
- Vienna (Wien): 900
- Graz: 117458
- Salzburg: 30501
- Linz: 40101
You usually don't need it. `publish` looks it up from `postCode`, using `location` to pick one when a postcode has several locations (e.g. the districts of Graz under 8010). To see the options:

```bash
willhaben locations 8010
```
</details>

<details>
Expand Down
2 changes: 2 additions & 0 deletions docs/.vitepress/config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,8 @@ export default defineConfig({
{ text: 'update', link: '/commands/update' },
{ text: 'delete', link: '/commands/delete' },
{ text: 'images', link: '/commands/images' },
{ text: 'search', link: '/commands/search' },
{ text: 'locations', link: '/commands/locations' },
{ text: 'config', link: '/commands/config' },
]
}
Expand Down
6 changes: 3 additions & 3 deletions docs/commands/get.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# get

Get detailed information about a specific listing.
Get detailed information about a listing: one of yours, or any public listing (e.g. from [`search`](/commands/search)).

## Usage

Expand Down Expand Up @@ -77,6 +77,6 @@ willhaben get 123456789 --json
}
```

## Requires Authentication
## Authentication

You must be logged in to use this command.
Works without login for public listings. When logged in, your session is used.
10 changes: 9 additions & 1 deletion docs/commands/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,15 +15,23 @@ Quick reference for all willhaben-cli commands.
| Command | Description |
|---------|-------------|
| [`list`](/commands/list) | List all your listings |
| [`get`](/commands/get) | Get listing details |
| [`get`](/commands/get) | Get listing details (yours or any public one) |
| [`publish`](/commands/publish) | Create a new listing |
| [`update`](/commands/update) | Update listing properties |
| [`delete`](/commands/delete) | Delete a listing |

## Search

| Command | Description |
|---------|-------------|
| [`search`](/commands/search) | Search marketplace listings (no login required) |
| [`locations`](/commands/locations) | Look up location ids for a postcode |

## Listing Actions

| Command | Description |
|---------|-------------|
| `activate <id>` | Put a draft live |
| `republish <id>` | Republish an expired listing |
| `deactivate <id>` | Take a listing offline |
| `reserve <id>` | Mark as reserved |
Expand Down
Loading
Loading