# Car Listings API (`truefetch/car-listings-api`) Actor

Search vehicle listings across 52 country-aware marketplaces, classifieds, dealer inventories, and auction sources. Export 35 normalized fields for prices, mileage, VINs, sellers, images, and source URLs.

- **URL**: https://apify.com/truefetch/car-listings-api.md
- **Developed by:** [TrueFetch](https://apify.com/truefetch) (community)
- **Categories:** E-commerce, Integrations, Automation
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.48 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

> **Affiliate disclosure:** Apify Store links in this README use the `fpr=aiagentapi` referral parameter, which may attribute a signup or purchase without changing your price.

**Global Car Listing is a multi-market vehicle listings API that searches 52 country-aware marketplaces across 28 countries and regions, then returns one normalized 35-field dataset for automotive research and inventory workflows.**

- **52 verified source routes** cover marketplaces, classifieds, dealer inventories, and auction listings.
- **28 selectable countries and regions** determine which vehicle sources are eligible for a run.
- **Five public inputs** keep country, keyword, platform, location, and result limits explicit.
- **35 documented output fields** preserve prices, mileage, specifications, sellers, images, and source links.

[**Run a one-result test**](https://apify.com/truefetch/global-car-listing?fpr=aiagentapi) · [**View API**](https://apify.com/truefetch/global-car-listing/api?fpr=aiagentapi)

The smallest useful test sets `max_results` to `1`; on the FREE tier, one published result plus Actor Start costs at most $0.02250 before any platform-level adjustments.

### What does Global Car Listing do?

Global Car Listing accepts a country, a vehicle keyword, and a per-platform result limit. It selects compatible sources for that country, optionally narrows the run to named platforms or a source-supported location, and publishes comparable vehicle records to the default Apify Dataset. The normalized fields cover listing identity, price, mileage, vehicle specifications, seller information, images, dates, and traceable source URLs.

The Actor is intended for public vehicle-listing research. It is not a vehicle-history report, appraisal service, private dealer database, financing service, or guarantee that every marketplace exposes the same details. Source-specific values can be empty, and the record reflects the listing information available when the run was performed. The Actor is not affiliated with the marketplaces named in its input options.

### How do I run Global Car Listing?

1. Open the [Global Car Listing input page](https://apify.com/truefetch/global-car-listing?fpr=aiagentapi) and choose a supported `country`.
2. Enter a source-compatible vehicle phrase in `keyword`, such as `Toyota Camry`.
3. Set `max_results` to `1` for the first test. Optionally choose one or more `platforms` and add a source-supported `location`.
4. Start the run, then open the default Dataset and verify the returned `source_url` before increasing the result limit.

Use this smallest shared scenario for the examples in this README:

```json
{
  "country": "United States",
  "keyword": "Toyota Camry",
  "platforms": ["CarGurus"],
  "location": "10001",
  "max_results": 1
}
```

`max_results` applies per selected platform, not to the entire multi-platform run. If three compatible platforms are selected with `max_results` set to `10`, the run may publish up to 30 results. Actual output can be lower because availability and field coverage depend on each source.

### What data does Global Car Listing return?

Global Car Listing publishes one object per vehicle listing. Every record uses the same 35-field contract, while fields that are unavailable at the source may be empty.

| Field group | Public fields | What they represent |
| --- | --- | --- |
| Identity and media | `main_image`, `title`, `images`, `listing_id`, `vin` | Listing identity, vehicle media, and source identifiers. |
| Price and vehicle | `price`, `currency`, `price_text`, `year`, `make`, `model`, `trim`, `condition` | Asking-price and core vehicle identity values. |
| Specifications | `mileage`, `mileage_unit`, `body_type`, `fuel`, `transmission`, `engine`, `drive_type`, `exterior_color`, `interior_color` | Source-published odometer and specification details. |
| Seller and place | `seller`, `seller_type`, `location`, `country` | Public seller classification and listing geography. |
| Source and timing | `platform`, `source_url`, `platform_url`, `official_url`, `posted_at`, `updated_at`, `processed_at` | Source traceability and timestamps. |
| Content and attribution | `description`, `processor` | Listing text and Actor attribution. |

The following abbreviated item is illustrative and uses the same Toyota Camry scenario:

```json
{
  "main_image": "https://example.com/vehicle-images/toyota-camry.jpg",
  "title": "2021 Toyota Camry XLE",
  "price": 24500,
  "currency": "USD",
  "year": 2021,
  "make": "Toyota",
  "model": "Camry",
  "mileage": 58200,
  "mileage_unit": "mi",
  "location": "New York, NY",
  "platform": "CarGurus",
  "source_url": "https://www.cargurus.com/Cars/link/000000000",
  "seller_type": "dealer",
  "images": ["https://example.com/vehicle-images/toyota-camry.jpg"],
  "processor": "https://apify.com/username/actor_name",
  "processed_at": "2026-07-21T12:00:00Z"
}
```

Apify Datasets can be exported as JSON, JSONL, CSV, Excel, XML, HTML, or RSS, subject to the current [Dataset API](https://docs.apify.com/api/v2/dataset-items-get) options.

### What inputs can I configure?

| Input | Type | Required | Rules and effect |
| --- | --- | --- | --- |
| `country` | string | Yes | One of 28 schema values. It selects country-compatible platforms and proxy geography. |
| `keyword` | string | Yes | A non-empty vehicle phrase. It is trimmed but not translated or replaced. Some sources require a make/model-style phrase and reject a leading year. |
| `platforms` | array of strings | No | An optional allowlist of the 52 public labels. Empty means all sources compatible with the country and location. |
| `location` | string | No | Optional city, region, postcode, ZIP code, or local area. A supplied value must be usable by at least one selected source. |
| `max_results` | integer | Yes | From 1 to 10,000, applied independently to each selected platform. |

Only `country`, `keyword`, and `max_results` are required. The optional filters have no non-empty default, so omitting them does not silently impose a location or platform restriction.

### What platforms and markets does Global Car Listing cover?

The public country enum contains Australia, Brazil, Canada, Egypt, France, Germany, Greece, Hong Kong, India, Indonesia, Italy, Mainland China, Malaysia, Moldova, Morocco, Netherlands, Pakistan, Philippines, Poland, Portugal, Russia, Singapore, Spain, Turkey, Ukraine, United Kingdom, United States, and Vietnam.

The 52 public platform labels are 28car, 999.md, Arabam, Auto.it, Auto.ru, Autohome, Automobile.it, AutoScout24, AutoTrader.ca, Auto Trader UK, Autotrader US, Avito Morocco, Avito Russia, car.gr, CarDekho, CARFAX, CarGurus, Carlist.my, CarMax, Carmudi Philippines, Cars.com, CARS24, carsales, CarsGuide, Carvana, CarWale, Cho Tot, Coches.net, Copart, Craigslist Cars & Trucks, Dongchedi, Drom.ru, Dubizzle Egypt, eBay Motors, Edmunds, IAA, Kelley Blue Book, La Centrale, Leboncoin, Marktplaats, mobile.de, Motorist.sg, OLX Pakistan, OLX Poland, OLX Ukraine, Oto, Otomoto, sgCarMart, Standvirtual, Subito, TrueCar, and Webmotors.

Coverage is country-aware, not a promise that every source works in every country. Location behavior is also source-dependent: some sources accept raw areas, some require a resolved postal code, and others do not accept a location filter. Incompatible combinations are rejected or skipped rather than relabeled as location-filtered results.

### Why use Global Car Listing?

| Verified capability | Practical benefit |
| --- | --- |
| Country-aware routing across 52 sources | Compare relevant marketplaces without maintaining 52 separate input contracts. |
| One 35-field Dataset schema | Load records into a spreadsheet, database, BI model, or review queue with stable column names. |
| Optional platform and location controls | Start broad, then narrow a run only when the selected source supports that restriction. |
| Publishable records require a usable listing URL | Review the original listing before using a record in a pricing or inventory decision. |
| Per-result billing | Tie most of the Actor cost to records written to the default Dataset. |

The main trade-off is normalization versus source completeness. A shared schema makes cross-market comparison easier, but no marketplace is required to expose every optional field. Users who need one platform's full proprietary field set should choose a focused Actor for that market.

### Who is Global Car Listing for?

Global Car Listing is designed for developers, automotive data teams, market researchers, dealer analysts, procurement teams, and operations specialists who need comparable public listing records across several markets. Typical uses include asking-price studies, inventory sampling, dealer landscape research, auction discovery, regional availability checks, and repeatable data exports for internal dashboards.

It can also support analysts who begin in Excel and later automate the same input through the Apify API or a scheduled run. The Actor is not the right fit for users seeking private owner data, guaranteed VIN history, appraisal values, financing decisions, or a real-time inventory guarantee. It should not be used as the sole evidence for a purchase, compliance, lending, or safety decision.

### How can I use Global Car Listing through the API or MCP?

The canonical owner/name identifier derived from this release is `truefetch/global-car-listing`. The public Store API did not return a current record for that identifier on July 21, 2026, so a numeric Actor ID and live usage proof are intentionally omitted. Verify publication before using the Actor-specific endpoints below.

The current Apify API accepts an Actor ID or a tilde-separated owner and Actor name. This synchronous example uses the same one-result scenario and sends the API token in the recommended authorization header:

```bash
curl -L "https://api.apify.com/v2/actors/truefetch~global-car-listing/run-sync-get-dataset-items?maxItems=1" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <APIFY_TOKEN>" \
  -d '{
    "country": "United States",
    "keyword": "Toyota Camry",
    "platforms": ["CarGurus"],
    "location": "10001",
    "max_results": 1
  }'
```

See the official [synchronous Actor run endpoint](https://docs.apify.com/api/v2/act-run-sync-get-dataset-items-post) for timeout, output, and charge-limiting parameters.

For MCP clients, Apify currently recommends the hosted Streamable HTTP server. This configuration is valid JSON and uses OAuth when the client supports it:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=actors,docs"
    }
  }
}
```

After publication, ask the MCP client to find `truefetch/global-car-listing`, inspect its schema, run the one-result Toyota Camry scenario above, and retrieve the Dataset item. Running Actors through MCP requires authentication. See the current [Apify MCP server guide](https://docs.apify.com/integrations/mcp) before configuring a production client.

### How much does Global Car Listing cost?

Global Car Listing uses pay-per-event pricing. Actor Start is a one-time event for each run, while `result` is charged once for every vehicle listing written to the default Dataset.

| Billed event and tier | Price per event | Billing unit |
| --- | ---: | --- |
| Actor Start | $0.01000 | One Actor run start. |
| Result - FREE | $0.01250 | One published Dataset item. |
| Result - BRONZE | $0.01208 | One published Dataset item. |
| Result - SILVER | $0.01167 | One published Dataset item. |
| Result - GOLD | $0.01125 | One published Dataset item. |
| Result - PLATINUM | $0.01125 | One published Dataset item. |
| Result - DIAMOND | $0.01125 | One published Dataset item. |

On the FREE tier, the smallest useful run that publishes one result costs $0.01000 + $0.01250 = **$0.02250**. A run with no published result can still incur Actor Start. Prices can change, so verify the live Store pricing surface after publication before budgeting a large run.

### How does Global Car Listing compare with alternatives?

| Option | Best fit | Trade-off |
| --- | --- | --- |
| Global Car Listing | One normalized contract across several vehicle markets. | Optional source fields can be empty, and platform/location compatibility varies. |
| A focused TrueFetch car Actor | Deep work in one named market such as Hong Kong, India, or Brazil. | It does not provide the same broad multi-market selection. |
| Separate marketplace integrations | Teams that require every platform's native response structure. | More integration, monitoring, and normalization work. |
| Manual marketplace review | Small, occasional checks where human context matters most. | Difficult to repeat, compare, or schedule at larger volumes. |

Choose Global Car Listing when cross-market consistency is the priority. Choose a focused Actor when one marketplace's coverage and terminology matter more than a shared schema.

### What are the limits and troubleshooting steps?

| Symptom or limit | Explanation and next step |
| --- | --- |
| No compatible platform remains | Confirm that every selected platform supports the chosen country. Remove the allowlist to test all country-compatible sources. |
| A location input is rejected | Try one supported postal code or area, or omit `location`; not every marketplace accepts native location filtering. |
| A make/model source rejects the keyword | Remove a leading year or generic term and use a make/model phrase such as `Toyota Camry`. |
| Fewer results arrive than requested | `max_results` is a ceiling, not a guarantee. Check live source availability and retry with one platform to isolate the source. |
| Optional fields are empty | The source did not expose those values in the listing. Use `source_url` to review the original record. |
| Similar listings appear across platforms | Deduplication occurs within a platform stream; the same vehicle can legitimately appear on several marketplaces. |
| One platform fails while others return data | Treat the run as partial. Record the platform label and run ID before opening a support request. |

For the smallest reproducible report, use `max_results: 1`, one platform, one country, and no location unless the defect is location-specific. Do not include API tokens or private data in an issue.

### Frequently asked questions

#### Which inputs are required?

`country`, `keyword`, and `max_results` are required. `platforms` and `location` are optional and do not receive a non-empty default.

#### Does `max_results` limit the whole run?

No. It limits published results per selected platform, so a multi-platform run can return more than the configured number overall.

#### Why can a valid location still produce no result?

Location semantics belong to each source. A postal code, city, or region may be valid generally but unsupported by the selected marketplace.

#### Is the current Store usage count included as proof?

No. The public TrueFetch record was not available during the July 21, 2026 verification, and the user identified existing online data as legacy. No old run, user, rating, or review number is presented as current release evidence.

### Related TrueFetch Actors

- [28car Car Listing](https://apify.com/truefetch/28car-car-listing?fpr=aiagentapi) focuses on Hong Kong vehicle listings when a single local marketplace is preferable to global routing.
- [CarDekho Car Listing](https://apify.com/truefetch/cardekho-car-listing?fpr=aiagentapi) focuses on India and is the narrower choice for CarDekho-specific research.
- [Webmotors Car Listing](https://apify.com/truefetch/webmotors-car-listing?fpr=aiagentapi) focuses on Brazil for Webmotors-specific inventory and pricing work.

These are the three related TrueFetch project directories verified in the current audit scope. Their public links must be rechecked after publication.

### Support and last updated

- **Store:** [Global Car Listing](https://apify.com/truefetch/global-car-listing?fpr=aiagentapi)
- **API:** [Global Car Listing API](https://apify.com/truefetch/global-car-listing/api?fpr=aiagentapi)
- **Apify platform help:** [Apify documentation](https://docs.apify.com/)
- **Community:** [TrueFetch Telegram group](https://t.me/TrueFetch)
- **Direct support:** [AiAgentApi support](https://t.me/AiAgentApi)

Verified against the local schemas, pricing metadata, and read-only runtime evidence on **July 21, 2026**. Store, API, and related Actor destinations were not publicly resolvable during verification and remain a pre-publication validation gate.

[**Test one Global Car Listing result**](https://apify.com/truefetch/global-car-listing?fpr=aiagentapi) · [**Review the API surface**](https://apify.com/truefetch/global-car-listing/api?fpr=aiagentapi)

# Actor input Schema

## `country` (type: `string`):

Country or region used for platform routing and proxy selection.

## `keyword` (type: `string`):

Required vehicle search phrase. It is sent without adding, removing, translating, or replacing terms.

## `platforms` (type: `array`):

Optional platform allowlist. Leave empty to use all compatible platforms for the selected country and location.

## `location` (type: `string`):

Optional city, region, postal code, ZIP, or local area. Platforms without a native location request are skipped.

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

Maximum vehicle listings returned per selected platform.

## Actor input object example

```json
{
  "country": "United States",
  "keyword": "Toyota Camry",
  "max_results": 50
}
```

# Actor output Schema

## `results` (type: `string`):

Open the overview table for normalized vehicle listings from the selected supported platforms.

# 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 = {
    "country": "United States",
    "keyword": "Toyota Camry",
    "max_results": 50
};

// Run the Actor and wait for it to finish
const run = await client.actor("truefetch/car-listings-api").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 = {
    "country": "United States",
    "keyword": "Toyota Camry",
    "max_results": 50,
}

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

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

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

```

## CLI example

```bash
echo '{
  "country": "United States",
  "keyword": "Toyota Camry",
  "max_results": 50
}' |
apify call truefetch/car-listings-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=truefetch/car-listings-api",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

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