# Oscaro Search

## Overview

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

## Description

Oscaro Search API. Search auto parts by keyword, search URL or category listing on oscaro.com, oscaro.es and oscaro.pt. Returns prices 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/oscaro/search' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Search 'moteur ai' on oscaro.com (page 1)

```json
{
  "results": [
    {
      "url": "https://www.oscaro.com/moteur-electrique-pulseur-dair-habitacle-magneti-marelli-069412247010-13361124-793-p",
      "price": 91.79,
      "title": "Moteur électrique, pulseur d'air habitacle MAGNETI MARELLI - 069412247010",
      "currency": "EUR",
      "image_url": "https://oscaro.media/catalog/images/jpg/normal/95/mt_mte247ax-wr.jpg",
      "product_id": "13361124-793"
    },
    {
      "url": "https://www.oscaro.com/moteur-electrique-pulseur-dair-habitacle-magneti-marelli-069412215010-13485530-793-p",
      "price": 47.6,
      "title": "Moteur électrique, pulseur d'air habitacle MAGNETI MARELLI - 069412215010",
      "currency": "EUR",
      "image_url": "https://oscaro.media/catalog/images/jpg/normal/95/mt_mte215ax_wr.jpg",
      "product_id": "13485530-793"
    }
  ],
  "pagination": {
    "next": null,
    "page": 1,
    "per_page": 50,
    "total_pages": null,
    "total_results": null
  }
}
```

## Documentation

## Overview
The **Oscaro Search API** returns auto parts listings from Oscaro shops (com, es, pt). Pass a **keyword**, a **search URL**, or a **category listing URL** (`*-{id}-g`), optionally with **`region`** and **`page`**, and receive structured JSON with prices and pagination.

Piloterr uses **browser rendering** and waits for `article.productbox` tiles before parsing the DOM.

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

## Supported regions
Default: `com` (France via www.oscaro.com).

| `region` | Domain | Search path | Currency | Aliases |
|---|---|---|---|---|
| `com` | oscaro.com | `/fr/search?q=...` | EUR | `fr` |
| `es` | oscaro.es | `/es/search?q=...` | EUR | |
| `pt` | oscaro.pt | `/pt/search?q=...` | EUR | |

When `query` is a full Oscaro URL, region is detected from the TLD (`region` is ignored).

## URL formats
| Type | Pattern | Example |
|---|---|---|
| Search | `*/search?q=*` | `https://www.oscaro.com/fr/search?q=moteur+ai` |
| Category listing | `*-{id}-g` | `https://www.oscaro.com/huile-moteur-1862-g` |
| Product (use Product API) | `*-{sku}-p` | `https://www.oscaro.es/filtro-de-aceite-purflux-l343d-13644654-7-p` |

## Quickstart
```
GET https://api.piloterr.com/v2/oscaro/search?query=moteur+ai
GET https://api.piloterr.com/v2/oscaro/search?query=moteur+ai&region=com
GET https://api.piloterr.com/v2/oscaro/search?query=https://www.oscaro.com/fr/search?q=moteur+ai
GET https://api.piloterr.com/v2/oscaro/search?query=https://www.oscaro.com/huile-moteur-1862-g&page=2
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Keyword, search URL, or category listing URL |
| `region` | string | no | Shop when `query` is a keyword (default: `com`) |
| `page` | integer | no | 1-based page override for category listings |
| `return_page_source` | boolean | no | Raw HTML as `{\"result\": \"...\"}` (default: `false`) |

## Listings (`results[]`)
| Field | Type | Description |
|---|---|---|
| `product_id` | string | Slug id from product URL (e.g. `13361124-793`) |
| `title` | string | Product title |
| `url` | string | Absolute product URL (`-p` suffix) |
| `image_url` | string \| null | Card image |
| `price` | number \| null | Displayed price |
| `currency` | string | ISO currency from shop config |

## Pagination
| Field | Type | Description |
|---|---|---|
| `page` | integer | Current page |
| `per_page` | integer | Results on this page (up to ~50 on keyword search) |
| `total_results` | integer \| null | Often `null` |
| `total_pages` | integer \| null | Set on category listings |
| `next` | string \| null | Next page URL (`?page=2` on listings; often `null` on keyword search) |

Lazy-load placeholder tiles (`.product-placeholder`) are skipped.

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

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

## Notes
- Category listings paginate with query param **`page`**.
- Keyword search (Algolia) returns up to ~50 results per page; `pagination.next` is often `null`.
- Costs **2 credits** per call (browser rendering).

## Main use cases
- **Parts discovery**: harvest product ids across keywords and categories
- **Price monitoring**: track listing prices on search and category pages
- **Catalog crawl**: walk category pagination via `pagination.next`