---
title: "Recognition"
description: "Extract license plates and VINs from images using computer vision."
canonical_url: "https://docs.carsxe.com/docs/products/recognition"
markdown_url: "https://docs.carsxe.com/docs/products/recognition.md"
last_updated: "1980-01-01"
---

# Recognition
URL: /docs/products/recognition
LLM index: /llms.txt
Description: Extract license plates and VINs from images using computer vision.

Recognition turns vehicle images into structured identifiers you can use in the rest of the CarsXE API. Use Plate Image Recognition when the photo contains a license plate. Use VIN OCR when the photo contains a VIN plate, dashboard VIN, or sticker. Both endpoints are `POST` requests with JSON bodies and `key` as a query parameter.

## When to use it

- Intake workflows where users upload vehicle photos
- Parking, tolling, inspections, and fleet workflows
- Turning a plate photo into a plate string before plate decoding
- Extracting a VIN from paperwork, dashboard stickers, or VIN plates

## Plate Image Recognition

Extract a license plate number and region from a vehicle image.

### Parameters

| Parameter | Required | Location | Description |
|---|---|---|---|
| `key` | Yes | Query | Your CarsXE API key |
| `image_url` | Yes | JSON body | Public URL to an image of a vehicle/license plate |

<Note>
  Use `image_url` for raw HTTP requests. Some SDKs may expose this as `upload_url`; the endpoint body field remains `image_url`.
</Note>

### Example

<CodeGroup title="Recognize a plate" tag="POST" label="/platerecognition">

```bash
curl -X POST "https://api.carsxe.com/platerecognition?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image_url":"https://imagedelivery.net/moyiiSImjJPI_EZVxNMBBw/f49aed53-d736-4370-f3f4-97418841c800/public"}'
```

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

const carsxe = new CarsXE("YOUR_API_KEY");
const imageUrl = "https://imagedelivery.net/moyiiSImjJPI_EZVxNMBBw/f49aed53-d736-4370-f3f4-97418841c800/public";

try {
  const plateRecognition = await carsxe.plateImageRecognition({ imageUrl });
  console.log(plateRecognition);
} catch (error) {
  console.error(error);
}
```

```python
import asyncio
from carsxe_api import CarsXE

carsxe = CarsXE("YOUR_API_KEY")
upload_url = "https://imagedelivery.net/moyiiSImjJPI_EZVxNMBBw/f49aed53-d736-4370-f3f4-97418841c800/public"

try:
    plateRecognition = asyncio.run(carsxe.plate_image_recognition({"upload_url": upload_url}))
    print(plateRecognition)
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");
$upload_url = "https://imagedelivery.net/moyiiSImjJPI_EZVxNMBBw/f49aed53-d736-4370-f3f4-97418841c800/public";

try {
    $plateRecognition = $carsxe->plateImageRecognition(["upload_url" => $upload_url]);
    print_r($plateRecognition);
} catch (Exception $error) {
    echo "Error: " . $error->getMessage();
}
```

```ruby
require "carsxe"

carsxe = Carsxe::CarsXE.new(api_key: "YOUR_API_KEY")
imageUrl = "https://imagedelivery.net/moyiiSImjJPI_EZVxNMBBw/f49aed53-d736-4370-f3f4-97418841c800/public"

begin
  plateRecognition = carsxe.plate_image_recognition("imageUrl" => imageUrl)
  puts plateRecognition
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")
	imageUrl := "https://imagedelivery.net/moyiiSImjJPI_EZVxNMBBw/f49aed53-d736-4370-f3f4-97418841c800/public"
	plateRecognition := client.PlateImageRecognition(map[string]string{"imageUrl": imageUrl})
	fmt.Println(plateRecognition)
}
```

```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("imageUrl", "https://imagedelivery.net/moyiiSImjJPI_EZVxNMBBw/f49aed53-d736-4370-f3f4-97418841c800/public");

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

```swift
import carsxe

let carsxe = CarsXE(apiKey: "YOUR_API_KEY")
let imageUrl = "https://imagedelivery.net/moyiiSImjJPI_EZVxNMBBw/f49aed53-d736-4370-f3f4-97418841c800/public"

do {
    let plateRecognition = try carsxe.plateImageRecognition(["imageUrl": imageUrl])
    print(plateRecognition)
} 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 imageUrl = "https://imagedelivery.net/moyiiSImjJPI_EZVxNMBBw/f49aed53-d736-4370-f3f4-97418841c800/public";

        try
        {
            var plateRecognition = await carsxe.PlateImageRecognition(new Dictionary<string, string> { { "imageUrl", imageUrl } });
            Console.WriteLine(plateRecognition);
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Error: {ex.Message}");
        }
    }
}
```

