# Oscaro Product

## Overview

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

## Description

Oscaro Product API. Fetch full auto parts product data from an Oscaro product URL. Returns pricing, brand, reference, images and availability via browser rendering and JSON-LD parsing.

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

## Example Response

### MOTUL SPECIFIC 0720 5W-30 (15213891) on oscaro.com

```json
{
  "url": "https://www.oscaro.com/huile-moteur-motul-102208-15213891-1862-p",
  "brand": "MOTUL",
  "price": 13.28,
  "title": "MOTUL - SPECIFIC 0720 5W-30  1L - ref. 102208 - Huile moteur",
  "images": [
    "https://oscaro.media/catalog/images/oscjpg/normal/1114/specific 0720 5w30 1l.jpg"
  ],
  "currency": "EUR",
  "in_stock": true,
  "image_url": "https://oscaro.media/catalog/images/oscjpg/normal/1114/specific 0720 5w30 1l.jpg",
  "reference": "102208",
  "product_id": "15213891"
}
```

## Documentation

## Overview
The **Oscaro Product API** returns full product page data from Oscaro shops. Pass a **product URL** (`*-{sku}-p`) and receive structured JSON with pricing, brand, reference, images, ratings, and availability.

Piloterr uses **browser rendering**, waits for `.price`, then parses JSON-LD `@type: Product` (fallback: DOM `h1` + `.price` + id from URL).

Use [Oscaro Search](https://www.piloterr.com/library/oscaro-search) to discover listings, then [Oscaro Product](https://www.piloterr.com/library/oscaro-product) for the full record.

## Supported regions
Region is auto-detected from the product URL TLD (`oscaro.com`, `oscaro.es`, `oscaro.pt`).

| Domain | Currency |
|---|---|
| oscaro.com | EUR |
| oscaro.es | EUR |
| oscaro.pt | EUR |

## Quickstart
```
GET https://api.piloterr.com/v2/oscaro/product?query=https://www.oscaro.com/huile-moteur-motul-102208-15213891-1862-p
GET https://api.piloterr.com/v2/oscaro/product?query=https://www.oscaro.es/filtro-de-aceite-purflux-l343d-13644654-7-p
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Product page URL (`-p` suffix) |
| `return_page_source` | boolean | no | Raw HTML as `{\"result\": \"...\"}` (default: `false`) |

## Response fields
| Field | Type | Description |
|---|---|---|
| `product_id` | string | SKU from JSON-LD (`sku`) |
| `title` | string | Product name |
| `url` | string | Canonical product URL |
| `price` | number \| null | Current price |
| `currency` | string | ISO currency |
| `brand` | string \| null | Brand name |
| `reference` | string \| null | Manufacturer part number (`mpn`) |
| `image_url` | string \| null | Main image |
| `images` | string[] \| null | Image gallery |
| `description` | string \| null | Long description (when exposed) |
| `rating` | number \| null | Average rating |
| `review_count` | integer \| null | Review count |
| `in_stock` | boolean \| null | Online availability |

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

## Error codes
| Code | Meaning |
|---|---|
| `400` | Missing or invalid `query` |
| `404` | Unparsable or missing product page |
| `500` | Rendering or parsing error |

## Notes
- Product URLs end with `-p` (e.g. `15213891-1862-p`).
- Costs **2 credits** per call (browser rendering).

## Main use cases
- **PDP enrichment**: brand, reference, gallery, ratings
- **Price monitoring**: track part prices across Oscaro shops
- **Stock checks**: `in_stock` from JSON-LD availability