---
source: sighthound-developer-portal
url: https://dev.sighthound.com/vehicle-analytics/rest-api/quickstart/hosted/
markdown-url: https://dev.sighthound.com/vehicle-analytics/rest-api/quickstart/hosted.md
title: "Vehicle Analytics REST API - Preview"
description: "Test the hosted Vehicle Analytics preview API with API-key authentication and sample requests."
content-type: text/markdown
---

> For AI agents: a documentation index is available at [llms.txt](https://dev.sighthound.com/llms.txt). Markdown versions are available at matching `.md` URLs.

# Vehicle Analytics REST API - Preview

<div class="portal-doc-hero portal-doc-hero--compact" markdown>
<p class="portal-doc-kicker">Hosted preview</p>
<p class="portal-doc-intro">Test the Sighthound-hosted Vehicle Analytics API with API-key authentication before moving to a local or self-hosted Docker deployment.</p>
<div class="portal-doc-actions">
    [Send a sample request](#examples)
    [Run the Docker quickstart](../docker/)
</div>
</div>

<div class="portal-feature-grid">
    <div class="portal-feature-card">
        <h3><i class="portal-icon" data-lucide="cloud"></i> Hosted endpoint</h3>
        <p>Use the preview API URL to evaluate image annotations without running services locally.</p>
    </div>
    <div class="portal-feature-card">
        <h3><i class="portal-icon" data-lucide="key-round"></i> API-key auth</h3>
        <p>Pass the Sighthound-provided key in the request header for every preview request.</p>
    </div>
    <div class="portal-feature-card">
        <h3><i class="portal-icon" data-lucide="car-front"></i> Vehicle results</h3>
        <p>Inspect vehicle, license plate, make, model, color, and region annotations in the JSON response.</p>
    </div>
</div>
The Sighthound Cloud API returns detection coordinates and annotations for all vehicles and license plates detected in an image. For vehicles, the annotations include make, model, color, and generation. For license plates, the annotations include the characters from the plate and region (e.g. Florida, Germany, etc.).

## Request Format

```txt
POST https://preview.sighthoundapi.com/v11/images:annotate
```

### Headers

Sighthound will provide an API key to you. This key is required to be in the request header as shown below.

```txt
Content-Type: application/json
X-API-Key: YOUR-API-KEY
```

### Body

There are two ways to send images to the Cloud API: by using a URI or base64-encoded content. See the `image` object in the examples below.

Only JPG and PNG images are supported at this time. If your use case requires a different format, please contact us.

**Image URI**

```json
{
  "requests": [
    {
      "image": {
        "source": {
          "imageUri": "https://d1mfcqjbhp6mmy.cloudfront.net/vehicles/audi-sports-car-r8-marlene.jpeg"
        }
      },
      "features": [
        {
          "type": "VEHICLE_DETECTION"
        },
        {
          "type": "LICENSE_PLATE_DETECTION"
        }
      ]
    }
  ]
}
```

**Base64 Content**

```json
{
  "requests": [
    {
      "image": {
        "content": "/9j/4QAYR...truncatedBase64String...ZUcQP/2Q=="
      },
      "features": [
        {
          "type": "VEHICLE_DETECTION"
        },
        {
          "type": "LICENSE_PLATE_DETECTION"
        }
      ]
    }
  ]
}
```
## Examples

### Request

Update `YOUR-API-KEY` with your actual key.

=== "curl"
    ```json
    curl --location --request POST 'https://preview.sighthoundapi.com/v11/images:annotate' \
    --header 'Content-Type: application/json' \
    --header "X-API-Key: YOUR-API-KEY" \
    --data-raw '{
    "requests": [
        {
        "image": {
            "source": {
                "imageUri": "https://d1mfcqjbhp6mmy.cloudfront.net/vehicles/audi-sports-car-r8-marlene.jpeg"
            }
        },
        "features": [
            {
                "type": "VEHICLE_DETECTION"
            },
            {
                "type": "LICENSE_PLATE_DETECTION"
            }
        ]}
    ]}'
    ```

=== "C#"

    ```cs

    using System;
    using System.Collections.Generic;
    using System.IO;
    using System.Net;
    using System.Text;
    using System.Text.Json;

    namespace Sighthound {

        public class Feature {
            public string type { get; set; }
        }
        public class Source {
            public string imageUri { get; set; }
        }
        public class Image {
            public Source source { get; set; }
        }
        public class Request {
            public Image image { get; set; }
            public List<Feature> features  { get; set; }
        }
        public class BatchRequest {
            public List<Request> requests { get; set; }
        }

        public class Example {

            public static void Main() {

                var apiUrl = "https://preview.sighthoundapi.com/v11/images:annotate";

                var batchRequest = new BatchRequest {
                    requests = new List<Request>(
                        new Request[] {
                            new Request {
                                image = new Image {
                                    source = new Source {
                                        imageUri = "https://d1mfcqjbhp6mmy.cloudfront.net/vehicles/audi-sports-car-r8-marlene.jpeg"
                                    }
                                },
                                features = new List<Feature>(
                                    new Feature[] {
                                        new Feature {
                                            type = "VEHICLE_DETECTION"
                                        },
                                        new Feature {
                                            type = "LICENSE_PLATE_DETECTION"
                                        }
                                    }
                                )
                            }
                        }
                    )
                };

                string requestJson = JsonSerializer.Serialize(batchRequest);
                byte[] requestData = Encoding.UTF8.GetBytes(requestJson);

                var webRequest = (HttpWebRequest)WebRequest.Create(apiUrl);
                webRequest.Method = "POST";
                webRequest.Accept = "application/json";
                webRequest.ContentType = "application/json";
                webRequest.ContentLength = requestData.Length;
                webRequest.GetRequestStream().Write(requestData, 0, requestData.Length);
                webRequest.Headers.Add("X-API-Key", "YOUR-API-KEY");        //Add your API key here

                using var webResponse = webRequest.GetResponse();
                using var webStream = webResponse.GetResponseStream();

                using var responseReader = new StreamReader(webStream);
                var responseJson = responseReader.ReadToEnd();
                var responseData = JsonDocument.Parse(responseJson);

                var response = responseData.RootElement.GetProperty("responses")[0];

                Console.WriteLine("detected " +
                    response.GetProperty("vehicleAnnotations").GetArrayLength() + " vehicles and " +
                    response.GetProperty("licenseplateAnnotations").GetArrayLength() + " license plates");
            }
        }
    }
    ```

=== "Go"

    ```go
    package main

    import (
        "bytes"
        "encoding/json"
        "fmt"
        "io/ioutil"
        "net/http"
    )

    type Source struct {
        ImageUri string `json:"imageUri"`
    }
    type Image struct {
        Source Source `json:"source"`
    }
    type Feature struct {
        Type string `json:"type"`
    }
    type Request struct {
        Image    Image     `json:"image"`
        Features []Feature `json:"features"`
    }
    type BatchRequest struct {
        Requests []Request `json:"requests"`
    }

    type ExampleResponse struct {
        VehicleAnnotations      []interface{} `json:"vehicleAnnotations"`
        LicenseplateAnnotations []interface{} `json:"licenseplateAnnotations"`
    }
    type ExampleBatchResponse struct {
        Responses []ExampleResponse `json:"responses"`
    }

    var apiUrl = "https://preview.sighthoundapi.com/v11/images:annotate"

    func main() {

        batchRequest := BatchRequest{
            Requests: []Request{
                {
                    Image: Image{
                        Source: Source{
                            ImageUri: "https://d1mfcqjbhp6mmy.cloudfront.net/vehicles/audi-sports-car-r8-marlene.jpeg",
                        },
                    },
                    Features: []Feature{
                        {
                            Type: "VEHICLE_DETECTION",
                        },
                        {
                            Type: "LICENSE_PLATE_DETECTION",
                        },
                    },
                },
            },
        }

        httpRequestBody, _ := json.Marshal(batchRequest)

        httpRequest, _ := http.NewRequest("POST", apiUrl, bytes.NewBuffer(httpRequestBody))
        httpRequest.Header.Set("Content-Type", "application/json")
        httpRequest.Header.Set("Accept", "application/json")
        httpRequest.Header.Set("X-API-Key", "YOUR-API-KEY")     //Add your API key here

        httpClient := &http.Client{}
        httpResponse, error := httpClient.Do(httpRequest)

        if error != nil {
            fmt.Println("request failed:", error)
            return
        }
        defer httpResponse.Body.Close()

        if httpResponse.Status != "200 OK" {
            fmt.Println("response error:", httpResponse.Status)
            return
        }

        responseBody, _ := ioutil.ReadAll(httpResponse.Body)

        var batchResponse ExampleBatchResponse
        err := json.Unmarshal(responseBody, &batchResponse)
        if err != nil {
            fmt.Println("parse error:", err)
            return
        }

        fmt.Println("detected",
            len(batchResponse.Responses[0].VehicleAnnotations), "vehicles and",
            len(batchResponse.Responses[0].LicenseplateAnnotations), "license plates")
    }
    ```

=== "Java"
    ```java
    import java.net.*;
    import java.net.http.*;
    import org.json.*;

    class Example {

        public static void main(String[] args) throws Exception {

            System.setProperty("java.net.preferIPv6Addresses","true"); // for correct "localhost" resolution

            var imageSource = new JSONObject();
            imageSource.put("imageUri", "https://d1mfcqjbhp6mmy.cloudfront.net/vehicles/audi-sports-car-r8-marlene.jpeg");
            var image = new JSONObject();
            image.put("source", imageSource);

            var featureVehicleDetection = new JSONObject();
            featureVehicleDetection.put("type", "VEHICLE_DETECTION");
            var featureLicenseplateDetection = new JSONObject();
            featureLicenseplateDetection.put("type", "LICENSE_PLATE_DETECTION");
            var features = new JSONArray();
            features.put(featureVehicleDetection);
            features.put(featureLicenseplateDetection);

            var request = new JSONObject();
            request.put("image", image);
            request.put("features", features);
            var requests = new JSONArray();
            requests.put(request);

            var batchRequest = new JSONObject();
            batchRequest.put("requests", requests);

            var apiUrl = "https://preview.sighthoundapi.com/v11/images:annotate";

            var httpRequest = HttpRequest.newBuilder()
                .uri(URI.create(apiUrl))
                .header("Content-Type", "application/json")
                .header("Accept", "application/json")
                .header("X-API-Key", "YOUR-API-KEY")        //Add your API key here
                .POST(HttpRequest.BodyPublishers.ofString(batchRequest.toString()))
                .build();

            var httpClient = HttpClient.newHttpClient();

            var httpResponse = httpClient.send(httpRequest, HttpResponse.BodyHandlers.ofString());
            if (httpResponse.statusCode() == 200) {

                var batchResponse = new JSONObject(httpResponse.body());
                var response = batchResponse.getJSONArray("responses").getJSONObject(0);

                System.out.printf("detected %d vehicles and %d license plates%n",
                    response.getJSONArray("vehicleAnnotations").length(),
                    response.getJSONArray("licenseplateAnnotations").length());
            }
        }
    }
    ```

=== "JS"
    ```js
    const apiUrl = "https://preview.sighthoundapi.com/v11/images:annotate";

    const batchRequest = {
        requests: [
            {
                image: {
                    source: {
                        imageUri: "https://d1mfcqjbhp6mmy.cloudfront.net/vehicles/audi-sports-car-r8-marlene.jpeg"
                    }
                },
                features: [
                    {
                        type: "VEHICLE_DETECTION"
                    },
                    {
                        type: "LICENSE_PLATE_DETECTION"
                    }
                ]
            }
        ]
    };

    const fetchResponse = await fetch(apiUrl, {
        body: JSON.stringify(batchRequest),
        headers: {
            "Content-Type": "application/json"
            "X-API-Key": "YOUR-API-KEY"     //Add your API key here
            },
        method: "POST"
    });

    const batchResponse = await fetchResponse.json();

    const response = batchResponse.responses[0];

    console.log("detected",
        response.vehicleAnnotations.length, "vehicles and",
        response.licenseplateAnnotations.length, "license plates");
    ```

=== "PHP"
    ```php
    <?php

    $apiUrl = "https://preview.sighthoundapi.com/v11/images:annotate";

    $batchRequest = [
        "requests" => [
            [
                "image" => [
                    "source" => [
                        "imageUri" => "https://d1mfcqjbhp6mmy.cloudfront.net/vehicles/audi-sports-car-r8-marlene.jpeg"
                    ]
                ],
                "features" => [
                    [
                        "type" => "VEHICLE_DETECTION"
                    ],
                    [
                        "type" => "LICENSE_PLATE_DETECTION"
                    ]
                ]
            ]
        ]
    ];

    $post = array(
        'http' => array(
        'method'  => 'POST',
        'content' => json_encode($batchRequest),
        'header'=>  "Content-Type: application/json\r\n" .
                    "Accept: application/json\r\n"
                    "X-API-Key: YOUR-API-KEY",         //Add your API key here
        )
    );

    $context  = stream_context_create($post);
    $result = file_get_contents($apiUrl, false, $context);
    $batchResponse = json_decode($result);

    print 'detected ' .
        count($batchResponse->{'responses'}[0]->{'vehicleAnnotations'}) . ' vehicles and ' .
        count($batchResponse->{'responses'}[0]->{'licenseplateAnnotations'}) . ' license plates' .
        PHP_EOL;

    ?>
    ```

=== "Python"
    ```python
    import requests

    apiUrl = "https://preview.sighthoundapi.com/v11/images:annotate"

    batchRequest = {
        "requests": [
            {
                "image": {
                    "source": {
                        "imageUri": "https://d1mfcqjbhp6mmy.cloudfront.net/vehicles/audi-sports-car-r8-marlene.jpeg"
                    }
                },
                "features": [
                    {
                        "type": "VEHICLE_DETECTION"
                    },
                    {
                        "type": "LICENSE_PLATE_DETECTION"
                    }
                ]
            }
        ]
    }

    headers = {'X-API-Key': 'YOUR-API-KEY'}     //Add your API key here

    batchResponse = requests.post(apiUrl, json=batchRequest, headers=headers).json()

    response = batchResponse['responses'][0]

    print('detected %r vehicles and %r license plates' %(
        len(response['vehicleAnnotations']),
        len(response['licenseplateAnnotations'])
    ))
    ```

=== "Ruby"
    ```ruby
    require 'json'
    require 'net/http'
    require 'uri'

    apiUrl = 'https://preview.sighthoundapi.com/v11/images:annotate'

    batchRequest = {
        requests: [
            {
                image: {
                    source: {
                        imageUri: 'https://d1mfcqjbhp6mmy.cloudfront.net/vehicles/audi-sports-car-r8-marlene.jpeg'
                    }
                },
                features: [
                    {
                        type: 'VEHICLE_DETECTION'
                    },
                    {
                        type: 'LICENSE_PLATE_DETECTION'
                    }
                ]
            }
        ]
    }

    uri = URI(apiUrl)
    http = Net::HTTP.new(uri.host, uri.port)
    http.use_ssl = true
    request = Net::HTTP::Post.new(uri.request_uri, 'Content-Type' => 'application/json')
    request.add_field('X-API-Key', 'YOUR-API-KEY')  # Add your API key here
    request.body = batchRequest.to_json

    response = http.request(request)
    batchResponse = JSON.parse(response.body)

    vehicleCount = batchResponse['responses'][0]['vehicleAnnotations'].length
    licenseplateCount = batchResponse['responses'][0]['licenseplateAnnotations'].length

    puts "detected #{vehicleCount} vehicles and #{licenseplateCount} license plates"
    ```

=== "Swift"
    ```swift
    import Foundation

    let done = DispatchSemaphore(value: 0)

    let apiUrl = URL(string: "https://preview.sighthoundapi.com/v11/images:annotate")!

    let batchRequest: [String: Any] = [
        "requests": [
            [
                "image": [
                    "source": [
                        "imageUri": "https://d1mfcqjbhp6mmy.cloudfront.net/vehicles/audi-sports-car-r8-marlene.jpeg"
                    ]
                ],
                "features": [
                    [
                        "type": "VEHICLE_DETECTION"
                    ],
                    [
                        "type": "LICENSE_PLATE_DETECTION"
                    ]
                ]
            ]
        ]
    ]

    let batchRequestJson = try? JSONSerialization.data(withJSONObject: batchRequest)

    var httpRequest = URLRequest(url: apiUrl)
    httpRequest.httpMethod = "POST"
    httpRequest.httpBody = batchRequestJson;
    httpRequest.setValue("application/json", forHTTPHeaderField: "Content-Type")
    httpRequest.setValue("application/json", forHTTPHeaderField: "Accept")
    httpRequest.setValue("YOUR-API-KEY", forHTTPHeaderField: "X-API-Key")       //Add your API key here

    let task = URLSession.shared.dataTask(with: httpRequest) { (data: Data?, httpResponse, error) in

        guard let data = data, error == nil else {
            print(error?.localizedDescription ?? "unknown error")
            return
        }

        let batchResponseJson = try? JSONSerialization.jsonObject(with: data, options: [])
        let batchResponse = batchResponseJson as? [String: Any]
        let responses = batchResponse!["responses"] as? [[String: [[String: Any]]]]
        let response = responses![0]

        print("detected \(response["vehicleAnnotations"]!.count) vehicles and \(response["licenseplateAnnotations"]!.count) license plates")

        done.signal()
    }
    task.resume()

    done.wait()
    ```

### Response

```json
{
  "responses": [
    {
      "licenseplateAnnotations": [
        {
          "string": {
            "value": "RTBB221",
            "score": 0.86
          },
          "region": {
            "value": "Germany",
            "score": 0.86
          },
          "boundingPoly": {
            "vertices": [
              {
                "x": 620,
                "y": 450
              },
              {
                "x": 738,
                "y": 450
              },
              {
                "x": 738,
                "y": 478
              },
              {
                "x": 620,
                "y": 478
              }
            ],
            "normalizedVertices": [
              {
                "x": 0.6888888888888889,
                "y": 0.7258064516129032
              },
              {
                "x": 0.82,
                "y": 0.7258064516129032
              },
              {
                "x": 0.82,
                "y": 0.7709677419354839
              },
              {
                "x": 0.6888888888888889,
                "y": 0.7709677419354839
              }
            ]
          },
          "locale": "en-US",
          "score": 0.86,
          "mid": "/m/01jfm_",
          "description": "License plate"
        }
      ],
      "vehicleAnnotations": [
        {
          "make": {
            "value": "audi",
            "score": 0.94
          },
          "model": {
            "value": "r8",
            "score": 0.94
          },
          "generation": {
            "value": {
              "start": 2007,
              "end": 2014
            },
            "score": 0.94
          },
          "color": {
            "value": "white",
            "score": 0.94
          },
          "licenseplate": {
            "$ref": "#/responses/0/licenseplateAnnotations/0"
          },
          "boundingPoly": {
            "vertices": [
              {
                "x": 428,
                "y": 287
              },
              {
                "x": 833,
                "y": 287
              },
              {
                "x": 833,
                "y": 556
              },
              {
                "x": 428,
                "y": 556
              }
            ],
            "normalizedVertices": [
              {
                "x": 0.47555555555555556,
                "y": 0.4629032258064516
              },
              {
                "x": 0.9255555555555556,
                "y": 0.4629032258064516
              },
              {
                "x": 0.9255555555555556,
                "y": 0.896774193548387
              },
              {
                "x": 0.47555555555555556,
                "y": 0.896774193548387
              }
            ]
          },
          "locale": "en-US",
          "score": 0.94,
          "mid": "/m/0k4j",
          "description": "Car"
        }
      ]
    }
  ]
}
```

---

# Agent Instructions

Use this Markdown page as context for Sighthound Developer Portal questions. For broader navigation, read https://dev.sighthound.com/llms.txt. Answer from Sighthound documentation, cite relevant source URLs, and do not ask users to paste secrets, tokens, license keys, or credentials into chat.