```bash {{ title: "Response" }}
{
  "success": true,
  "message": "",
  "results": [
    {
      "box": {
        "xmin": 2045,
        "ymin": 1400,
        "xmax": 2732,
        "ymax": 1849
      },
      "plate": "9djc652",
      "region": {
        "code": "us-ca",
        "score": 0.849
      },
      "score": 1,
      "candidates": [
        {
          "score": 1,
          "plate": "9djc652"
        }
      ],
      "dscore": 0.928,
      "vehicle": {
        "score": 0.963,
        "type": "Sedan",
        "box": {
          "xmin": 56,
          "ymin": 0,
          "xmax": 3594,
          "ymax": 2913
        }
      }
    }
  ],
  "processing_time": 117.822
}
```

</CodeGroup>

### Response

#### Top-level shape

<PlateRecognitionTopLevelShape />

Click any object or array to expand it and see sample data. For the full interactive reference, try it live in the [API Reference](/api-reference/recognition/plate-image-recognition).

All response fields are optional. If `results` is empty or missing, no plate was detected.

### results

<Properties>
  <Property name="plate" type="string">
    Best plate candidate, normalized as returned by the recognition provider. Example: `"9djc652"`.
  </Property>
  <Property name="box" type="object">
    Bounding box around the detected plate.
  </Property>
  <Property name="region" type="object">
    Predicted plate region with `code` and `score`.
  </Property>
  <Property name="score" type="number">
    Confidence for the selected plate candidate, from `0` to `1`.
  </Property>
  <Property name="candidates" type="array">
    Alternate plate readings and confidence scores.
  </Property>
  <Property name="dscore" type="number">
    Detection confidence for the plate region.
  </Property>
  <Property name="vehicle" type="object">
    Vehicle detection details when available, including type, confidence, and vehicle bounding box.
  </Property>
</Properties>

### Bounding boxes

Coordinates are pixel offsets in the original image. `xmin` and `ymin` mark the top-left corner. `xmax` and `ymax` mark the bottom-right corner. Use these values to draw overlays or crop the detected plate or vehicle.

<Properties>
  <Property name="xmin" type="number">
    Left edge of the detected region.
  </Property>
  <Property name="ymin" type="number">
    Top edge of the detected region.
  </Property>
  <Property name="xmax" type="number">
    Right edge of the detected region.
  </Property>
  <Property name="ymax" type="number">
    Bottom edge of the detected region.
  </Property>
</Properties>

### Region and candidates

<details>
<summary>**region** - predicted registration region</summary>

The `region.code` identifies the predicted plate region, such as `"us-ca"`. The `region.score` value is the confidence for that region prediction, from `0` to `1`.

</details>

<details>
<summary>**candidates** - alternate plate readings</summary>

Use `candidates` when the top plate result is ambiguous. Each candidate includes a possible plate string and a score so you can decide whether to show alternatives, ask for review, or accept the top result automatically.

</details>

## VIN OCR

Extract a 17-character VIN from an image.

### Parameters

| Parameter | Required | Location | Description |
|---|---|---|---|
| `key` | Yes | Query | Your CarsXE API key |
| `image_url` | Yes | JSON body | Public image URL or base64-encoded image string |

### Example

<CodeGroup title="Extract a VIN" tag="POST" label="/v1/vinocr">

```bash
curl -X POST "https://api.carsxe.com/v1/vinocr?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image_url":"https://user-images.githubusercontent.com/5663423/30922082-64edb4fa-a3a8-11e7-873e-3fbcdce8ea3a.png"}'
```

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

const carsxe = new CarsXE("YOUR_API_KEY");
const imageUrl = "https://user-images.githubusercontent.com/5663423/30922082-64edb4fa-a3a8-11e7-873e-3fbcdce8ea3a.png";

try {
  const vinOcr = await carsxe.vinOcr({ imageUrl });
  console.log(vinOcr);
} catch (error) {
  console.error(error);
}
```

```python
import asyncio
from carsxe_api import CarsXE

carsxe = CarsXE("YOUR_API_KEY")
upload_url = "https://user-images.githubusercontent.com/5663423/30922082-64edb4fa-a3a8-11e7-873e-3fbcdce8ea3a.png"

try:
    vinOcr = asyncio.run(carsxe.vin_ocr({"upload_url": upload_url}))
    print(vinOcr)
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");
$upload_url = "https://user-images.githubusercontent.com/5663423/30922082-64edb4fa-a3a8-11e7-873e-3fbcdce8ea3a.png";

