# Zooplus Search

## Overview

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

## Description

Zooplus Search API. Search pet food and supplies by keyword or URL across 26 Zooplus/Zoohit shops. Parses Next.js RSC initialStoreState; returns prices, ratings and pagination.

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

## Example Response

### Search 'croquette' on zooplus.fr (page 1)

```json
{
  "results": [
    {
      "url": "https://www.zooplus.fr/shop/chiens/croquettes_chien/croquettes_chien_pedigree/lot_economique_pedigree/318589",
      "price": 66.49,
      "title": "Lot Pedigree pour chien",
      "rating": 4,
      "summary": "Croquettes pour chien Pedigree composées de viandes et de légumes délicieux. Un pur régal à chaque croquette !",
      "currency": "EUR",
      "image_url": "https://media.zooplus.com/bilder/5/400/318589_pedigree_2x_5.jpg",
      "is_on_sale": true,
      "product_id": "318589",
      "review_count": 36,
      "variant_count": 8
    },
    {
      "url": "https://www.zooplus.fr/shop/chats/croquettes_chat/royal_canin_croquettes_chat/sterilised/47497",
      "price": 77.99,
      "title": "Royal Canin Sterilised 37",
      "rating": 5,
      "summary": "Croquettes complètes pour chats adultes castrés et stérilisés ayant tendance à l'embonpoint.",
      "currency": "EUR",
      "image_url": "https://media.zooplus.com/bilder/5/400/rc_fhn_sterilised37_mv_eretailkit_fr_fr_5.jpg",
      "product_id": "47497",
      "review_count": 678,
      "variant_count": 1
    }
  ],
  "pagination": {
    "next": "https://www.zooplus.fr/search/results?q=croquette&p=2",
    "page": 1,
    "per_page": 26,
    "total_pages": 209,
    "total_results": null
  }
}
```

## Documentation

## Overview
The **Zooplus Search API** returns pet product listings from Zooplus online shops. Pass a **keyword** or a **full search URL**, optionally with **`region`** and **`page`**, and receive structured JSON with prices, ratings, summaries, and pagination.

Piloterr fetches the SSR HTML and parses the Next.js RSC stream (`self.__next_f.push` + `initialStoreState`). No browser rendering required.

Use each result `url` or `product_id` with [Zooplus Product](https://www.piloterr.com/library/zooplus-product) for full PDP data.

## Supported regions
26 footer regions. Default: `fr` → `www.zooplus.fr`.

| `region` | Domain | Currency | Aliases |
|---|---|---|---|
| `fr` | zooplus.fr | EUR | `fr-fr` |
| `de` | zooplus.de | EUR | `de-de` |
| `gb` | zooplus.co.uk | GBP | `uk`, `en-gb` |
| `pl` | zooplus.pl | PLN | `pl-pl` |
| `cs` | zoohit.cz | CZK | `cz`, `cs-cz` |
| `ch-fr` | zooplus.ch/fr | CHF | `fr-ch` |
| `com` | zooplus.com | EUR | `en`, `intl` |
| … | see docs | … | 26 regions total |

When `query` is a full Zooplus/Zoohit URL, domain and region are detected automatically (`region` is ignored).

## Quickstart
```
GET https://api.piloterr.com/v2/zooplus/search?query=croquettes+chat
GET https://api.piloterr.com/v2/zooplus/search?query=croquettes+chat&region=fr
GET https://api.piloterr.com/v2/zooplus/search?query=https://www.zooplus.fr/search/results?q=croquettes+chat
GET https://api.piloterr.com/v2/zooplus/search?query=croquette&page=2
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Keyword or full search URL |
| `region` | string | no | Country when `query` is a keyword (default: `fr`) |
| `page` | integer | no | 1-based page override (default: from URL or `1`) |
| `return_page_source` | boolean | no | Raw HTML as `{"result": "..."}` (default: `false`) |

## Listings (`results[]`)
| Field | Type | Description |
|---|---|---|
| `product_id` | string | `shopIdentifier` |
| `title` | string | Product title |
| `url` | string | Absolute product URL |
| `image_url` | string \| null | Card image (`picture400` / `picture200`) |
| `price` | number \| null | Displayed price |
| `currency` | string | ISO currency from shop |
| `summary` | string \| null | Short teaser text |
| `rating` | number \| null | Average rating |
| `review_count` | integer \| null | Number of reviews |
| `variant_count` | integer \| null | Available variants |
| `is_on_sale` | boolean \| null | Reduced price flag |
| `is_new` | boolean \| null | New product flag |

## Pagination
| Field | Type | Description |
|---|---|---|
| `page` | integer | Current page |
| `per_page` | integer | Results on this page (deduplicated count) |
| `total_results` | integer \| null | Often `null` |
| `total_pages` | integer \| null | Total pages |
| `next` | string \| null | Next page URL (`p=2`, …) |

Raw SSR pages may contain ~48 entries; results are deduplicated by `shopIdentifier`.

## Zooplus workflow
1. [Zooplus Search](https://www.piloterr.com/library/zooplus-search) to discover listings (this endpoint)
2. [Zooplus Product](https://www.piloterr.com/library/zooplus-product) for full PDP JSON

## Error codes
| Code | Meaning |
|---|---|
| `400` | Missing or invalid `query` / `region` |
| `404` | Page without parseable search state |
| `500` | Network or parsing error |

## Notes
- Pagination uses query param **`p`**, not `page`.
- Costs **1 credit** per call (HTTP crawler).

## Main use cases
- **Pet retail discovery**: harvest product ids across keywords and regions
- **Price monitoring**: track promotions (`is_on_sale`) on food and accessories
- **Catalog intel**: ratings and variant counts before fetching full PDP data