# Finn — 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.

> Search and retrieve listings across Norwegian marketplaces on FINN.no, including vehicles, real estate, jobs, and second-hand items. Access structured listing data such as price, location, images, and category-specific attributes across all major FINN.no verticals.

**Category:** Marketplaces | **Website:** [finn.no/](https://finn.no/) | **Docs:** [parse.bot/marketplace/5105ca5c-f032-454a-b537-b6f574c0f85d/finn-no-api](https://parse.bot/marketplace/5105ca5c-f032-454a-b537-b6f574c0f85d/finn-no-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-finn-no-api-5105ca5c/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_listing_by_finnkode

Retrieve details of any listing by its FINN code. For mobility listings (cars, boats, motorcycles), attempts structured data from the search API. Falls back to HTML parsing with page title and advertising metadata for all listing types. Returns source indicator ('search_api' or 'html') to distinguish data quality.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `finnkode` | string | Yes | The unique FINN code for the listing (numeric string, e.g. '466534318') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-finn-no-api-5105ca5c/get_listing_by_finnkode \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"finnkode":"<string>"}'
```

### search_cars

Search for used and new car listings on FINN.no. Returns paginated results with vehicle metadata including make, model, mileage, price, year, and location. Without a query, returns all available car listings sorted by publication date.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number (1-indexed) |
| `query` | string | No | Search keyword (e.g. 'Tesla', 'BMW X5') |
| `rows` | integer | No | Number of results per page |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-finn-no-api-5105ca5c/search_cars \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","query":"<string>","rows":"<integer>"}'
```

### search_generic

Search within a specific mobility/vehicle category on FINN.no. Returns paginated results from the mobility search API. Supports cars, boats, motorcycles, campervans, caravans, and commercial vehicles. Without a query, returns all listings in the category.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | Yes | Vehicle category name or direct search ID |
| `page` | integer | No | Page number (1-indexed) |
| `query` | string | No | Search keyword |
| `rows` | integer | No | Results per page |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-finn-no-api-5105ca5c/search_generic \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>","page":"<integer>","query":"<string>","rows":"<integer>"}'
```

### search_real_estate

Search for real estate listings for sale on FINN.no. Returns paginated results parsed from the search page with property details including heading, prices, location, and area. Without a query, returns all available listings.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number (1-indexed) |
| `query` | string | No | Search keyword (e.g. 'Oslo', 'leilighet') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-finn-no-api-5105ca5c/search_real_estate \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","query":"<string>"}'
```

### search_torget

Search the general marketplace (Torget) for second-hand items. Returns paginated results with item details including price, location, brand, trade type, and images. Requires a search query.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number (1-indexed) |
| `query` | string | Yes | Search keyword (e.g. 'iphone 15', 'sofa') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-finn-no-api-5105ca5c/search_torget \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","query":"<string>"}'
```