---
title: "Plate Decoder"
description: "Look up vehicle data by license plate number and state across 50+ countries."
canonical_url: "https://docs.carsxe.com/docs/products/plate-decoder"
markdown_url: "https://docs.carsxe.com/docs/products/plate-decoder.md"
last_updated: "1980-01-01"
---

# Plate Decoder
URL: /docs/products/plate-decoder
LLM index: /llms.txt
Description: Look up vehicle data by license plate number and state across 50+ countries.

Resolve a license plate to structured vehicle data — make, model, trim, VIN, engine, and more. Pass a plate and state (or country) and get back the same richness you'd expect from a VIN decode, sourced directly from registration records.

## When to use it

- Identifying a vehicle when you only have a plate number
- Pre-filling vehicle details in insurance or dealership workflows
- Augmenting camera-captured plates with spec data
- Cross-referencing plate ownership against VIN history

## Parameters

| Parameter | Required | Description |
|---|---|---|
| `plate` | Yes | The license plate number |
| `state` | Yes | Two-letter state, province, or region code (e.g. `CA`, `ON`, `NSW`) |
| `key` | Yes | Your CarsXE API key |
| `country` | No | ISO 3166-1 alpha-2 country code. Defaults to `US`. Example: `GB`, `DE`, `AU` |
| `district` | No | Pakistan only — pass the district code alongside `country=PK` |
| `require_vin` | No | Spain only (`country=ES`). Pass `1` to guarantee a VIN in the response. Costs 2× a standard lookup |

## Example

<CodeGroup title="Decode a plate" tag="GET" label="/v2/platedecoder">

```bash
curl -G https://api.carsxe.com/v2/platedecoder \
  -d key=YOUR_API_KEY \
  -d plate=7XER187 \
  -d state=CA \
  -d country=US
```

```js
import { CarsXE } from "carsxe-api";

const carsxe = new CarsXE("YOUR_API_KEY");
const plate = "7XER187";
const state = "CA";
const country = "US";

try {
  const plateDecoder = await carsxe.platedecoder({ plate, state, country });
  console.log(plateDecoder);
} catch (error) {
  console.error(error);
}
```

```python
import asyncio
from carsxe_api import CarsXE

carsxe = CarsXE("YOUR_API_KEY")
plate = "7XER187"
state = "CA"
country = "US"

try:
    plateDecoder = asyncio.run(carsxe.plate_decoder({"plate": plate, "state": state, "country": country}))
    print(plateDecoder)
except Exception as e:
    print(f"Error: {e}")
```

```php
<?php
require_once __DIR__ . '/vendor/autoload.php';
use CarsxeDeveloper\Carsxe\Carsxe;

$carsxe = new Carsxe("YOUR_API_KEY");
$plate = "7XER187";
$state = "CA";
$country = "US";

try {
    $plateDecoder = $carsxe->plateDecoder(["plate" => $plate, "state" => $state, "country" => $country]);
    print_r($plateDecoder);
} catch (Exception $error) {
    echo "Error: " . $error->getMessage();
}
```

```ruby
require "carsxe"

carsxe = Carsxe::CarsXE.new(api_key: "YOUR_API_KEY")
plate = "7XER187"
state = "CA"
country = "US"

begin
  plateDecoder = carsxe.plate_decoder("plate" => plate, "state" => state, "country" => country)
  puts plateDecoder
rescue StandardError => error
  puts "Error: #{error.message}"
end
```

```go
package main

import (
	"fmt"
	"github.com/carsxe/carsxe-go-package"
)

func main() {
	client := carsxe.New("YOUR_API_KEY")
	plate := "7XER187"
	state := "CA"
	country := "US"
	plateDecoder := client.PlateDecoder(map[string]string{"plate": plate, "state": state, "country": country})
	fmt.Println(plateDecoder)
}
```

```java
import io.github.carsxe.CarsXE;
import java.util.Map;
import java.util.HashMap;

public class Main {
    public static void main(String[] args) {
        CarsXE carsxe = new CarsXE("YOUR_API_KEY");
        Map<String, String> params = new HashMap<>();
        params.put("plate", "7XER187");
        params.put("state", "CA");
        params.put("country", "US");

        try {
            Map<String, Object> plateDecoder = carsxe.platedecoder(params);
            System.out.println(plateDecoder);
        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
        }
    }
}
```

```swift
import carsxe

let carsxe = CarsXE(apiKey: "YOUR_API_KEY")
let plate = "7XER187"
let state = "CA"
let country = "US"

do {
    let plateDecoder = try carsxe.plateDecoder(["plate": plate, "state": state, "country": country])
    print(plateDecoder)
} catch {
    print("Error: \(error)")
}
```

```csharp
using carsxe;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        CarsXE carsxe = new CarsXE("YOUR_API_KEY");
        string plate = "7XER187";
        string state = "CA";
        string country = "US";

        try
        {
            var plateDecoder = await carsxe.PlateDecoder(new Dictionary<string, string> { { "plate", plate }, { "state", state }, { "country", country } });
            Console.WriteLine(plateDecoder);
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Error: {ex.Message}");
        }
    }
}
```

```bash {{ title: "Response" }}
{
  "success": true,
  "input": {
    "plate": "7XER187",
    "state": "CA",
    "country": "US"
  },
  "description": "2021 Toyota Camry SE",
  "make": "Toyota",
  "model": "Camry",
  "trim": "SE",
  "vin": "4T1G11AK9MU451234",
  "year": "2021",
  "style": "Sedan",
  "body_style": "SEDAN 4-DR",
  "color": "Silver",
  "engine": "2.5L L4 DOHC 16V",
  "engine_size": "2.5",
  "fuel_type": "Gasoline",
  "drive_type": "FWD",
  "transmission": "8-Speed Automatic",
  "assembly": "United States"
}
```

