# Build with Argentina’s car prices

Find recent price drops, compare dealer cash quotes and help buyers spot versions priced below their usual level.

## Your first request

Find automatic SUVs under US$30,000 with a detected price reduction in the last seven days.

```sh
curl --get 'https://zero-km.vercel.app/api/v1/deals' \
  --data-urlencode 'kind=price_drops' \
  --data-urlencode 'window=7d' \
  --data-urlencode 'type=SUV' \
  --data-urlencode 'transmission=Automatic' \
  --data-urlencode 'maxPriceUsd=30000'
```

- [API reference](https://zero-km.vercel.app/developers/api)
- [Connect an AI agent](https://zero-km.vercel.app/developers/mcp)

## Start with a buying question

| Your user asks | Use |
| --- | --- |
| “What dropped in price this week?” | `find_deals` with `kind=price_drops` and `window=7d`. |
| “Which versions are below their usual price?” | `find_deals` with `kind=opportunities`. |
| “What does a Corolla start at?” | `get_model_prices` for its cheapest version, current quote and price range. |
| “What can I buy within my budget?” | `search_vehicles` for the lowest current prices matching budget and specifications. |

Cheapest, recently reduced and below-usual prices answer different questions. The API keeps these signals separate.

## Dealer prices, with the evidence attached

- Catalogue monitored five times daily. Each version carries its own detailed quote-check date.
- Dealer cash quotes from El Cero KM for listings with stock at observation, with original ARS/USD prices and quote conditions.
- Same-version opportunity comparisons and dated currency conversions, using the same calculations as the website.
- 418 versions with specifications traced to official Argentine sources. Each specification links to its source; filters exclude unknown equipment.

- [Data quality and price rules](https://zero-km.vercel.app/developers/help)

## From an answer to a shortlist

Use the results’ original IDs to inspect all quotes or compare two to four versions. Include the canonical Zero KM vehicle, model or comparison link in your answer. Buyers can explore the full chart, compare equipment and save their shortlist on the website.

- [Browse current opportunities](https://zero-km.vercel.app/?opportunities=1)
- [Explore version comparisons](https://zero-km.vercel.app/comparar)

# HTTP API reference

Current prices and buying signals, ready for your application.

## Make a request

Base URL: `https://zero-km.vercel.app/api/v1`. Version `1.0.0`. Use GET for queries; HEAD and OPTIONS are also supported. All responses are JSON and allow cross-origin browser access.

```js
const query = new URLSearchParams({
  kind: 'price_drops', window: '7d',
  type: 'SUV', maxPriceUsd: '30000'
});
const response = await fetch(`https://zero-km.vercel.app/api/v1/deals?${query}`);
const body = await response.json();
if (!response.ok) throw new Error(body.error.message);
for (const car of body.data.vehicles) {
  console.log(car.currentPriceUsd, car.bestQuote, car.url);
}
```

## Find opportunities

`GET /api/v1/deals` · MCP: `find_deals`

Find new-car buying opportunities in Argentina by budget, model and specs: below-usual prices, price drops in the last 1/3/7 days, or newly qualifying deals. Returns reasons, before/after prices where available, quote dates and links to explore on Zero KM.

| Parameter | Details |
| --- | --- |
| `kind` | Below-usual prices, recent price reductions, or newly qualifying opportunities. `opportunities`, `price_drops`, `new_opportunities` Default: `opportunities`. |
| `window` | Recent-change window, relative to catalogueObservedAt. Applies to price_drops and new_opportunities. `1d`, `3d`, `7d` Default: `7d`. |
| `sort` | Recommended ranks opportunities by discount, recent price drops by percentage, and new opportunities by recency. `recommended`, `recent`, `price_asc`, `discount_desc` Default: `recommended`. |

- [Shared filters](https://zero-km.vercel.app/developers/api#filters)
- [Pagination](https://zero-km.vercel.app/developers/api#pagination)

## Model prices

`GET /api/v1/models/prices` · MCP: `get_model_prices`

Get current prices for an exact make and model in Argentina: starting price, cheapest version and quote, price range, opportunity count and versions ordered by price. Follow the model link for charts and detailed exploration.

| Parameter | Details |
| --- | --- |
| `make` · required | Type: `string`. |
| `model` · required | Type: `string`. |

```sh
curl --get 'https://zero-km.vercel.app/api/v1/models/prices' \
  --data-urlencode 'make=CITROEN' \
  --data-urlencode 'model=BASALT'
```

- [Pagination](https://zero-km.vercel.app/developers/api#pagination)

## Search versions

`GET /api/v1/vehicles` · MCP: `search_vehicles`

Find the lowest current new-car prices in Argentina by budget, make, model and sourced specifications. Defaults to cheapest first. For recent price drops and buying opportunities use find_deals; get_vehicle provides all current quotes.

| Parameter | Details |
| --- | --- |
| `opportunitiesOnly` | At least 5% below typical price with sufficient history. Type: `boolean`. |
| `sort` | `price_asc`, `price_desc`, `discount_desc`, `name` Default: `price_asc`. |

- [Shared filters](https://zero-km.vercel.app/developers/api#filters)
- [Pagination](https://zero-km.vercel.app/developers/api#pagination)

## Version quotes

`GET /api/v1/vehicles/{id}` · MCP: `get_vehicle`

Inspect a version’s current dealer cash quotes in original ARS/USD, fees, stock at observation, quote-check dates and official specification sources. Includes compact opportunity evidence and a Zero KM link for the full chart and saved shortlist.

| Parameter | Details |
| --- | --- |
| `id` · required | Original vehicle ID returned in pricing or search results. Type: `string`. |

## Compare versions

`GET /api/v1/compare` · MCP: `compare_vehicles`

Compare two to four versions by current prices, buying signals and sourced specifications. Returns a shareable Zero KM comparison page. Missing specifications remain unknown.

| Parameter | Details |
| --- | --- |
| `ids` · required | Two to four distinct vehicle IDs; comma-separated in HTTP, a JSON array in MCP. Type: `array`. 2–4 items. |

## Catalogue

`GET /api/v1/catalogue` · MCP: `get_catalogue`

Discover supported makes, models, filter values, coverage counts and snapshot dates before narrowing a price or opportunity search.

## Shared search filters

Available on `/deals` and `/vehicles`. Names match without case or accents; other enum values are case-sensitive. `q` matches every word across make, model and version. Specification filters exclude unknown values.

| Parameter | Details |
| --- | --- |
| `q` | Words in make, model or version; case and accent insensitive. Type: `string`. |
| `make` | Exact make, case and accent insensitive. Type: `string`. |
| `model` | Exact model, case and accent insensitive. Type: `string`. |
| `type` | `SUV`, `Pickup`, `Hatchback`, `Sedan`, `Van`, `Coupe`, `Wagon`, `MPV`, `Other` |
| `fuel` | `Petrol`, `Diesel`, `Electric`, `Hybrid`, `Mild hybrid`, `Plug-in hybrid`, `Range extender` |
| `transmission` | `Automatic`, `Manual` |
| `minPriceUsd` | Minimum detailed quote in USD. Type: `number`. Min: 0. |
| `maxPriceUsd` | Maximum detailed quote in USD. Type: `number`. Min: 0. |
| `minSeats` | Minimum confirmed seats; excludes unknown values. Type: `integer`. Min: 1. Max: 100. |
| `minAirbags` | Minimum confirmed airbags; excludes unknown values. Type: `integer`. Min: 0. Max: 30. |
| `drivetrain` | `fwd`, `rwd`, `4x2`, `awd`, `4x4`, `4x4-low-range` |
| `aeb` | True includes confirmed low-speed AEB; unknown or optional is excluded. Type: `boolean`. |
| `hasSpecs` | Whether official technical specifications are available. Type: `boolean`. |
| `minDiscountPct` | Requires sufficient price history. Type: `number`. Min: 0. Max: 100. |

`awd`, `4x4` and `4x4-low-range` are distinct drivetrain values. `aeb=false` matches confirmed absence only; unknown or optional equipment is excluded.

## Pagination and ordering

- Follow `pagination.nextOffset` until null. `total` counts all matches before paging. Model price ranges and opportunity counts always cover the full model, even when its versions are paginated.
- Search and model prices start with the cheapest versions. Deals use `recommended`: discount for current opportunities, percentage reduction for price drops, recency for new opportunities. Ties use a stable vehicle ID; deals and model lists also break ties by price.
- Unknown or insufficient-history discounts sort last. If `snapshotAt` changes between pages, restart at offset 0 when you need a consistent snapshot.

| Parameter | Details |
| --- | --- |
| `limit` | Maximum records per page. Type: `integer`. Default: `20`. Min: 1. Max: 100. |
| `offset` | Records to skip; follow pagination.nextOffset. Type: `integer`. Default: `0`. Min: 0. Max: 100000. |

## Response fields

Every query returns `schemaVersion`, `snapshotAt`, `catalogueObservedAt`, `source`, `methodologyUrl`, `documentationUrl` and `data`. Response schemas are defined in OpenAPI.

| Field | Meaning |
| --- | --- |
| `data.vehicles`, `data.pagination` | Search and deal results, or the paginated versions of a model. |
| `data.vehicle` | One version, including every current quote, exchange rate and sourced specification. |
| `id`, `make`, `model`, `trim` | Original catalogue identity. Keep the ID when calling other tools; IDs are case-sensitive. |
| `url`, `sourceUrl` | Canonical Zero KM page and original El Cero KM listing. Return these links with the quote date. |
| `currentPriceUsd`, `bestQuote`, `quoteCount` | Lowest detailed quote in USD, its original ARS/USD offer and number of quotes. `observedAt` dates that check. |
| `quotes[]` | Original price, currency, USD equivalent, color and fees. Stock, location and seller ID are included where supplied; otherwise null. |
| `comparison` | Usual-price benchmark, percentage below it and qualification as an opportunity. |
| `recentChanges` | 1d / 3d / 7d catalogue signals, including before/after evidence when a reduction occurred. |
| `reasons` | `below_typical`, `price_drop` and/or `new_opportunity`. Recent reasons cover seven days; use `recentChanges[window]` for a specific window. |
| `specs` | Values, per-field source attribution and gaps, or null. Missing values mean unknown; equipment may be true, false or optional. |

```json
{
  "schemaVersion": 1,
  "snapshotAt": "2026-10-19T23:09:08.196Z",
  "catalogueObservedAt": "2026-10-19T23:05:15.913Z",
  "source": "https://elcerokm.com",
  "methodologyUrl": "https://zero-km.vercel.app/metodologia",
  "documentationUrl": "https://zero-km.vercel.app/developers",
  "data": {
    "kind": "price_drops",
    "window": "7d",
    "vehicles": [
      {
        "id": "ASqaWO3KfV4tWT3pjkv3B",
        "url": "https://zero-km.vercel.app/renault/kardian/iconic-200-edc",
        "feedUrl": "https://zero-km.vercel.app/datos/renault/kardian/iconic-200-edc.json",
        "make": "RENAULT",
        "model": "KARDIAN",
        "trim": "ICONIC 200 EDC",
        "trimDisplay": "Iconic 200 EDC",
        "type": "SUV",
        "tier": "Entry",
        "tierLabel": "Entrada de gama",
        "fuel": "Petrol",
        "transmission": "Automatic",
        "seats": 5,
        "airbags": 6,
        "factSources": {
          "fuel": "official",
          "transmission": "official",
          "seats": "catalogue",
          "airbags": "catalogue"
        },
        "observedAt": "2026-10-18T20:04:03.490Z",
        "currentPriceUsd": 27837.867549668874,
        "comparison": {
          "windowDays": 180,
          "typicalPriceUsd": 29513.88888888889,
          "lowestPriceUsd": 27186.801346801345,
          "discountPct": 5.678754655239581,
          "observedWeeks": 9,
          "sufficientHistory": true,
          "opportunity": true
        },
        "sourceUrl": "https://elcerokm.com/renault/kardian/iconic-200-edc",
        "recentChanges": {
          "1d": null,
          "3d": null,
          "7d": {
            "kind": "new_opportunity",
            "changedAt": "2026-10-13T21:05:09.856Z",
            "qualifiedSince": null,
            "dropPct": 15.011767084512739,
            "previousPriceUsd": 32754.96688741722,
            "currentPriceUsd": 27837.867549668874,
            "conversionBasis": "current_observed_exchange_rate"
          }
        },
        "hasSpecs": true,
        "quoteCount": 2,
        "bestQuote": {
          "id": 44037,
          "price": 42035180,
          "currency": "ARS",
          "priceUsd": 27837.867549668874,
          "feesIncluded": true,
          "color": null,
          "stock": 1,
          "location": null,
          "sellerId": null
        },
        "availability": "InStock",
        "reasons": [
          "below_typical",
          "price_drop",
          "new_opportunity"
        ]
      }
    ],
    "pagination": {
      "total": 4,
      "limit": 1,
      "offset": 0,
      "nextOffset": 1
    }
  }
}
```

- [Price signals, dates and currencies](https://zero-km.vercel.app/developers/help)
- [Full response schemas](https://zero-km.vercel.app/openapi.json)

## Caching and errors

Successful queries include an ETag and a five-minute shared-cache lifetime. Send `If-None-Match` to get 304 for an unchanged response. Errors are not cached. Reuse responses, paginate and back off on 429 or temporary 5xx errors; no per-client quota is currently configured.

| Status | Meaning |
| --- | --- |
| `400` | Invalid, unknown or repeated parameter; reversed budget bounds; duplicate comparison IDs. |
| `404` | Unknown route, model or version outside the current priced catalogue. |
| `405` | Use GET, HEAD or OPTIONS. |
| `414` | Query string exceeds 4096 characters. |

```json
{
  "error": {
    "code": "invalid_parameters",
    "message": "Use distinct vehicle IDs."
  }
}
```

# Connect your AI agent

Give your agent tools to find buying opportunities and compare current new-car prices in Argentina.

## Connect your client

Add a remote MCP server in your client using the endpoint below. Choose Streamable HTTP and no authentication. Hosted clients need a public HTTPS address; localhost works for clients running on this machine.

```text
https://zero-km.vercel.app/mcp
```

In ChatGPT or another hosted client, install or enable your custom connection and select it for the conversation. Availability depends on the client and workspace settings.

## Codex setup

```sh
codex mcp add zero-km --url https://zero-km.vercel.app/mcp
codex mcp list
```

- [OpenAI MCP setup](https://developers.openai.com/plugins/quickstart)

## Available tools

Pricing tools return the same envelope as the HTTP API in `structuredContent` and a JSON text fallback. Pass numbers and booleans as JSON values; `compare_vehicles.ids` is an array. Errors set `isError=true`. Resources expose the developer guide and methodology as Markdown.

| Tool | Use it for |
| --- | --- |
| `find_deals` | Find new-car buying opportunities in Argentina by budget, model and specs: below-usual prices, price drops in the last 1/3/7 days, or newly qualifying deals. Returns reasons, before/after prices where available, quote dates and links to explore on Zero KM. |
| `get_model_prices` | Get current prices for an exact make and model in Argentina: starting price, cheapest version and quote, price range, opportunity count and versions ordered by price. Follow the model link for charts and detailed exploration. |
| `search_vehicles` | Find the lowest current new-car prices in Argentina by budget, make, model and sourced specifications. Defaults to cheapest first. For recent price drops and buying opportunities use find_deals; get_vehicle provides all current quotes. |
| `get_vehicle` | Inspect a version’s current dealer cash quotes in original ARS/USD, fees, stock at observation, quote-check dates and official specification sources. Includes compact opportunity evidence and a Zero KM link for the full chart and saved shortlist. |
| `compare_vehicles` | Compare two to four versions by current prices, buying signals and sourced specifications. Returns a shareable Zero KM comparison page. Missing specifications remain unknown. |
| `get_catalogue` | Discover supported makes, models, filter values, coverage counts and snapshot dates before narrowing a price or opportunity search. |
| `search` / `fetch` | Retrieval-compatible discovery by make, model or version words, and a sourced vehicle record by ID. |

- [Tool parameters and response schemas](https://zero-km.vercel.app/developers/api)

## Try these questions

- “Which automatic SUVs under US$30,000 dropped in price in Argentina in the last seven days? Show the before/after prices and links.”
- “What is the lowest current price for a Toyota Corolla, and which versions are below their usual price?”
- “Compare these two versions by price and equipment, with links to inspect them on Zero KM.”

```json
{
  "kind": "price_drops",
  "window": "7d",
  "type": "SUV",
  "transmission": "Automatic",
  "maxPriceUsd": 30000,
  "limit": 5
}
```

## Make answers useful to buyers

- Return the Zero KM `url`, original `sourceUrl` and individual quote `observedAt`. Link to the model or comparison page when that better matches the question.
- Keep original currencies and quote conditions. Distinguish a recent price reduction from a usual-price discount; neither implies a manufacturer promotion.
- Cite specification sources through `specs.sourceOf` and `specs.sources`. Missing equipment remains unknown.

- [Data rules](https://zero-km.vercel.app/developers/help)

## Check the connection

MCP Inspector should list 8 tools and two Markdown resources. The server uses stateless Streamable HTTP with current and 2025 client support. A plain browser GET to the endpoint can return 405; connect with an MCP client instead.

```sh
npx @modelcontextprotocol/inspector
```

- [MCP documentation](https://modelcontextprotocol.io/docs/getting-started/intro)
- [Connection troubleshooting](https://zero-km.vercel.app/developers/help#connection)

# Data quality and help

Understand the dates, sources and calculations behind every price and opportunity.

## Freshness and stock

Catalogue monitoring runs five times daily. Detailed quotes refresh when catalogue prices change and on a rotation. Listings have stock in the source at observation; each version includes its own check date. API, MCP and website use the same published snapshot.

| Date | What it tells you |
| --- | --- |
| `catalogueObservedAt` | When the catalogue was checked; the reference time for recent-change windows. |
| `observedAt` | When this version’s detailed quotes, stock and exchange rate were checked. |
| `snapshotAt` | Latest capture included anywhere in the site; it is not the check date of every quote. |

A newer catalogue price can precede a detailed quote update. Requests use the published data; they do not start a live dealer check.

## What qualifies as an opportunity?

The usual price is the median of weekly dealer-price averages over 180 days. For recent kinds, `window=1d`, `3d` or `7d` uses the website’s monitoring windows relative to the catalogue check. Current opportunities do not need a recent change. These are comparisons with recorded asking prices, not manufacturer discounts or guaranteed transaction savings.

| Signal | Rule |
| --- | --- |
| Current opportunity | At least 5% below the same version’s usual-price benchmark, with at least six observed weeks spanning 35 days and history updated within 45 days. |
| Recent price drop | A detected catalogue reduction of at least 2% and US$300, or a reduction that crosses the opportunity threshold. |
| New opportunity | A version newly qualifying within the selected window. It may qualify as more evidence becomes available, without another price cut. |

- [Calculation methodology](https://zero-km.vercel.app/metodologia)

## Prices, currencies and fees

Detailed quotes preserve native ARS/USD values. ARS quotes use the source exchange rate observed at their quote check. Registration is excluded; `feesIncluded` covers freight and paperwork. Financing and final sale conditions may differ.

| Recent-change field | Interpretation |
| --- | --- |
| `dropPct` | Positive price reduction, using native prices when currencies match. Null if qualification occurred without a reduction. |
| `previousPriceUsd`, `currentPriceUsd` | Catalogue before/after prices converted with the same current observed rate. This separates price movement from FX movement; these values can differ from the last detailed quote. |
| `changedAt` | Detected catalogue change time, or null if there was no new price change. |
| `qualifiedSince` | Monitoring-window boundary for qualification without a new price; not an exact event timestamp. |
| `conversionBasis` | `current_observed_exchange_rate`: both change prices use one observed rate. |

## Specifications and unknown values

Technical specifications are traced to official Argentine sources. `sourceOf` maps fields to entries in `sources`. Catalogue facts retain their own `factSources`. Missing, null or a recorded gap means unknown, unclear or disputed; it never means absent. Equipment can be `true`, `false` or `optional`.

- Unit suffixes include `Mm`, `Kg`, `L`, `Kw`, `Nm`, `Kmh` and `L100km`. Power includes `powerUnit`.
- Native version and tier labels are preserved. No tier is inferred from price.

## No results or a missing vehicle

Use `get_catalogue` to discover exact make/model names, then try fewer filters. Models and versions are separate identities. Specification filters exclude unknown values. Keep original case-sensitive IDs: a version leaving the priced catalogue returns 404. A recent-deal search can correctly return no results; widen the window or try current opportunities.

## Connection troubleshooting

- Use the full `/mcp` URL with Streamable HTTP and no authentication, not the legacy `/sse` transport.
- For ChatGPT and other hosted clients, use the deployed HTTPS endpoint. A localhost address points to that client’s machine.
- A browser 403 can mean an Origin restriction. Operators may extend the allowed origins through `MCP_ALLOWED_ORIGINS`; see the repository README.
- MCP bodies are limited to 32 KiB. Query limits also apply to tools; avoid sending whole previous responses as arguments.
- For temporary errors, retry with backoff or use the HTTP API. The AI client may have its own access requirements or charges.

## Discovery and distribution

Developer pages, OpenAPI and Markdown guides are linked from `llms.txt`. Search engines can index the documentation. An MCP endpoint is used when a client connects to it; publishing one does not automatically install it in Google or ChatGPT search. Public directory distribution is a separate platform process.

- [OpenAI public submission](https://developers.openai.com/plugins/deploy/submission)

## Existing public feeds

Established JSON feeds retain their original format, including history. New integrations should use the focused pricing API and link to Zero KM for interactive charts and a saved shortlist.

- [Feed format](https://zero-km.vercel.app/datos.md)
- [Complete existing feed](https://zero-km.vercel.app/datos/vehiculos.json)

## Attribution and reuse

When sharing prices, include the Zero KM page, original El Cero KM listing and quote-check date. Preserve official specification sources. Public technical access does not change ownership of source content or images. Zero KM provides comparison information and does not sell vehicles.

## Resources

- [OpenAPI](https://zero-km.vercel.app/openapi.json)
- [Markdown guide](https://zero-km.vercel.app/developers.md)
- [Methodology](https://zero-km.vercel.app/metodologia)