# Otomoto — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Browse and retrieve vehicle listings from otomoto.pl, Poland's leading automotive marketplace. Search by make, model, and category, fetch full listing details and photos, or paginate through bulk results.

**Category:** Automotive | **Website:** [otomoto.pl/](https://otomoto.pl/) | **Docs:** [parse.bot/marketplace/e3d2b436-d4f5-4b61-b9ab-1f2a0ce58ee3/otomoto-pl-api](https://parse.bot/marketplace/e3d2b436-d4f5-4b61-b9ab-1f2a0ce58ee3/otomoto-pl-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-otomoto-pl-api-e3d2b436/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_all_listings_paginated

Scrape vehicle listings across multiple pages for a given search. Iterates through pages until max_pages is reached or no more results exist. Returns all collected listings in a single response. Useful for bulk collection but slower than single-page search_listings.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | No | Vehicle category slug. |
| `make` | string | No | Vehicle make slug (e.g., volkswagen, toyota, bmw). |
| `max_pages` | integer | No | Maximum number of pages to scrape (1-50). |
| `model` | string | No | Vehicle model slug (e.g., golf, corolla). Requires make to be set. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-otomoto-pl-api-e3d2b436/get_all_listings_paginated \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>","make":"<string>","max_pages":"<integer>","model":"<string>"}'
```

### get_categories

Get the fixed list of vehicle categories on otomoto.pl. Returns category slugs (used in URLs and as the category parameter) and their Polish display names. The list is stable and rarely changes.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-otomoto-pl-api-e3d2b436/get_categories \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_listing_detail

Retrieve full details for a specific vehicle listing by its URL. Returns a transformed advert object with stable fields: price, description, seller info, equipment categories, images, details, and main features. Volatile upstream fields (parametersDict) are excluded to keep the shape stable across listings.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | string | Yes | Full URL or path of the listing (e.g., https://www.otomoto.pl/osobowe/oferta/volkswagen-golf-ID6I6lAb.html). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-otomoto-pl-api-e3d2b436/get_listing_detail \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"<string>"}'
```

### get_listing_photos

Get all full-resolution photo URLs for a specific listing. Returns an array of direct image URLs extracted from the listing page. Performs the same page fetch as get_listing_detail but returns only the photo URLs.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | string | Yes | Full URL or path of the listing (e.g., https://www.otomoto.pl/osobowe/oferta/volkswagen-golf-ID6I6lAb.html). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-otomoto-pl-api-e3d2b436/get_listing_photos \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"<string>"}'
```

### search_listings

Search vehicle listings on otomoto.pl with optional make, model, and category filters. Returns a paginated page of listing summaries including price, location, and vehicle parameters. Each page contains up to 32 results. Use the page parameter to advance through results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | No | Vehicle category slug. |
| `make` | string | No | Vehicle make slug (e.g., volkswagen, toyota, bmw, aston-martin). |
| `model` | string | No | Vehicle model slug (e.g., golf, corolla, 3-series). Requires make to be set. |
| `page` | integer | No | Page number for pagination (1-based). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-otomoto-pl-api-e3d2b436/search_listings \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>","make":"<string>","model":"<string>","page":"<integer>"}'
```