# Mobile Search

## Overview

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

## Description

Mobile Search API. Search car listings by URL or make/model code across mobile.de locales. Returns prices and pagination via webunlocker and Next.js RSC 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/mobile/search' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Search Porsche (ms=20100) on mobile.de FR

```json
{
  "results": [
    {
      "url": "https://www.mobile.de/fr/voiture/d%C3%A9tails.html?id=455007337&s=Car&vc=Car",
      "make": "Porsche",
      "ad_id": "455007337",
      "model": "Cayman",
      "power": "265 kW (360 ch)",
      "price": 54990,
      "title": "Porsche Cayman S PDK",
      "locale": "fr",
      "mileage": "22.500 km",
      "currency": "EUR",
      "location": "München",
      "fuel_type": "Essence",
      "image_url": "https://img.classistatic.de/api/v1/mo-prod/images/jpg/normal/95/mt_mte247ax-wr.jpg",
      "price_rating": "GOOD_PRICE",
      "transmission": "Automatique",
      "first_registration": "03/2021",
      "price_rating_label": "Bon prix"
    }
  ],
  "pagination": {
    "next": null,
    "page": 1,
    "per_page": 50,
    "total_pages": null,
    "total_results": null
  }
}
```

## Documentation

## Overview
The **Mobile Search API** returns car listings from mobile.de across 10 locales. Pass a **search URL**, or a **make/model code** (`ms=`), optionally with **`locale`** and **`page`**, and receive structured JSON with prices and pagination.

Piloterr fetches pages via **webunlocker** and parses Next.js RSC (`searchResults.listings[]`).

Use each result `url` or `ad_id` with [Mobile Ad](https://www.piloterr.com/library/mobile-ad) for full listing data.

## Supported hosts
| Host | Notes |
|---|---|
| `www.mobile.de` | Primary host (URLs rebuilt in the current locale) |
| `suchen.mobile.de` | Legacy German subdomain; canonicalized to `www.mobile.de` before fetch |

Only the registered domain `mobile.de` is accepted. Other domains return `400`.

## Locales
Default: `fr`. Auto-detected from URL path when `query` is a full URL.

| Locale | Aliases | Search path (excerpt) |
|---|---|---|
| `de` | `de-de` | `/fahrzeuge/search.html` |
| `en` | `en-gb`, `en-us` | `/en/vehicles/search.html` |
| `es` | `es-es` | `/es/vehículos/buscar.html` |
| `fr` | `fr-fr` | `/fr/voiture/recherche.html` |
| `nl` | `nl-nl`, `nl-be` | `/nl/voertuigen/zoek.html` |
| `pl` | `pl-pl` | `/pl/pojazdy/szukaji.html` |
| `ro` | `ro-ro` | `/ro/vehicule/căutare.html` |
| `ru` | `ru-ru` | `/ru/транспортные-средства/поиск.html` |
| `cz` | `cs`, `cs-cz`, `cz-cz` | `/cz/vozidel/vyhledávání.html` |
| `tr` | `tr-tr` | `/tr/araçlar/arama.html` |

## URL formats
| Type | Pattern | Example |
|---|---|---|
| Search | `*/search?q=*` or locale search HTML | `https://www.mobile.de/fr/voiture/recherche.html?ms=20100` |
| Category listing | `*-{id}-g` | Category genart pages when supported |
| Product (use Ad API) | `details.html?id=` or `*-p` slug | Pass to [Mobile Ad](https://www.piloterr.com/library/mobile-ad) |

## Quickstart
```
GET https://api.piloterr.com/v2/mobile/search?query=20100&locale=fr
GET https://api.piloterr.com/v2/mobile/search?query=https://www.mobile.de/fr/voiture/recherche.html?ms=20100&s=Car&vc=Car
GET https://api.piloterr.com/v2/mobile/search?query=https://suchen.mobile.de/fahrzeuge/search.html?s=Car&vc=Car
GET https://api.piloterr.com/v2/mobile/search?query=https://www.mobile.de/fr/voiture/recherche.html?ms=20100&page=2
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Search URL or make/model code (`ms=`) |
| `locale` | string | no | Locale when `query` is a code (default: `fr`) |
| `page` | integer | no | 1-based page override (`pageNumber=`) |
| `return_page_source` | boolean | no | Raw HTML as `{\"result\": \"...\"}` (default: `false`) |

## Listings (`results[]`)
| Field | Type | Description |
|---|---|---|
| `ad_id` | string | Listing id |
| `title` | string | Listing title |
| `url` | string | Absolute ad URL in the current locale |
| `locale` | string | Parsed locale |
| `make` | string \| null | Brand |
| `model` | string \| null | Model |
| `price` | number \| null | Displayed price |
| `currency` | string | ISO currency |
| `image_url` | string \| null | Card image |
| `location` | string \| null | Seller location |
| `mileage` | string \| null | Formatted mileage |
| `first_registration` | string \| null | First registration (`MM/YYYY`) |
| `fuel_type` | string \| null | Fuel label |
| `power` | string \| null | Power label |
| `transmission` | string \| null | Transmission label |
| `price_rating` | string \| null | Rating code (e.g. `GOOD_PRICE`) |
| `price_rating_label` | string \| null | Localized rating label |

Optional fields: `description`, `images[]`, `features[]`, `segment`, `category`, `image_count`, `seller`.

## Pagination
| Field | Type | Description |
|---|---|---|
| `page` | integer | Current page |
| `per_page` | integer | Results on this page (~20-50) |
| `total_results` | integer \| null | Total hits when exposed |
| `total_pages` | integer \| null | Total pages when exposed |
| `next` | string \| null | Next page URL (`pageNumber=`); often `null` on Algolia keyword search |

## Mobile workflow
1. [Mobile Search](https://www.piloterr.com/library/mobile-search) to discover listings (this endpoint)
2. [Mobile Ad](https://www.piloterr.com/library/mobile-ad) for full ad JSON

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

## Notes
- Make/model code `20100` maps to Porsche; builds a default FR search URL with `s=Car&vc=Car`.
- Keyword search may return up to ~50 results with `pagination.next` often `null`.
- Costs **3 credits** per call (webunlocker).

## Main use cases
- **Inventory discovery**: harvest ad ids across makes, models and locales
- **Price monitoring**: track listing prices and `price_rating` labels
- **Marketplace intel**: compare search cards before fetching full ad data