</CodeGroup>

## Response

### Top-level shape

<PlateDecoderTopLevelShape />

Click `input` to expand it and see the echoed request fields. For the full interactive reference, try it live in the [API Reference](/api-reference).

All fields except `success` and `input` are optional — availability depends on the country and provider.

### Country response matrix

Plate Decoder v2 responses are country-specific. Expand a country below to inspect the JSON shape that country can return from the current v2 response builders. These fields are possible response keys, not guaranteed non-empty values for every plate.

<PlateDecoderCountryResponses />

### Fields

<details>
<summary>**Identity** — Who made it, what it is, and its VIN</summary>

<Properties>
  <Property name="description" type="string">
    Human-readable summary combining year, make, model, and trim. Example: `"2021 Toyota Camry SE"`.
  </Property>
  <Property name="make" type="string">
    Manufacturer or brand. Example: `"Toyota"`, `"Ford"`, `"BMW"`.
  </Property>
  <Property name="model" type="string">
    Model family. Example: `"Camry"`, `"F-150"`, `"3 Series"`.
  </Property>
  <Property name="trim" type="string">
    Trim level or variant. Example: `"SE"`, `"XLT"`, `"330i"`.
  </Property>
  <Property name="year" type="string">
    Model year as a 4-digit string. Example: `"2021"`.
  </Property>
  <Property name="vin" type="string">
    17-character vehicle identification number, when available from the provider. Not guaranteed — use `require_vin=1` with `country=ES` to enforce it for Spanish plates.
  </Property>
</Properties>

</details>

<details>
<summary>**Body & Style** — Shape, body classification, and color</summary>

<Properties>
  <Property name="style" type="string">
    Normalized vehicle category. Example: `"Sedan"`, `"SUV"`, `"Truck"`. Optional — not always returned.
  </Property>
  <Property name="body_style" type="string">
    Body style as recorded by the manufacturer, typically in uppercase with door count. Example: `"SEDAN 4-DR"`, `"PICKUP"`, `"SPORT UTILITY 4-DR"`.
  </Property>
  <Property name="color" type="string">
    Registered exterior color. Example: `"Silver"`, `"Black"`, `"White"`. Sourced from registration records — may differ from the current painted color if the vehicle has been repainted.
  </Property>
</Properties>

</details>

<details>
<summary>**Powertrain** — Engine, fuel, drivetrain, and transmission</summary>

<Properties>
  <Property name="engine" type="string">
    Full engine descriptor. Example: `"2.5L L4 DOHC 16V"`. Optional — not always returned.
  </Property>
  <Property name="engine_size" type="string">
    Engine displacement in liters. Example: `"2.5"`, `"3.0"`, `"5.0"`.
  </Property>
  <Property name="fuel_type" type="string">
    Primary fuel type. Example: `"Gasoline"`, `"Diesel"`, `"Electric"`, `"Hybrid"`.
  </Property>
  <Property name="drive_type" type="string">
    Wheel drive configuration. Example: `"FWD"`, `"RWD"`, `"AWD"`, `"4WD"`.
  </Property>
  <Property name="transmission" type="string">
    Transmission description. Example: `"8-Speed Automatic"`, `"6-Speed Manual"`, `"CVT"`.
  </Property>
  <Property name="assembly" type="string">
    Country where the vehicle was assembled. Example: `"United States"`, `"Germany"`, `"Japan"`.
  </Property>
</Properties>

</details>

<details>
<summary>**Registration** — Year registered</summary>

<Properties>
  <Property name="registration_year" type="string">
    Year the vehicle was first registered. May differ from the model year. Example: `"2021"`. Optional — not always returned.
  </Property>
</Properties>

</details>

## Country & region support

<Note>
  The endpoint supports **50+ countries**. Pass `country` as an ISO 3166-1 alpha-2 code (e.g. `GB`, `DE`, `NL`, `AU`). It defaults to `US` when omitted.

  **State or province is required** for US, Australian, Canadian, and Pakistani plates — use the standard two-letter code (e.g. `CA`, `NSW`, `ON`).

  **Pakistan** additionally supports a `district` parameter for more precise lookups.

  Coverage and field availability vary by country. Some regions return a full spec set; others return only identity fields.

  See the [full list of supported countries](/docs/guides/supported-countries).
</Note>

## require_vin (Spain only)

By default, Spanish plate lookups use a standard provider that does not guarantee a VIN in the response. Pass `require_vin=1` with `country=ES` to route the request through a higher-cost provider that always returns a VIN.

```bash
curl -G https://api.carsxe.com/v2/platedecoder \
  -d key=YOUR_API_KEY \
  -d plate=1234ABC \
  -d state=MA \
  -d country=ES \
  -d require_vin=1
```

This costs **2× a standard lookup** and only applies to `country=ES`. Passing it for any other country has no effect.

## Errors

| Status | When it happens |
|---|---|
| `400` | Missing `plate` or `state`, or invalid parameter values |
| `401` | Missing or invalid API key |
| `404` | No data found for this plate in the provider's database |
| `429` | Usage limit exceeded |
| `500` | Internal server error |
| `503` | Upstream plate data provider unavailable |

See the [Errors guide](/docs/guides/errors) for general error handling guidance.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).