# Point.P Search

## Overview

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

## Description

Point.P Search API: search by keyword or URL and get building-material listings with prices, brands, ratings, units, and pagination as JSON 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/pointp/search' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Search 'colle' on pointp.fr (page 1)

```json
{
  "results": [
    {
      "unit": "Sac-sachet",
      "brand": "ULTIBAT",
      "price": 37.82,
      "title": "Colle Flex polyvalente - C2S1 ET/G - gris - sac de 25 kg",
      "rating": 5,
      "currency": "EUR",
      "image_url": "https://www.pointp.fr/asset/29/81/AST2272981-M.jpg",
      "reference": "7147449",
      "product_id": "A7147449",
      "listing_url": "https://www.pointp.fr/p/decoration-interieure/mortier-colle-flex-polyvalent-ultibat-c2s1-et-g-25kg-gris-A7147449",
      "review_count": 3
    },
    {
      "unit": "Sac-sachet",
      "brand": "WEBER",
      "price": 41.74,
      "title": "Colle pour carrelage webercol flex enaé - gris - sac de 25 kg",
      "rating": 5,
      "currency": "EUR",
      "image_url": "https://www.pointp.fr/asset/46/89/AST17024689-M.jpg",
      "reference": "3596886",
      "product_id": "A3596886",
      "listing_url": "https://www.pointp.fr/p/decoration-interieure/mortier-colle-deformable-non-irritant-pour-carrelage-weber-col-A3596886",
      "review_count": 1
    },
    {
      "unit": "Pièce",
      "brand": "WEBER",
      "price": 29.24,
      "title": "Mortier-colle webercol grès pour tous carreaux - blanc - sac de 25 kg",
      "rating": 5,
      "currency": "EUR",
      "image_url": "https://www.pointp.fr/asset/44/78/AST17024478-M.jpg",
      "reference": "3900577",
      "product_id": "A3900577",
      "listing_url": "https://www.pointp.fr/p/decoration-interieure/mortier-colle-a-adherence-amelioree-pour-carrelage-c2-weber-col-A3900577",
      "review_count": 1
    }
  ],
  "pagination": {
    "next": "https://www.pointp.fr/search/page-2?q=colle",
    "page": 1,
    "per_page": 24,
    "total_pages": 49,
    "total_results": 1165
  }
}
```

## Documentation

## Overview
The **Point.P Search API** returns product listings from [Point.P](https://www.pointp.fr) search result pages. Pass a **keyword** (e.g. `colle`) or a **full search URL** and receive structured JSON with titles, prices, brands, ratings, units, and pagination.

Point.P pages are protected and JavaScript-heavy. Piloterr uses **browser rendering** to load the page and extract listing cards.

Use each result's `listing_url` with **Point.P Product** for full PDP details (description, EAN, specifications, breadcrumbs).

## Quickstart
```
GET https://api.piloterr.com/v2/pointp/search?query=colle
```

Paginate with the optional `page` parameter or pass `pagination.next`:
```
GET https://api.piloterr.com/v2/pointp/search?query=colle&page=2
GET https://api.piloterr.com/v2/pointp/search?query=https://www.pointp.fr/search/page-2?q=colle
```

Via POST:
```
POST https://api.piloterr.com/v2/pointp/search
Content-Type: application/json

{"query": "colle", "page": 1, "return_page_source": false}
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Search keyword or full Point.P search URL |
| `page` | integer | no | 1-based page number. Overrides the page inferred from the URL |
| `return_page_source` | boolean | no | Return raw HTML as `{"result": "..."}` (default: `false`) |

## Input formats
| Format | Example |
|---|---|
| Keyword | `colle` → `https://www.pointp.fr/search?q=colle` |
| Search URL | `https://www.pointp.fr/search?q=colle` |
| Paginated URL | `https://www.pointp.fr/search/page-2?q=colle` |

Accepted paths: `/search`, `/search/page-{n}` with query param `q`.

## Response: each listing (`results[]`)
| Field | Type | Always present | Description |
|---|---|---|---|
| `product_id` | string | yes | Point.P ID with `A` prefix (e.g. `A7147449`) |
| `reference` | string | no | Display reference shown on the card (≠ `product_id`) |
| `title` | string | yes | Product title |
| `listing_url` | string | yes | Absolute URL `/p/...-A{id}` |
| `image_url` | string | no | Thumbnail URL |
| `brand` | string | no | Brand name |
| `price` | number | no | Sale price; `null` when shown as agency-dependent |
| `currency` | string | no | ISO 4217 code (`EUR`) when `price` is set |
| `rating` | number | no | Star rating out of 5, 1 decimal |
| `review_count` | integer | no | Number of reviews |
| `unit` | string | no | Sales unit (e.g. `Sac-sachet`, `m²`) |

## Response: pagination
| Field | Type | Description |
|---|---|---|
| `page` | integer | Current page |
| `per_page` | integer | Listings on this page (typically `24`) |
| `total_results` | integer | Total products matching the query |
| `total_pages` | integer | Total pages available |
| `next` | string \| null | Full URL of the next page; `null` on the last page |

To paginate, call `pagination.next` or pass `page=N`.

## Workflow
1. **Search**: discover listings by keyword or search URL (this endpoint)
2. **Product**: fetch full PDP JSON from any `listing_url`

## Error codes
| Code | Meaning |
|---|---|
| `400` | Missing or invalid `query` |
| `404` | Resource not found or not parseable |
| `500` | Rendering or parsing error |

## Notes
- `product_id` (URL suffix) and `reference` (display ref) are distinct identifiers.
- Currency codes are normalized to ISO 4217 (`EUR`, not `€`).
- Costs **2 credits** per call (browser rendering).

## Main use cases
- **Building-materials repricing**: monitor Point.P prices by keyword
- **Catalog discovery**: harvest `product_id` and `listing_url` at scale
- **Search rank tracking**: track listing visibility across pages
- **Product enrichment**: chain Search → Product for EAN and specifications