# Current Public Car Listings (`thescrapelab/current-car-listings`) Actor

Collect supported public vehicle listings across cataloged countries and produce source-linked current listing observations. No external listing database or source APIs.

- **URL**: https://apify.com/thescrapelab/current-car-listings.md
- **Developed by:** [Inus Grobler](https://apify.com/thescrapelab) (community)
- **Categories:** E-commerce, Automation, Developer tools
- **Stats:** 2 total users, 1 monthly users, 90.5% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$0.10 / 1,000 current car listings

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Current Public Car Listings

Collect current public listings with observed prices and source links. Select public page URLs, countries or cataloged sources, or supply records you already have. Results describe the collected sample, with explicit coverage and missing values.

### Quick start and input

The public example below requests one observed listing. Clear Your records (JSON) to \[] before using public collection.

```json
{
  "pageUrls": [
    "https://www.finn.no/car/used/search.html"
  ],
  "max_results": 1,
  "maxPublicPages": 3,
  "maxObservations": 1
}
```

Explicit pageUrls and supplied observations take precedence over legacy country/source defaults. Use pageUrls for specific public listing/search pages, or countries with websites/sources to choose cataloged discovery routes. maxPublicPages is a single request allowance across all selected countries, including redirects. maxObservations bounds the collected comparison sample. No external listing database or source API is used. A blocked or unsupported source creates a coverage error, never substitute listings.

Legacy providedRecords or providedDatasetId still clean supplied exports. Their analysis is in EVIDENCE_ANALYSIS, with sourceVerified=false. Use one data source at a time.

### Output example

Representative fields from a reviewed public-page sample. Current listings and prices can change.

```json
{
  "url": "https://www.finn.no/mobility/item/476900113",
  "title": "BMW 225xe",
  "price": 119900,
  "currency_code": "NOK",
  "source": "finnno",
  "country_code": "NO",
  "observed_at": "2026-10-25T18:10:34.237176+00:00",
  "dataInputSource": "web",
  "sourceVerified": true,
  "collectionEvidence": {
    "method": "public_html",
    "pageUrl": "https://www.finn.no/car/used/search.html",
    "observedFields": [
      "title",
      "url",
      "price"
    ]
  },
  "brand": "BMW",
  "model": "225xe",
  "last_seen_at": "2026-10-25T18:10:34.237176+00:00"
}
```

PUBLIC_COLLECTION_SUMMARY reports observed records, requests, source errors, comparison coverage and confirmed delivered results. BASELINE_OBSERVATIONS contains the actual observations used. Source country metadata describes the cataloged source; incomplete samples are not national market statistics. Asking prices are not transaction prices. Currencies and sale/rental markets are compared separately.

### Observations and history

The first collection establishes a baseline. It cannot reconstruct earlier prices. Reuse historyName with the same source selection for later comparisons. Baseline-only price-change/report runs save their observations without a paid result row. A source missing from a partial run does not establish removal. Uncertain dataset writes stop without blind replay or advancing the observation history.

Current listings are delivered at the existing result price. Their observation time is distinct from a source publication date.

### Country and source coverage

The source catalog spans 73 countries across both listing categories. For cars, 18 sources in 14 countries currently have bounded HTTP-fixture extraction evidence: AU, CA, DE, GB, IN, LK, NL, NO, PK, RS, SE, SK, US, ZA. This is a sampled page check, not complete pagination or cloud-access proof for every source. Other catalog entries are candidates and can be blocked, API-only or unverified. Run summaries show actual coverage; selecting a country is not a guarantee of results. No fixed South Africa-only restriction is imposed.

### Pricing and limits

Check Pricing and set a spending cap. Confirmed delivered records use the existing result event. Supplied export analysis adds no separate analysis event. Baseline-only/failed collection creates no synthetic paid result. Start fees and normal platform/storage costs may still apply. Keep page and result limits small.

### Python API example

```python
import os
from apify_client import ApifyClient
client = ApifyClient(os.environ['APIFY_TOKEN'])
run = client.actor('thescrapelab/current-car-listings').call(run_input={
  "pageUrls": [
    "https://www.finn.no/car/used/search.html"
  ],
  "max_results": 1,
  "maxPublicPages": 3,
  "maxObservations": 1
})
if run is None:
    raise RuntimeError('Actor did not return run metadata')
dataset_id = run['defaultDatasetId'] if isinstance(run, dict) else run.default_dataset_id
for record in client.dataset(dataset_id).iterate_items():
    print(record)
```

### Support and limitations

Open Issues with a run ID and a sanitized example. Public pages may block requests or change layout. Supplied snapshots remain customer assertions. The Actor does not establish complete historical inventory, national trends, removals from partial coverage, or market-wide price estimates.

# Actor input Schema

## `pageUrls` (type: `array`):

Optional public pages from cataloged sources. Clear supplied records to \[] when collecting pages. Use URLs, source selections or countries; one global page budget applies.

## `countries` (type: `array`):

Choose countries for public source discovery. Clear the list to consider all cataloged countries. Explicit page URLs take precedence.

## `sources` (type: `array`):

Optional cataloged sources for public discovery. Explicit page URLs take precedence.

## `providedRecords` (type: `array`):

Paste records you have permission to process. These are normalized, validated and deduplicated without fetching their original websites. Use this OR a supplied dataset ID. Invalid web URLs, non-finite values and negative prices or counts are rejected. Unknown values remain unknown.

## `providedDatasetId` (type: `string`):

Optional 17-character ID of a dataset you can access. Clear the JSON records to \[] when using a dataset. Only a bounded number of records is read.

## `max_results` (type: `integer`):

Maximum listings in this run, from 1 to 500.

## `seen_days` (type: `integer`):

Inactive in this product workflow. Retained for existing API clients; it does not enable collection, source APIs or filtering of supplied records.

## `continuation_token` (type: `string`):

Inactive in this product workflow. Retained for existing API clients; it does not enable collection, source APIs or filtering of supplied records.

## `require_results` (type: `boolean`):

Inactive for supplied-data processing. Retained for existing API clients. For monitoring: fail when valid filters return no records. Empty searches are normally allowed.

## `maxPublicPages` (type: `integer`):

Global HTTP request allowance across all selected countries and sources, including redirects.

## `maxObservations` (type: `integer`):

Bound the observations collected or read for this run. Zero performs no collection.

## `historyName` (type: `string`):

Optional stable history for this exact selection. The first run creates an observed baseline; older prices are not reconstructed.

## Actor input object example

```json
{
  "pageUrls": [
    "https://www.finn.no/car/used/search.html"
  ],
  "countries": [
    "ZA"
  ],
  "providedRecords": [],
  "max_results": 5,
  "seen_days": 7,
  "require_results": false,
  "maxPublicPages": 3,
  "maxObservations": 5
}
```

# Actor output Schema

## `listings` (type: `string`):

No description

## `runSummary` (type: `string`):

No description

## `providedDataSummary` (type: `string`):

No description

## `publicCollectionSummary` (type: `string`):

No description

## `baselineObservations` (type: `string`):

No description

## `evidenceAnalysis` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "pageUrls": [
        "https://www.finn.no/car/used/search.html"
    ],
    "countries": [
        "ZA"
    ],
    "providedRecords": [],
    "max_results": 5
};

// Run the Actor and wait for it to finish
const run = await client.actor("thescrapelab/current-car-listings").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "pageUrls": ["https://www.finn.no/car/used/search.html"],
    "countries": ["ZA"],
    "providedRecords": [],
    "max_results": 5,
}

# Run the Actor and wait for it to finish
run = client.actor("thescrapelab/current-car-listings").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "pageUrls": [
    "https://www.finn.no/car/used/search.html"
  ],
  "countries": [
    "ZA"
  ],
  "providedRecords": [],
  "max_results": 5
}' |
apify call thescrapelab/current-car-listings --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,thescrapelab/current-car-listings"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/ZbjTDuQ8YSNkvAlcg/builds/ZHTzCW68U3ZmkJ3eM/openapi.json