# Chewy Products Finder

## Overview

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

## Description

Find Chewy product URLs by product name, ID, or any combination of filters to use in product detail and rendering API calls.

## 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/finder/chewy-products' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Search by query 'salmon'

```json
[
  {
    "id": "312253",
    "url": "https://www.chewy.com/blue-buffalo-life-protection-formula/dp/312253",
    "title": "Blue Buffalo Life Protection Formula Adult Chicken & Brown Rice Recipe Dry Dog Food",
    "domain": "com"
  },
  {
    "id": "133035",
    "url": "https://www.chewy.com/wellness-complete-health-natural-dry/dp/133035",
    "title": "Wellness Complete Health Natural Dry Dog Food, Salmon & Sweet Potato Recipe",
    "domain": "com"
  }
]
```

### Lookup multiple IDs

```json
[
  {
    "id": "312253",
    "url": "https://www.chewy.com/blue-buffalo-life-protection-formula/dp/312253",
    "title": "Blue Buffalo Life Protection Formula Adult Chicken & Brown Rice Recipe Dry Dog Food",
    "domain": "com"
  },
  {
    "id": "312254",
    "url": "https://www.chewy.com/blue-buffalo-life-protection-formula-2/dp/312254",
    "title": "Blue Buffalo Life Protection Formula Adult Lamb & Brown Rice Recipe Dry Dog Food",
    "domain": "com"
  }
]
```

### Search with count=true

```json
{
  "hits": [
    {
      "id": "312253",
      "url": "https://www.chewy.com/blue-buffalo-life-protection-formula/dp/312253",
      "title": "Blue Buffalo Life Protection Formula Adult Chicken & Brown Rice Recipe Dry Dog Food",
      "domain": "com"
    }
  ],
  "count": 842
}
```

## Documentation

## Overview
The Chewy Products Finder endpoint allows you to discover Chewy product URLs by searching with a product name, ID, or any combination of filters. It is primarily designed as a pre-step before calling the Website Rendering API on Chewy product pages, enabling you to resolve identifiers into actionable product URLs.

## Quickstart
```
GET https://api.piloterr.com/v2/finder/chewy-products?search=dog+food
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `search` | string | conditional | Free-text search across product titles and IDs. Required if no filter is provided. |
| `query` | string | conditional | Legacy alias of `search`. |
| `id` | string | no | One or several internal product IDs (comma-separated). |
| `domain` | string | no | One or several website domains (comma-separated). |
| `filter` | string | no | Raw filter expression for advanced filtering. |
| `limit` | integer | no | Max results, default `10`, capped at `100`. |
| `offset` | integer | no | Pagination offset, default `0`. |
| `sort` | string | no | Sort attributes (e.g. `title:asc`, comma-separated). |
| `fields` | string | no | Comma-separated list of fields to return. |
| `count` | boolean | no | When `true`, wraps the response as `{ count, hits }`. Default `false`. |

## Response

### Default response
Returns a JSON array of product objects:
```json
[
  { "id": "312253", "url": "...", "title": "...", "domain": "com" }
]
```

### Response when `count=true`
Returns an object with the total estimated number of matches and the page of results:
```json
{
  "count": 842,
  "hits": [
    { "id": "312253", "url": "...", "title": "...", "domain": "com" }
  ]
}
```

### Response fields
| Field | Type | Description |
|---|---|---|
| `id` | string | Internal product identifier |
| `url` | string | Direct Chewy product URL |
| `title` | string | Full product title |
| `domain` | string | Website domain (e.g. `com`) |
| `count` | integer | Total estimated number of matches (only when `count=true`) |
| `hits` | array | Array of product objects (only when `count=true`) |

## Examples

### Free-text search
```
GET /v2/finder/chewy-products?search=dog+food
```

### Lookup by one or several IDs
```
GET /v2/finder/chewy-products?id=312253,312254
```

### Search restricted to a domain, paginated
```
GET /v2/finder/chewy-products?search=salmon&domain=com&limit=20&offset=20
```

### Get total count and a slice of results
```
GET /v2/finder/chewy-products?search=dog+food&count=true&limit=10
```

### Advanced filter
```
GET /v2/finder/chewy-products?filter=domain%20%3D%20%22com%22%20AND%20title%20CONTAINS%20%22puppy%22
```

## Notes
- At least one of `search` (or `query`) or a filter (`id`, `domain`, `filter`, ...) must be provided.
- Returns up to `limit` results ordered by relevance (or by `sort` if provided).
- When `count=true`, an empty result set returns `{ count: 0, hits: [] }` with a 200 status. Without `count`, an empty result set returns a 404.
- Use returned URLs with the Website Rendering API to extract full product data.
- Accepts both free-text product names and numeric product IDs.

## Main use cases
- Find Chewy product URLs by keyword or ID before rendering product detail pages.
- Resolve a batch of internal product IDs to URLs in a single call.
- Build a pet supplies product catalog from Chewy.
- Estimate the size of a result set with `count=true` before paginating through it.
- Automate price monitoring pipelines for pet food, treats and accessories.
- Cross-reference product references across pet supplies retailers.