# Best Buy Search

## Overview

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

## Description

Search Best Buy US or Canada by keyword or search URL. Returns product listings with price, rating 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/bestbuy/search' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Keyword machine (US)

```json
{
  "results": [
    {
      "url": "https://www.bestbuy.com/product/singing-machine-smk302pp-kids-bluetooth-headphones-pink-collectibles-multicolor/J7GW9JWXZ5",
      "type": "product",
      "price": 29.99,
      "title": "Singing Machine - SMK302PP Kids Bluetooth Headphones Pink - COLLECTIBLES - Multicolor",
      "currency": "USD",
      "condition": "new",
      "image_url": "https://pisces.bbystatic.com/image2/BestBuy_US/images/products/014a6bfe-fd8a-413d-a204-49efbdb9baaa.jpg",
      "product_id": "J7GW9JWXZ5"
    }
  ],
  "pagination": {
    "next": 2,
    "page": 1,
    "per_page": 18,
    "total_pages": 763,
    "has_next_page": true,
    "total_results": 13730
  }
}
```

## Documentation

## Overview
The **Best Buy Search** endpoint searches Best Buy US (`bestbuy.com`) or Canada (`bestbuy.ca`) by keyword or search URL.

It returns product listings with price, rating and images, plus pagination. Browser rendering is used because Best Buy pages load products with JavaScript.

Costs **2 credits** per call.

## Quickstart
```
GET https://api.piloterr.com/v2/bestbuy/search?query=machine
GET https://api.piloterr.com/v2/bestbuy/search?query=machine&region=ca
GET https://api.piloterr.com/v2/bestbuy/search?query=machine&sort=best_discount
GET https://api.piloterr.com/v2/bestbuy/search?query=https://www.bestbuy.com/site/searchpage.jsp?st=machine
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Keyword or Best Buy search URL |
| `region` | string | no | `com` (default, USD) or `ca` (CAD). Detected from a full URL |
| `page` | integer | no | Page number (default: `1`) |
| `sort` | string | no | `best_selling` (default) or `best_discount` |
| `return_page_source` | boolean | no | Return rendered HTML instead of JSON |

## Regions
| `region` | Host | Currency |
|---|---|---|
| `com` | www.bestbuy.com | USD |
| `ca` | www.bestbuy.ca | CAD |

## Response fields
| Field | Type | Description |
|---|---|---|
| `results` | array | Product listings |
| `results[].type` | string | Always `product` |
| `results[].product_id` / `title` / `url` | string | Identifiers and link |
| `results[].price` / `original_price` / `currency` | mixed | Pricing when present |
| `results[].rating` / `review_count` | number | Reviews when present |
| `pagination` | object | `page`, `per_page`, `total_results`, `total_pages`, `has_next_page`, `next` |

## Error codes
| Code | Meaning |
|---|---|
| `400` | Empty or invalid `query` |
| `404` | Page has no usable listings |
| `500` | Rendering failed |

## Related endpoints
- [Best Buy Product](https://www.piloterr.com/library/bestbuy-product)