# Mascus Search

## Overview

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

## Description

Search used equipment listings on Mascus from a category URL, with pagination that keeps country and category filters.

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

## Example Response

### Belgian excavators (page 1)

```json
{
  "results": [
    {
      "url": "https://www.mascus.be/bouw/minigraafmachines---7t/airman-ax10u-7-ax10u-7/ff3ch5ch.html",
      "brand": "Airman",
      "model": "AX10U-7",
      "image_url": "https://dnge9sb91helb.cloudfront.net/image/product/medium/example.jpg",
      "rental_ad": false,
      "auction_ad": false,
      "price_euro": 0,
      "product_id": "{example}",
      "catalog_name": "construction",
      "company_name": "Example Dealer",
      "category_name": "miniexcavators",
      "location_city": "Oostrozebeke",
      "user_currency": "EUR",
      "year_of_manufacture": 2020,
      "location_country_code": "BE",
      "price_in_user_currency": 0
    }
  ],
  "pagination": {
    "next": 2,
    "current": 1,
    "page_size": 40,
    "total_pages": 14,
    "has_next_page": true,
    "total_results": 547
  }
}
```

## Documentation

## Overview
The **Mascus Search** endpoint returns used equipment listings from a Mascus category URL: brand, model, year, price, location, seller and image.

Pass a full Mascus browse or search URL. Use `page` (or `?page=` in the URL) to paginate, about 40 results per page. Category and country filters from the URL are kept on every page.

Costs **1 credit** per call.

## Quickstart
```
GET https://api.piloterr.com/v2/mascus/search?query=https://www.mascus.be/bouw/graafmachines/be,country.html
GET https://api.piloterr.com/v2/mascus/search?query=https://www.mascus.be/bouw/graafmachines/be,country.html&page=2
GET https://api.piloterr.com/v2/mascus/search?query=https://www.mascus.nl/bouw/graafmachines/nl,country.html&page=2
GET https://api.piloterr.com/v2/mascus/search?query=https://www.mascus.de/baumaschinen/bagger/de,country.html&page=2
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Full Mascus category/search URL |
| `page` | integer | no | Page number (default `1`, ~40 results per page) |

## Recommended URL shapes
| Shape | Example | Notes |
|---|---|---|
| Classic country browse | `https://www.mascus.be/bouw/graafmachines/be,country.html` | Best for harvests; `page` / `?page=` keep filters |
| Filter search path | `https://www.mascus.be/+/catalogs=construction&categories=excavators&countries=BE/2,relevance,search.html` | Page is in the path (`/2,relevance,search.html`) |

## Response fields
| Field | Type | Description |
|---|---|---|
| `results` | array | Listings on the page |
| `results[].product_id` | string | Listing id |
| `results[].brand` / `model` | string | Machine brand and model |
| `results[].year_of_manufacture` | integer | Year |
| `results[].price_euro` / `price_in_user_currency` | number | Price (`0` often means on request) |
| `results[].location_city` / `location_country_code` | string | Location |
| `results[].company_name` | string | Seller |
| `results[].url` | string | Listing URL (use with [Mascus Ad](https://www.piloterr.com/library/mascus-ad)) |
| `results[].image_url` | string | Main image |
| `pagination` | object | `current`, `page_size`, `total_pages`, `has_next_page`, `total_results`, `next` |

## Error codes
| Code | Meaning |
|---|---|
| `400` | Missing `query` or invalid Mascus domain |
| `404` | Page not found |
| `500` | Temporary failure |

## Notes
- Prefer classic `…/{country},country.html` URLs for stable pagination
- `page=2` and `query=…?page=2` both work
- On a filtered URL, `total_results` stays in the filtered set (not the site-wide catalog)

## Related endpoints
- [Mascus Ad](https://www.piloterr.com/library/mascus-ad): full listing details from a result URL