Vehicle API Reference
API URL: http(s)://<your-host>/vehicle/[region]
Where [region] is the expected geographic region of the license plates in the uploaded image:
| Region | Parameter Value |
|---|---|
| Europe | eur |
| Africa | afr |
| Australia | aus |
| North America | nam |
| Central America | cam |
| South America | sam |
| East Asia | eas |
| Central Asia | cas |
| South Asia | sas |
| Middle East | me |
To use the API, make an HTTP POST request the endpoint found above.
See below for the required and optional parameters and possible responses.
/{region+}
POST
Description
The content type of the POST request must be in 'multipart/form-data' format, and its size in bytes must not exceed the value specified in the CarmenWorkerMaxFileSize environment variable.
See below for the required and optional parameters and possible responses.
Parameters
| Name | Located in | Description | Required | Schema |
|---|---|---|---|---|
| x-enable-wide-range-analysis | header | If you cannot guarantee that the uploaded image meets all the required parameters (see the Input Images tab on the How To Use page), you can turn on the wide-range analysis by setting this header's value to true. Attention! The duration of the analysis may increase several times. | No | string |
| x-disable-image-resizing | header | The service resizes large images to Full HD resolution by bicubic interpolation. Resizing can make reading many times faster, but it can reduce the recognition efficiency. If you don't want the service to resize your images, turn this feature on by setting the header value to true. By disabling image resizing, you may also need to enable wide range analysis. | No | string |
| region | path | The expected geographic region of the license plates in the uploaded image. | Yes | string |
| Request | body | The request body has to include the required services separated by comma, and the binary content of the image to be examined. Optionally, it can include the place of origin (location) of the license plates in the image to be examined, and the maximum number of reads to be performed (maxreads). | Yes | Request |
Responses
| Code | Description | Schema |
|---|---|---|
| 200 | The HTTP 200 OK success status response code indicates that the request has succeeded. The response will contain a result in JSON format. | Response |
| 400 | Invalid Image. Recognition can not initiate without a proper image. Please check image input guide for proper input images. | Error |
| 401 | You are unauthorized to access the requested resource. An API key is missing. Your API KEY can be found on the ANPR Cloud Dashboard's 'how to use' page. | Error |
| 403 | Invalid API Key! Your account is not authorized to access the requested resource. Your API KEY may have changed. Please check the validity of your API key in the Cloud Dashboard. | Error |
| 405 | This method type is not currently supported. Only the POST method is allowed for ANPR Cloud SaaS. | Error |
| 408 | Timeout occured. | Error |
| 413 | The requested entity (image's size) is larger than the server is willing or able to process. Please check the image input guide to our maximum image size in MB. | Error |
| 429 | Limit exceeded, or throttled request. Please subscribe to our service through which your free lookups are redeemable. | Error |
| 500 | Unexpected internal server error. | Error |
| 503 | The server is currently unavailable. Due to 'queue full' error, cannot process the request. | Error |
| 504 | No timely response received from upstream server serving as a gateway or proxy. | Error |
Models
Request
The request body has to include the required services separated by comma, and the binary content of the image to be examined. Optionally, it can include the place of origin (location) of the license plates in the image to be examined, and the maximum number of reads to be performed (maxreads).
- service: (string) you can select the required service(s) with this parameter. If you only need ANPR data, select ’anpr’. If you only need vehicle identification data (MMR), select ’mmr’. If you only need vehicle hazardous material markings (ADR/eADR/IMO), select ’adr’. You can select any combination of the services, just separate them by commas.
- image: (binary or base64 string) the binary data (as base64-encoded string or as a binary file content) of the picture you would like to analyze.
- location: (string) an optional parameter, it includes the location where the picture was taken. For the complete list of the supported locations, view this documentation.
- maxreads: (integer) an optional parameter, it specifies the maximum number of vehicle/license plate searches per image. Use this parameter carefully, because every search increases the processing time. The system will stop searching when there is no more vehicle/license plate in the image, or the number of searches reaches the value of maxreads. Its value is 1 by default.
Response
If the service call is successful, the service will return a Response json object.
Response structure
- data: (Data structure) includes recognition results.
- nodename: (string) the name of the node this request has been processed by. This is diagnostic information to be included in error reports.
- nodetime: (number) total processing time spent on the worker node (this includes processing, image loading and latency).
- version: (string) version of the JSON response format. Incremented each time the response structure changes.
Data structure
Includes recognition results.
- vehicles: (array of Vehicle structures) includes recognition results returned by each recognition service specified for the vehicles detected in the image (plate for anpr, mmr for mmr, and markings for adr service).
Vehicle structure
Includes recognition results returned by each recognition service specified (anpr and/or mmr) for the vehicles detected in the image.
- bounds: (Bounds structure) the bounds of the vehicle.
- plate: (Plate structure) the recognized license plate.
- mmr: (MMR structure) make, model and color of the vehicle.
- markings: (array of Marking structures) the markings found on the vehicle.
Bounds structure
- extendedPlateFrame: (ROI structure) coordinates of the license plate extension, on the basis of which the vehicle type can be determined.
- vehicleFrame: (ROI structure) coordinates of the vehicle if provided by the MMR engine.
Plate structure
Includes data returned by the ANPR engine for a single license plate.
- found: true if an ANPR engine found plate information in the image, otherwise false.
- engine: (string) the name of the ANPR engine that successfully processed this vehicle.
- bgColor: (Color structure) color of the license plate background if provided by the ANPR engine, can be white or black. This also means that the engine does not give yellow to taxis and green to electric cars, but white. The color is specified by an RGB (red-green-blue) code which properties (r, g, and b respectively) are integer numbers between 0 and 255.
- daColor: (Color structure) dedicated area color. This is important for Arabic license plates, we get a white color for EU license plates.
- color: (Color structure) color of the license plate foreground if provided by the ANPR engine.
- confidence: (integer, min: 0, max: 100) Overall confidence of the license plate calculated from plate type, position, and character confidence values.
- plateTypeConfidence: (integer, min: 0, max: 100) Confidence of the license plate type.
- positionConfidence: (integer, min: 0, max: 100) Confidence of the license plate position.
- category: (string) category of the license plate. For the list of possible values please refer to the Carmen ANPR Reference Manual
- country: (string) nationality of the license plate. For a list of possible values please refer to this table.
- state: (string) where it makes sense, the code of the state, county or region, otherwise an empty string.
- plateChars: (Character structure) an array of read characters, including character structures.
- plateROI: (ROI structure) coordinates of the license plate found.
- plateType: (number) the AR type code of the table. For a list of possible values please refer to the Carmen ANPR Reference Manual.
- separatedText: (string) the recognized text of the license plate with gap symbols as it is visible on the plate (¶ for new row, space for space, | for vertical line, - for hyphen, and ( ) for begin end symbol of small characters.).
- unicodeText: (string) the recognized text of the license plate.
- proctime: (number) the running time of the engine in milliseconds.
Color structure
Represents an RGB color.
- r: (number, min: 0, max: 255) the red component of the color.
- g: (number, min: 0, max: 255) the green component of the color.
- b: (number, min: 0, max: 255) the blue component of the color.
Character structure
Describes a single character recognized on the license plate.
- bgColor: (Color structure) the background color of the character.
- color: (Color structure) the color of the character.
- code: (number) the numeric code of the character.
- confidence: (integer, min: 0, max: 100) the engine's confidence for the character.
- charROI: (ROI structure) coordinates of the given character (see (ROI structure)).
ROI structure
Describes the coordinates of a Rectangle of Interest, giving the coordinates of all four corners.
- topLeft: (Coordinate structure) the top left corner of the rectangle.
- topRight: (Coordinate structure) the top right corner of the rectangle.
- bottomLeft: (Coordinate structure) the bottom left corner of the rectangle.
- bottomRight: (Coordinate structure) the top right corner of the rectangle.
Coordinate structure
Represents a point on the Cartesian plane.
- x: (number) x coordinate.
- y: (number) y coordinate.
MMR structure
Includes the results of the MMR (Make and Model Recognition) process for a single vehicle.
- found: true if an MMR engine found mmr information in the image, otherwise false.
- engine: (string) the name of the MMR engine that successfully processed this vehicle.
- category: (string) the vehicle’s category.
- categoryConfidence: (integer, min: 0, max: 100) confidence level of the vehicle category recognition.
- heading: (string) the vehicle’s view (frontal or rear).
- headingConfidence: (integer, min: 0, max: 100) confidence level of the view recognition.
- color: (Color structure) the vehicle’s color.
- colorConfidence: (integer, min: 0, max: 100) confidence level of the vehicle color recognition.
- make: (string) the make/brand of the vehicle.
- makeConfidence: (integer, min: 0, max: 100) confidence level of the vehicle make recognition.
- model: (string) the model type of a vehicle.
- modelConfidence: (integer, min: 0, max: 100) confidence level of the vehicle model recognition.
- proctime: (number) the running time of the engine in milliseconds.
Marking structure
Includes data returned by the ANPR engine for a single ADR/eADR/IMO plate.
- engine: (string) the name of the ANPR engine that successfully processed this marking.
- confidence: (integer, min: 0, max: 100) Overall confidence of the plate.
- plateTypeConfidence: (integer, min: 0, max: 100) Confidence of the plate type. (Not provided for eADR and A plates)
- positionConfidence: (integer, min: 0, max: 100) Confidence of the plate position. (Not provided for eADR and A plates)
- plateChars: (Character structure) an array of read characters, including character structures. (Not provided for IMO, eADR and A plates)
- plateROI: (ROI structure) coordinates of the plate found.
- plateType: (number) the AR type code of the table. For a list of possible values please refer to the Carmen ANPR Reference Manual.
- type: (string) the type of the table. ADR for ADR plates, E for empty ADR plates, AP for A plates, and IMO for IMO plates
- unicodeText: (string) the recognized text of the ADR plate or a textual representation of the IMO plate.
- proctime: (number) the running time of the engine in milliseconds.
Error
The message property of the json response will describe the error.