try {
    $vinOcr = $carsxe->vinOcr(["upload_url" => $upload_url]);
    print_r($vinOcr);
} catch (Exception $error) {
    echo "Error: " . $error->getMessage();
}
```

```ruby
require "carsxe"

carsxe = Carsxe::CarsXE.new(api_key: "YOUR_API_KEY")
imageUrl = "https://user-images.githubusercontent.com/5663423/30922082-64edb4fa-a3a8-11e7-873e-3fbcdce8ea3a.png"

begin
  vinOcr = carsxe.vin_ocr("imageUrl" => imageUrl)
  puts vinOcr
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")
	imageUrl := "https://user-images.githubusercontent.com/5663423/30922082-64edb4fa-a3a8-11e7-873e-3fbcdce8ea3a.png"
	vinOcr := client.VinOCR(map[string]string{"imageUrl": imageUrl})
	fmt.Println(vinOcr)
}
```

```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("imageUrl", "https://user-images.githubusercontent.com/5663423/30922082-64edb4fa-a3a8-11e7-873e-3fbcdce8ea3a.png");

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

```swift
import carsxe

let carsxe = CarsXE(apiKey: "YOUR_API_KEY")
let imageUrl = "https://user-images.githubusercontent.com/5663423/30922082-64edb4fa-a3a8-11e7-873e-3fbcdce8ea3a.png"

do {
    let vinOcr = try carsxe.vinOCR(["imageUrl": imageUrl])
    print(vinOcr)
} 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 imageUrl = "https://user-images.githubusercontent.com/5663423/30922082-64edb4fa-a3a8-11e7-873e-3fbcdce8ea3a.png";

        try
        {
            var vinOcr = await carsxe.VinOcr(new Dictionary<string, string> { { "imageUrl", imageUrl } });
            Console.WriteLine(vinOcr);
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Error: {ex.Message}");
        }
    }
}
```

```bash {{ title: "Response" }}
{
  "success": true,
  "vin": "JHLRD77874C026456",
  "box": {
    "xmin": 257,
    "xmax": 1673,
    "ymin": 635,
    "ymax": 793
  },
  "confidence": 0.9834251403808594,
  "candidates": [
    {
      "vin": "JHLRD77874C026456",
      "confidence": 0.9834251403808594,
      "box": {
        "xmin": 257,
        "xmax": 1673,
        "ymin": 635,
        "ymax": 793
      }
    }
  ]
}
```

</CodeGroup>

### Response

#### Top-level shape

<VinOcrTopLevelShape />

Click any object or array to expand it and see sample data. For the full interactive reference, try it live in the [API Reference](/api-reference/recognition/vin-ocr).

All response fields are optional. A successful response can include one best VIN plus candidate VINs when multiple readings are possible.

### VIN fields

<Properties>
  <Property name="vin" type="string">
    Best extracted VIN candidate. Example: `"JHLRD77874C026456"`.
  </Property>
  <Property name="confidence" type="number">
    Confidence score between `0` and `1`.
  </Property>
  <Property name="box" type="object">
    Bounding box around the detected VIN text.
  </Property>
  <Property name="candidates" type="array">
    Alternate VIN candidates with confidence scores and optional bounding boxes.
  </Property>
</Properties>

### Image quality

- Use a sharp image where the plate or VIN is readable.
- Avoid glare, motion blur, extreme angles, and heavy cropping.
- For VIN OCR, include the full VIN line when possible.
- For base64 input on VIN OCR, send the base64 string in `image_url`.

## Chaining Recognition With Vehicle Data

Plate Image Recognition returns a plate string; pass that into [Plate Decoder](/docs/products/plate-decoder) when you need vehicle details. VIN OCR returns a VIN; pass that into [Specifications](/docs/products/specifications), Market Value, Vehicle History, or Recalls.

Use the [API Reference](/api-reference) to try these endpoints live and inspect the complete schemas.

## Errors

See the [Errors guide](/docs/guides/errors) for the full list.

Plate Image Recognition:

- **400** - missing image URL, commonly `"Missing upload URL"`.
- **404** - no plate detected, commonly `"No plates detected in image"`.
- **500** - recognition service error, commonly `"Could not get information at this time"`.

VIN OCR:

- **400** - missing image data, invalid image data, or no text detected.
- **401** - API key is inactive.
- **404** - API key not found/disabled, or no valid VIN candidates found.
- **429** - usage limit exceeded.

## 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).