# CarAPI.dev Documentation > Complete API documentation for CarAPI.dev - the Automotive Data API Platform. ## Complete API Reference For full API documentation with all parameters, code examples (cURL, JavaScript, Python), and response schemas in a single file, see: **[llms-full.txt](https://carapi.dev/llms-full.txt)** This documentation site provides detailed guides, code examples, and reference material for integrating CarAPI.dev's automotive data APIs into your applications. ## Developer Resources Machine-readable integration assets for tooling, code generation, and import into API clients: - **OpenAPI 3.1 Specification**: [https://api.carapi.dev/openapi.json](https://api.carapi.dev/openapi.json) — complete schema for all endpoints with request/response shapes, parameters, and error formats. Import into Postman, Insomnia, OpenAPI Generator, or any spec-compatible tool. - **Postman Workspace**: [https://www.postman.com/andurit/carapi-dev](https://www.postman.com/andurit/carapi-dev) — public Postman workspace with pre-built collection and environments (Production + Local). Fork the workspace, paste your API key into the `apiKey` environment variable, and send your first request. ## API Overview Base URL: `https://api.carapi.dev/v1/` All requests require authentication via the `token` query parameter. ## Endpoints ### VIN Decode - **URL**: [/endpoints/vin-decode](https://docs.carapi.dev/endpoints/vin-decode) - **Endpoint**: `GET /v1/vin-decode/:vin` - **Description**: Decode a Vehicle Identification Number (VIN) to retrieve detailed vehicle specifications including make, model, engine power, transmission, fuel type, body style, drivetrain, color, and manufacturer details (name, region, country). ### Plate to VIN - **URL**: [/endpoints/plate-to-vin](https://docs.carapi.dev/endpoints/plate-to-vin) - **Endpoint**: `GET /v1/plate-to-vin/:plateNumber` - **Description**: Convert a license plate number to its corresponding VIN. Supports PL, NO, SK, SE, CZ, and US. US lookups require a 2-letter `state` query parameter (US plates are only unique per state). ### Stolen Vehicle Check - **URL**: [/endpoints/stolen-vehicle-check](https://docs.carapi.dev/endpoints/stolen-vehicle-check) - **Endpoint**: `GET /v1/stolen-check/:vin` - **Description**: Check if a vehicle has been reported as stolen in national and international databases. ### Vehicle Inspection - **URL**: [/endpoints/vehicle-inspection](https://docs.carapi.dev/endpoints/vehicle-inspection) - **Endpoint**: `GET /v1/inspection/:vin` - **Description**: Retrieve vehicle inspection history including MOT tests, emissions checks, and safety inspections. ### Vehicle Listing - **URL**: [/endpoints/vehicle-listing](https://docs.carapi.dev/endpoints/vehicle-listing) - **Endpoint**: `GET /v1/listing` - **Description**: Search current vehicle listings on the market. Filter by make, model, year, price range, and location. ### Vehicle Photos - **URL**: [/endpoints/vehicle-photos](https://docs.carapi.dev/endpoints/vehicle-photos) - **Endpoint**: `GET /v1/photos/:vin` - **Description**: Retrieve available photos for a specific vehicle including exterior, interior, and detail shots. ### Vehicle Payments - **URL**: [/endpoints/vehicle-payments](https://docs.carapi.dev/endpoints/vehicle-payments) - **Endpoint**: `GET /v1/payments/:vin` - **Description**: Get estimated monthly payment calculations based on vehicle price, down payment, loan term, and interest rate. ### Vehicle Valuation - **URL**: [/endpoints/vehicle-valuation](https://docs.carapi.dev/endpoints/vehicle-valuation) - **Endpoint**: `GET /v1/vehicle-valuation?make=&model=&year=&country=` - **Description**: Get current market valuation for a vehicle by make/model/year/country (all required; `country` is ISO 3166-1 alpha-2, 24 supported). Optional `fuel` (`petrol`, `diesel`, `electric`, `hybrid`, `lpg`, `cng`, `hydrogen`) and `kw` (0-2000) filters narrow to a specific drivetrain variant. Optional `mileage` (0-1,000,000 km) refines the valuation for the supplied vehicle. Applied filters are echoed back on the response. Prices are returned in the market's local currency — USD for US, EUR for all other supported markets. Valuations are keyed per base model — use canonical base-model names (`vw` not `volkswagen`, `3-series` not `320d`); unsupported makes return 400 with a did-you-mean suggestion, and model years never produced or models not sold in the requested market return 404 with an explanatory message. Returns 404 when no valuation is available for the supplied configuration. ### Mileage History - **URL**: [/endpoints/mileage-history](https://docs.carapi.dev/endpoints/mileage-history) - **Endpoint**: `GET /v1/mileage-history/:vin` - **Description**: Track historical mileage records for a vehicle to detect odometer rollbacks or inconsistencies. ### VIN OCR (Image) - **URL**: [/endpoints/extract-vin](https://docs.carapi.dev/endpoints/extract-vin) - **Endpoint**: `POST /v1/extract-vin` - **Description**: Extract a 17-character VIN from a photo of a windshield etching, dashboard plate, door jamb sticker, or registration document. Accepts a base64-encoded image (15 MB body limit). Returns `{ vin, confidence }`; a 200 with `vin: null` means no VIN was found. ### License Plate OCR (Image) - **URL**: [/endpoints/extract-plate](https://docs.carapi.dev/endpoints/extract-plate) - **Endpoint**: `POST /v1/extract-plate` - **Description**: Extract a license plate string from a vehicle photo. Optional `country` field (27 supported regions: sk, cz, de, at, pl, hu, ro, bg, hr, si, rs, fr, gb, it, es, pt, be, nl, se, no, dk, fi, ch, ie, gr, us, ca) enforces region-specific format validation. Returns `{ plateNumber, confidence }`; a 200 with `plateNumber: null` means no plate was found. ### Recalls - **URL**: [/endpoints/recalls](https://docs.carapi.dev/endpoints/recalls) - **Endpoint**: `GET /v1/recalls?make=&model=&modelYear=` - **Description**: Look up U.S. recall records for a given make / model / year. Returns recall summaries, consequence, remedy, and severity flags (`parkIt`, `parkOutside`, `overTheAirUpdate`). Results are cached server-side. ### EV Charging Stations - **URL**: [/endpoints/charging-stations](https://docs.carapi.dev/endpoints/charging-stations) - **Endpoint**: `GET /v1/charging-stations?lat=&lon=` - **Description**: Nearest-N EV charging station search around a coordinate pair. Required: `lat` (-90..90), `lon` (-180..180). Optional: `radius` (km, default 10, max 50), `connectorType` (`type2` | `ccs` | `chademo`), `owner` (case-insensitive operator substring, e.g. "ionity"), `minPowerKw` (> 0), `limit` (default 5, max 10). Returns physical locations sorted by great-circle (straight-line, NOT driving) distance, each with address, owners, per-connector-type summaries (`maxPowerKw`, `minPricePerKwh` in EUR — often null, `plugs`), and `stationCount` (charge points merged into the location). No pagination by design. European coverage (strongest: IT, DE, NL, AT, BE, FR, CZ, PL, HU, RO, SK); data refreshes monthly. ### Time to Sell - **URL**: [/endpoints/time-to-sell](https://docs.carapi.dev/endpoints/time-to-sell) - **Endpoint**: `GET /v1/time-to-sell?make=&model=&country=` - **Description**: How long comparable listings stay on the market. Required: `make` (1-50 chars), `model` (1-100 chars, matched as a base model — `A6` ≠ `A6 Allroad`), `country` (13 supported: CZ, SK, PL, UK, US, DE, NL, NO, IT, BE, ES, AT, FR). Optional `year` (1990..next year, widened ±2), `kw` (1-2000, widened ±20% / min ±15), `mileage` (0-2,000,000 km, widened ±25% / min ±20,000), `fuel` (`petrol`, `diesel`, `electric`, `hybrid`, `lpg`, `cng`, `hydrogen` — matched exactly, never relaxed). Send point values for one concrete car, not ranges: the cohort buffers are applied server-side. Returns `make`/`model`/`country` (the canonical cohort resolved to) plus three numbers: `medianDaysToSell` (half of comparable listings were gone faster, half slower — the headline), `p25Days` (the fast quarter; a realistic best case) and `p75Days` (where the slow quarter starts; a quarter took longer still, with no upper bound). The distribution is right-skewed, so publish the p25→p75 spread with the median rather than the median alone — it is typically 4-6x wide — and never present it as a countdown, since the percentiles describe a cohort of past listings rather than the specific car. The metric measures listing disappearance, which also captures withdrawn and expired ads, so it is a market-liquidity signal rather than a sales record; frame it that way wherever the number is shown. If a cohort falls under 30 delistings the upstream silently relaxes `mileage`, then `kw`, then widens `year` to ±4 and answers 200 for that wider set, so send only the optional filters you need. Returns 404 with a `hint` when fewer than 30 comparable delistings exist even after relaxation — an expected outcome for rare cars, not an error to retry. Complements Vehicle Valuation: valuation answers "what is it worth", this answers "how fast will it move". ### Cost of Ownership - **URL**: [/endpoints/cost-of-ownership](https://docs.carapi.dev/endpoints/cost-of-ownership) - **Endpoint**: `GET /v1/cost-of-ownership?make=&model=&year=&country=` - **Description**: What a car costs to run over a holding period. Required: `make` (1-50 chars), `model` (1-100 chars, matched as a base model), `year` (1990..next year — required, unlike Time to Sell, because depreciation is a function of the car's age), `country` (4 supported: CZ, SK, PL, US). Optional: `fuel` (`petrol`, `diesel`, `electric`, `hybrid`, `phev`, `lpg` — inferred from the market when omitted; `lpg` is rejected for US), `kw` (1-2000 — narrows the depreciation cohort and picks the CZ/SK/PL insurance band, ignored for US insurance), `kmPerYear` (1,000-200,000, default 15,000 for CZ/SK/PL and 19,300 for US), `years` (1-15, default 5), `currency` (`EUR`, `CZK`, `PLN`, `USD`; defaults EUR for CZ/SK/PL and USD for US, and is not constrained by country). Returns `vehicle` (the resolved car, plus `requested` — your make/model after case and alias normalization such as volkswagen → vw, the exact form sent upstream), `country`, `assumptions` (`kmPerYear`, `years`, `currentValue`, `currency`, `fuelPriceFlat`), `totals` (`total`, `perYear`, `perMonth`, `perKm`), `breakdown` with five components (`depreciation`, `fuel`, `insurance`, `maintenance`, `taxesAndFees`) and `perYear` (one row per year). All money values are integers in `assumptions.currency` except `totals.perKm`, which carries 3 decimals. IMPORTANT: every component carries its own `confidence` — `measured` means a published dataset covers this exact vehicle (EEA/EPA consumption, an official fuel-price series, a depreciation curve fitted across live listings), `estimated` means authored constants or data stretched to fit. Render the breakdown; do not flatten the response into one number. `perYear` is not `totals.perYear` repeated: depreciation is steepest early and one-off charges land in year 1. Insurance covers the mandatory policy only (MTPL in CZ/SK/PL, liability-only in the US) — never comprehensive. US totals include ~6% sales tax on the car's value following the Edmunds True Cost to Own convention, and US tax/fee figures are national expected values across 50 state regimes rather than a bill for any one state. Financing interest is never included, in any market. Returns 404 with `missing` (`make`, `model`, `consumption`, `fuelPrice`, `depreciation` or `insurance`) and a `hint` when a whole component cannot be estimated; that answer is cached per query, so retrying unchanged returns the same 404. Costs 1 credit. Complements Vehicle Valuation ("what is it worth") and Time to Sell ("how fast will it move") with "what will it cost me to keep". ### EV Route Planner - **URL**: [/endpoints/ev-route](https://docs.carapi.dev/endpoints/ev-route) - **Endpoint**: `GET /v1/ev-route?originLat=&originLon=&destLat=&destLon=&vehicleId=` - **Description**: Plans a drivable EV route and inserts the charging stops needed to complete it. Required: `originLat`/`originLon`/`destLat`/`destLon`, all inside the European service area (lat 35..62, lon -11..35); routes up to 2500 km. Vehicle: either `vehicleId` from /v1/ev-vehicles, OR a custom vehicle via `batteryKwh` (5-300) plus `consumptionWhKm` (80-400), optionally `connector` (`ccs` | `chademo` | `type2`, default ccs) and `maxDcKw` (20-1000, default 150) — sending both a vehicleId and custom params is a 400. Optional: `initialSoc` (5-100, default 90), `minArrivalSoc` (0-80, default 10), `reserveSoc` (0-50, default 10, must be below initialSoc), `ambientC` (-40..50, default 20 — cold raises consumption and slows charging, which can add a stop), `maxDetourKm` (0.5-10, default 5), `optimize` (only `time` today), `includeGeometry` (default false; returns the encoded route polyline). Returns `feasible`, `summary` (distance, drive/charge/total minutes, the charge split into `chargeActiveMin` and `plugOverheadMin`, `offRouteMin`/`offRouteKm`, energy, arrival SoC, stop count, `estChargeCostEur` and `stopsWithKnownPrice`), `stops[]` (station, arrival/depart SoC, charge minutes, kWh added, cost, detour, alternatives), `legs[]`, `vehicle`, `warnings[]` and `attribution[]`. IMPORTANT: `feasible: false` is a 200, not an error — `summary` is null and `gap`/`reason` describe the stretch that cannot be crossed. Cost coverage is partial: read `estChargeCostEur` next to `stopsWithKnownPrice`, since a low count means a low estimate rather than a cheap trip. The optimizer minimizes total trip time, not stop count. Costs 1 credit; identical routes are cached. The `attribution` array MUST be displayed wherever the plan is shown — it is a license condition of OpenStreetMap (ODbL), openrouteservice and Open EV Data. ### EV Vehicle Catalog - **URL**: [/endpoints/ev-vehicles](https://docs.carapi.dev/endpoints/ev-vehicles) - **Endpoint**: `GET /v1/ev-vehicles` - **Description**: The electric vehicles the route planner supports. Optional filters: `brand` (case-insensitive, max 100 chars) and `q` (free text across brand, model and variant, max 100 chars); unfiltered it returns the whole catalog with no pagination. Each vehicle carries `id` (pass as `vehicleId` to /v1/ev-route), `brand`, `model`, `variant`, `releaseYear`, `usableBatteryKwh` (usable, not nominal — planning against the nominal pack overstates range), `consumptionWhPerKm`, `dcMaxKw` and `dcPorts`. Vehicles with no DC port cannot be planned and are rejected by /v1/ev-route with a 400; describe such a car with `batteryKwh`/`consumptionWhKm` instead. Costs 1 credit. The `attribution` string (Open EV Data) must be displayed alongside the data. ## Account & Usage (Free — Not Billed) These introspection endpoints never debit a credit. They require an API token (`?token=`) and are rate-limited rather than quota-billed. ### Account - **URL**: [/account](https://docs.carapi.dev/account) - **Endpoint**: `GET /v1/account?token=` - **Description**: Read your account's plan, status and live usage (`used`, `limit`, `remaining`, `resetDate`) plus your per-minute rate limit, in one response. Free — never spends a credit, and keeps returning 200 even when your monthly quota is exhausted so you can read your balance and reset date. Rate-limited to 1 request/second per account (burst 5). Never cached (`Cache-Control: no-store`). ### Endpoints Catalog - **URL**: [/endpoints](https://docs.carapi.dev/endpoints) - **Endpoint**: `GET /v1/endpoints?token=` - **Description**: List every active endpoint with its per-call credit cost (`slug`, `name`, `category`, `description`, `creditCost`). Free — never spends a credit. Identical for everyone and cacheable (`Cache-Control: public, max-age=300`). ## Authentication Example ```bash curl -X GET "https://api.carapi.dev/v1/vin-decode/1HGBH41JXMN109186?token=your_api_token" ``` ## Response Format All endpoints return JSON responses with consistent structure: ```json { "success": true, "data": { ... }, "requestId": "uuid" } ``` ## Error Handling Error responses include: ```json { "success": false, "error": { "code": "ERROR_CODE", "message": "Human readable error message" } } ``` ## Rate Limits Rate limits are based on your subscription plan: - Free: 100 requests/month - Starter: 5,000 requests/month - Professional: 25,000 requests/month - Business: 100,000 requests/month ## Referral Credit (Lower Your Bill) Customers can reduce their monthly bill by referring other developers via [carapi.dev/refer](https://carapi.dev/refer). - **You earn**: €10 in **account credit** per qualified referral, applied automatically to your next CarAPI.dev invoice - **Not cash**: this is invoice credit, not a cash payout — it cannot be withdrawn, transferred, or paid out to a bank/card; it is only redeemable against CarAPI.dev invoices - **Friend gets**: 20% off their first invoice - **When**: credit is granted when the referred user pays their first invoice (30-day refund clawback window) - **Limit**: up to 10 successful referrals per rolling 12-month window - **Free-plan users**: can earn credit; it is held on the account and applied automatically when they upgrade to a paid plan ## Market Coverage CarAPI.dev has endpoint-specific country availability, strongest in Central/Eastern Europe. ### Global Endpoints (No Restrictions) - **VIN Decode**: Any valid 17-character VIN (post-1981) - **Mileage History, Vehicle Listing, Vehicle Photos, Vehicle Payments**: Global ### Vehicle Valuation (24 Countries) CZ, SK, DE, AT, CH, FR, PL, RO, HU, HR, PT, BG, SI, RS, NL, LT, BE, ES, IE, IT, UK, NO, SE, US ### Vehicle Listing & Valuation - Supported Makes (40 total) Both endpoints support 40 vehicle makes: Acura, Alfa Romeo, Audi, BMW, Cadillac, Chevrolet, Citroën, Cupra, Dacia, Dodge, Ferrari, Fiat, Ford, GMC, Honda, Hyundai, Jaguar, Jeep, Kia, Land Rover, Lexus, Mazda, Mercedes-Benz, MG, MINI, Mitsubishi, Nissan, Opel, Peugeot, Porsche, Ram, Renault, SEAT, Škoda, Subaru, Suzuki, Tesla, Toyota, Volvo, VW Each make includes multiple models. See [llms-full.txt](https://carapi.dev/llms-full.txt) for complete model lists. ### Stolen Vehicle Check (5 Countries) SK, CZ, SI, HU, RO ### Plate to VIN (6 Countries) PL, NO, SK, SE, CZ, US (US requires a 2-letter state code) ### Vehicle Inspection - **Available**: Slovakia (SK) and Czechia (CZ) - STK/EK records - **Coming Soon**: Germany (DE), United Kingdom (UK) ### EV Charging Stations (European Roaming Network) Coverage across the European EV roaming network, strongest in IT, DE, NL, AT, BE, FR, CZ, PL, HU, RO, SK. ~54,000 physical charging locations; refreshed monthly. ### Time to Sell (13 Countries) Tier 1 (high volume, healthy re-sighting): CZ, SK, PL, UK, US, DE. Tier 2 (viable but thinner — expect more relaxation and more 404s on niche models): NL, NO, IT, BE, ES, AT, FR. Deliberately narrower than Vehicle Valuation's 24 markets: this endpoint needs enough *delistings* and a crawl cadence fine enough to resolve a listing's lifetime, which some high-volume markets do not have. NL figures resolve to roughly ±6 days (41% of Dutch delistings land in a single crawl-interval bucket) — usable for ranking models, not for precise promises. ## MCP Server (for AI Agents) CarAPI is also available as a remote MCP (Model Context Protocol) server, exposing all REST endpoints plus a composite buyer-due-diligence tool to MCP-compatible clients (Claude Desktop, Claude Code, Claude.ai, Cursor, ChatGPT, Cline, Zed). - **Endpoint**: `https://mcp.carapi.dev/mcp` - **Transport**: Streamable HTTP (MCP spec 2025-03) - **Auth**: `Authorization: Bearer ` (same key as the REST API) - **Docs page**: [docs.carapi.dev/mcp](https://docs.carapi.dev/mcp) Tool inventory: `carapi_vin_decode`, `carapi_plate_to_vin`, `carapi_stolen_check`, `carapi_inspection`, `carapi_listing_search`, `carapi_photos`, `carapi_payments`, `carapi_valuation`, `carapi_mileage_history`, `carapi_extract_vin` (image OCR), `carapi_extract_plate` (image OCR), `carapi_recalls` (US recalls), `carapi_charging_stations` (nearest EV chargers by coordinates), `carapi_time_to_sell` (median days on market), `carapi_buyer_report` (composite — costs 4 quota units), `carapi_docs` (search this documentation, no API key required, 60 req/min/IP). ## Main Website Visit [carapi.dev](https://carapi.dev/) to sign up, manage your API keys, and view usage analytics.