# Target Search

## Overview

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

## Description

Search Target.com by keyword or search URL. Returns product cards 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/target/search' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Root touch up hair dye

```json
{
  "results": [
    {
      "url": "https://www.target.com/p/l-oreal-paris-magic-root-rescue-10-minute-root-hair-coloring-kit/-/A-54397299",
      "name": "L'Oreal Paris Magic Root Rescue 10 Minute Root Hair Coloring Kit",
      "tcin": "54397299",
      "brand": "L'Oreal Paris",
      "price": 6.99,
      "rating": 4,
      "currency": "USD",
      "image_url": "https://target.scene7.com/is/image/Target/GUEST_c22ac354-59d7-4187-ab0b-8cd8a4707e07?qlt=65&fmt=webp&hei=350&wid=350",
      "sponsored": true,
      "review_count": 1525
    }
  ],
  "pagination": {
    "next": "https://www.target.com/s?searchTerm=root+touch+up+hair+dye&Nao=24",
    "page": 1,
    "per_page": 24,
    "total_pages": 9,
    "total_results": 201
  }
}
```

## Documentation

## Overview
Search products on Target.com. Pass a keyword or a Target search URL. You get product cards with name, brand, price, rating and image, plus pagination.

Browser rendering. Costs **2 credits** per call.

## Quickstart
```
GET https://api.piloterr.com/v2/target/search?query=shampoo
GET https://api.piloterr.com/v2/target/search?query=root+touch+up+hair+dye
GET https://api.piloterr.com/v2/target/search?query=https://www.target.com/s?searchTerm=shampoo&page=2
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Keyword or Target search URL (`/s?searchTerm=…`) |
| `page` | string | no | Page number (1-based) |
| `return_page_source` | boolean | no | Return rendered HTML instead of JSON |

Category URLs (`/c/…`) are not supported.

## Response fields
| Field | Type | Description |
|---|---|---|
| `results` | array | Product cards |
| `results[].tcin` | string | Target product id |
| `results[].name` / `brand` | string | Title and brand |
| `results[].url` / `image_url` | string | Product link and image |
| `results[].price` / `currency` | number / string | Price in USD |
| `results[].rating` / `review_count` | number | Reviews when present |
| `results[].sponsored` | boolean | Sponsored listing |
| `pagination` | object | `page`, `per_page`, `total_results`, `total_pages`, `next` |

## Error codes
| Code | Meaning |
|---|---|
| `400` | Empty query, category URL, or not Target.com |
| `404` | No products found |
| `500` | Rendering failed |

## Related endpoints
- [Target Product](https://www.piloterr.com/library/target-product)