# Mobile Ad

## Overview

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

## Description

Mobile Ad API. Fetch full car listing data from a mobile.de ad URL or numeric id. Returns pricing, specs, images and features via webunlocker.

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

## Example Response

### Porsche Taycan 4S (455111824) on mobile.de FR

```json
{
  "url": "https://www.mobile.de/fr/voiture/d%C3%A9tails.html?id=455111824",
  "make": "Porsche",
  "ad_id": "455111824",
  "model": "Taycan",
  "power": "390 kW (530 ch)",
  "price": 80990,
  "title": "Porsche Taycan 4S",
  "locale": "fr",
  "mileage": "22.000 km",
  "category": "Berline",
  "currency": "EUR",
  "features": [
    "ABS",
    "Airbags"
  ],
  "fuel_type": "Électrique",
  "image_url": "https://img.classistatic.de/api/v1/mo-prod/images/jpg/normal/95/taycan_main.jpg",
  "transmission": "Automatique",
  "first_registration": "05/2021"
}
```

## Documentation

## Overview
The **Mobile Ad API** returns full car listing data from mobile.de. Pass an **ad URL** or **numeric ad id**, optionally with **`locale`**, and receive structured JSON with pricing, specs, images, ratings, and availability fields.

Piloterr fetches via **webunlocker** and parses Next.js RSC page-vip data (fallback: DOM `h1`, price, images).

Use [Mobile Search](https://www.piloterr.com/library/mobile-search) to discover listings, then [Mobile Ad](https://www.piloterr.com/library/mobile-ad) for the full record.

## Supported hosts
| Host | Notes |
|---|---|
| `www.mobile.de` | Primary host |
| `suchen.mobile.de` | Legacy German subdomain; canonicalized before fetch |

Region/locale is auto-detected from full ad URLs.

## Quickstart
```
GET https://api.piloterr.com/v2/mobile/ad?query=455111824&locale=fr
GET https://api.piloterr.com/v2/mobile/ad?query=https://www.mobile.de/fr/voiture/d%C3%A9tails.html?id=455111824
GET https://api.piloterr.com/v2/mobile/ad?query=https://www.mobile.de/es/veh%C3%ADculos/detalles.html?id=382789413
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Ad URL or numeric id |
| `locale` | string | no | Locale when `query` is id only (default: `fr`) |
| `return_page_source` | boolean | no | Raw HTML as `{\"result\": \"...\"}` (default: `false`) |

## Response fields
| Field | Type | Description |
|---|---|---|
| `ad_id` | string | Listing id |
| `title` | string | Listing title |
| `url` | string | Canonical ad URL |
| `locale` | string | Parsed locale |
| `make` | string \| null | Brand |
| `model` | string \| null | Model |
| `price` | number \| null | Current price |
| `currency` | string | ISO currency |
| `image_url` | string \| null | Main image |
| `images` | string[] \| null | Gallery URLs |
| `mileage` | string \| null | Formatted mileage |
| `first_registration` | string \| null | First registration |
| `fuel_type` | string \| null | Fuel label |
| `power` | string \| null | Power label |
| `transmission` | string \| null | Transmission label |
| `features` | string[] \| null | Equipment list |
| `category` | string \| null | Body/category label |
| `description` | string \| null | Long description (when exposed) |
| `rating` | number \| null | Average rating |
| `review_count` | integer \| null | Review count |
| `in_stock` | boolean \| null | Availability flag |

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

## Error codes
| Code | Meaning |
|---|---|
| `400` | Missing or invalid `query` / `locale` |
| `404` | Unparsable or missing ad page |
| `500` | Fetch or parsing error |

## Notes
- `description`, `seller` and `images[]` may be partial on some ads (RSC split across chunks).
- Numeric id alone builds a locale-specific details URL.
- Costs **3 credits** per call (webunlocker).

## Main use cases
- **PDP enrichment**: specs, features, gallery, price rating
- **Price monitoring**: track individual ad price changes
- **Lead gen**: structured vehicle data for automotive CRM workflows