# Costco Search

## Overview

| Property | Value |
|----------|-------|
| **Status** | active |
| **Method** | `GET` |
| **Endpoint** | `/v2/costco/search` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 2 credits per call |
| **Documentation** | https://www.piloterr.com/library/costco-search |

## Description

Costco Search API: search product listings by keyword or URL across 13 regional Costco sites. Returns prices, availability, review counts and pagination via browser rendering.

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/costco/search' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Search 'home' on costco.com (page 1)

```json
{
  "results": [
    {
      "url": "https://www.costco.com/mohawk-home-6mm-thick-94in-x-478in-22-mil-waterproof-luxury-vinyl-plank-flooring-1565-sq-ftctn.product.4000266385.html",
      "price": 40.99,
      "title": "Mohawk Home 6MM Thick 9.4in X 47.8in 22 MIL Waterproof Luxury Vinyl Plank Flooring (15.65 sq ft/ctn)",
      "region": "www.costco.com",
      "currency": "USD",
      "image_url": "https://bfasset.costco-static.com/U447IH35/as/6wxn2893r8g35r5p98jnkw2v/4000266385-847_tudoroak_1?auto=webp&format=jpg",
      "product_id": "4000266385",
      "availability": "delivery",
      "review_count": 84
    }
  ],
  "pagination": {
    "next": "https://www.costco.com/s?keyword=home&currentPage=2",
    "page": 1,
    "region": "www.costco.com",
    "per_page": 24,
    "total_pages": 36,
    "total_results": 860
  }
}
```

## Documentation

## Overview
The **Costco Search API** returns product listings from [Costco](https://www.costco.com) regional sites. Pass a **keyword**, a **full search URL**, or a keyword with **`region`** and receive structured JSON with prices, availability, review counts, and pagination.

Piloterr uses **browser rendering** (`wait_for=#costco-consent-manager`, ~8s) to load search result tiles across supported regional hosts.

Use each result `url` with **Costco Product** for full PDP data (brand, description, images, breadcrumbs).

## Supported regions
| Code | Host | Search path | Page param |
|---|---|---|---|
| `us` / `com` | www.costco.com | `/s?keyword=` | `currentPage` |
| `fr` | www.costco.fr | `/s?keyword=` | `currentPage` |
| `es` | www.costco.es | `/s?keyword=` | `currentPage` |
| `mx` | www.costco.com.mx | `/s?keyword=` | `currentPage` |
| `kr` | www.costco.co.kr | `/s?keyword=` | `currentPage` |
| `tw` | www.costco.com.tw | `/s?keyword=` | `currentPage` |
| `jp` | www.costco.co.jp | `/s?keyword=` | `currentPage` |
| `au` | www.costco.com.au | `/s?keyword=` | `currentPage` |
| `is` | www.costco.is | `/s?keyword=` | `currentPage` |
| `nz` | www.costco.co.nz | `/s?keyword=` | `currentPage` |
| `se` | www.costco.se | `/s?keyword=` | `currentPage` |
| `ca` | www.costco.ca | `/CatalogSearch?keyword=` | `currentPage` |
| `uk` | www.costco.co.uk | `/search?text=` | `page` |

CA and UK use dedicated search URL formats; other regions follow the US-like `/s?keyword=` pattern.

## Quickstart
```
GET https://api.piloterr.com/v2/costco/search?query=home
GET https://api.piloterr.com/v2/costco/search?query=home&region=fr
GET https://api.piloterr.com/v2/costco/search?query=https://www.costco.co.uk/search?text=sonos
GET https://api.piloterr.com/v2/costco/search?query=https://www.costco.ca/CatalogSearch?keyword=home&currentPage=2
```

Via POST:
```
POST https://api.piloterr.com/v2/costco/search
Content-Type: application/json

{"query": "home", "region": "fr", "return_page_source": false}
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Keyword or full regional search URL |
| `region` | string | no | Region code or host when `query` is a keyword only (default: US) |
| `page` | integer | no | 1-based page override (`currentPage` or `page` depending on region) |
| `return_page_source` | boolean | no | Raw HTML as `{"result": "..."}` (default: `false`) |

## Input formats
| Format | Example |
|---|---|
| Keyword (US) | `home` → `https://www.costco.com/s?keyword=home` |
| Keyword + region | `home` + `region=fr` → `https://www.costco.fr/s?keyword=home` |
| Full URL | `https://www.costco.co.uk/search?text=sonos` |
| Paginated URL | `https://www.costco.ca/CatalogSearch?keyword=home&currentPage=2` |

## Response: each listing (`results[]`)
| Field | Type | Description |
|---|---|---|
| `product_id` | string | Catalog product ID |
| `title` | string | Product title |
| `url` | string | Product page URL |
| `image_url` | string \| null | Main thumbnail |
| `price` | number \| null | Display price |
| `currency` | string \| null | ISO 4217 code |
| `review_count` | integer \| null | Review count |
| `availability` | string \| null | e.g. `delivery`, `in_stock` |
| `region` | string | Regional host |

## Response: pagination
| Field | Type | Description |
|---|---|---|
| `page` | integer | Current page |
| `per_page` | integer | Listings on this page |
| `total_results` | integer \| null | Total matching products |
| `total_pages` | integer \| null | Total pages |
| `next` | string \| null | Rebuilt next-page URL (respects regional page param) |
| `region` | string | Regional host |

## Costco API workflow
1. **Costco Search**: discover listings by keyword or URL (this endpoint)
2. **Costco Product**: fetch full PDP JSON from any result `url` or product ID

## Error codes
| Code | Meaning |
|---|---|
| `400` | Missing or invalid `query` |
| `404` | Search page not parseable |
| `500` | Rendering or parsing error |

## Notes
- UK pagination uses `page=`; most other regions use `currentPage=`.
- Costs **2 credits** per call (browser rendering).

## Main use cases
- **Multi-region repricing**: monitor Costco prices across US, CA, UK, FR, and more
- **Catalog discovery**: harvest `product_id` and URLs at scale
- **Search rank tracking**: track listing visibility by keyword and region