# Action Search

## Overview

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

## Description

Action Search API: search product listings by keyword or URL on Action.com across European locales. Returns prices, images, locale, currency 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/action/search' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Search 'meuble' on action.com fr-fr (page 1)

```json
{
  "results": [
    {
      "url": "https://www.action.com/fr-fr/p/3220594/meuble-d-entree/",
      "price": 32.95,
      "title": "Meuble d'entrée",
      "locale": "fr-fr",
      "currency": "EUR",
      "image_url": "https://asset.action.com/image/upload/3220594_8718964261123-110_01_l7lvqj",
      "product_id": "3220594"
    },
    {
      "url": "https://www.action.com/fr-fr/p/3216159/etagere/",
      "price": 39.95,
      "title": "Étagère",
      "locale": "fr-fr",
      "currency": "EUR",
      "image_url": "https://asset.action.com/image/upload/3216159_8718964237609-110_01_lbhy6y",
      "product_id": "3216159"
    },
    {
      "url": "https://www.action.com/fr-fr/p/3220583/etagere/",
      "price": 29.95,
      "title": "Étagère",
      "locale": "fr-fr",
      "currency": "EUR",
      "image_url": "https://asset.action.com/image/upload/3220583_8718964261420-110_01_uoqzby",
      "product_id": "3220583"
    }
  ],
  "pagination": {
    "next": "https://www.action.com/fr-fr/search/?q=meuble&page=2#product-grid",
    "page": 1,
    "per_page": 24,
    "total_pages": 8,
    "total_results": 185
  }
}
```

## Documentation

## Overview
The **Action Search API** returns product listings from Action. Pass a **keyword** or a **full search URL**, optionally with **`region`**, and receive structured JSON with prices, images, locale, currency, and pagination.

Piloterr uses **browser rendering** and parses Action.com Next.js RSC payloads (`self.__next_f.push(...)`) with DOM / JSON-LD fallbacks.

Use each result `url` or `product_id` with [Action Product](https://www.piloterr.com/library/action-product) for full PDP data (specs, images, availability).

## Supported regions
`cs-cz`, `de-at`, `de-de`, `de-ch`, `es-es`, `fr-be`, `fr-fr`, `fr-lu`, `fr-ch`, `it-it`, `it-ch`, `nl-be`, `nl-nl`, `pl-pl`, `pt-pt`, `sk-sk`, `ro-ro`, `hr-hr`, `sl-si`

For multilingual countries, pass the full locale (`fr-be`, `nl-be`, `fr-ch`, `de-ch`, `it-ch`).

## Quickstart
```
GET https://api.piloterr.com/v2/action/search?query=meuble
GET https://api.piloterr.com/v2/action/search?query=meuble&region=fr-fr
GET https://api.piloterr.com/v2/action/search?query=https://www.action.com/fr-fr/search/?q=meuble&page=2
GET https://api.piloterr.com/v2/action/search?query=cabide&region=pt-pt
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Keyword or full Action search URL |
| `region` | string | no | Locale or country code (default: `fr-fr`) |
| `page` | integer | no | 1-based page number (default: 1) |
| `return_page_source` | boolean | no | Raw HTML as `{"result": "..."}` (default: `false`) |

## Input formats
| Format | Example |
|---|---|
| Keyword | `meuble` with `region=fr-fr` |
| Full URL | `https://www.action.com/fr-fr/search/?q=meuble` |
| Paginated URL | `https://www.action.com/fr-fr/search/?q=meuble&page=2` |

## Response: each listing (`results[]`)
| Field | Type | Description |
|---|---|---|
| `product_id` | string | Action article code |
| `title` | string | Product name |
| `url` | string | Absolute product URL |
| `image_url` | string | Main image |
| `price` | number | Current price (incl. tax) |
| `currency` | string | ISO currency code |
| `locale` | string | Locale used |

## Response: pagination
| Field | Type | Description |
|---|---|---|
| `page` | integer | Current page |
| `per_page` | integer | Results on this page |
| `total_results` | integer \| null | Total matches |
| `total_pages` | integer \| null | Total pages |
| `next` | string \| null | Next page URL |

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

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

## Notes
- Single-page searches may return `total_pages: 1` and `next: null`.
- Costs **2 credits** per call (browser rendering).

## Main use cases
- **Price monitoring**: track Action listings across European locales
- **Catalog discovery**: harvest `product_id` and URLs at scale
- **Cross-border retail intel**: compare availability and pricing by region