License Plate Recognition

Detects and reads license plates within target media.

The License Plate Recognition API detects and recognizes license plates displayed on vehicles in a video or image file. For a full list of supported video container formats and codecs, see Supported Media Formats.

The License Plates Recognition API detects license plates and uses Optical Character Recognition (OCR) to extract the text. You must provide a source location, which is the location where the source video was captured. The API uses this to match the extracted text against a list of probable license plate formats that are commonly seen at that location. This process improves the license plate results. For a list of supported source locations, see the Request tab.

Quick Start

You can upload a video to the API as a file, in which case you must use a POST method.

curl -X POST http://api.havenondemand.com/1/api/async/recognizelicenseplates/v2 --form "file=@gb-plates.mp4" --form "source_location=GB"

You can also input a URL or a Haven OnDemand reference.

If you provide a URL, it must link directly to a video file. You cannot link to a page with an embedded video (such as a news page or YouTube link).

/1/api/async/recognizelicenseplates/v2?url=https://www.havenondemand.com/sample-content/videos/gb-plates.mp4&source_location=GB

Note: Because input files for this API can be large and take a long time to process, the API runs only in asynchronous mode. See Get the Results.

Note: This API has rate and duration limits:

  • Input files are truncated after 30 minutes.
  • The processing terminates after two hours and returns only what it has completed within that time.

For more information, see Rate Limiting, Quotas, Data Expiry, and Maximums.

Specify the Source Location

The source location is the location where the video was captured. This information allows the API to match the extracted text from the image against a list of probable license plate formats that are commonly seen at that location.

curl -X POST http://api.havenondemand.com/1/api/async/recognizelicenseplates/v2 --form "file=@gb-plates.mp4" --form "source_location=GB"

For a list of supported source locations, see the Request tab.

Get the Results

The asynchronous mode returns a job-id, which you can then use to extract your results. There are two methods for this:

  • Use /1/job/status/ to get the status of the job, including results if the job is finished.
  • Use /1/job/result/, which waits until the job has finished and then returns the result.

    Note: Because /result has to wait for the job to finish before it can return a response, using it for longer operations such as processing a large video file can result in an HTTP request timeout response. The /result method returns a response either when the result is available, or after 120 seconds, whichever is sooner. If the job is not complete after 120 seconds, the /result method returns a code 7010 (job result request timeout) response. This means that your asynchronous job is still in progress. To avoid the timeout, use /status instead.

Example

The sample file in the example, gb-plates.mp4, returns:

"items": [{
	"origin": "GB",
	"location_adjusted_text_components": [
		"RV12CNO"
	],
	"ocr_text": "RV12CNO",
	"shape": "regular",
	"confidence": 97,
	"source_region_coordinates": [{
		"x": 493,
		"y": 342,
		"unit": "pixels"
	}, {
		"x": 546,
		"y": 343,
		"unit": "pixels"
	}, {
		"x": 546,
		"y": 358,
		"unit": "pixels"
	}, {
		"x": 493,
		"y": 357,
		"unit": "pixels"
	}],
	"start_time_offset": 2.802,
	"end_time_offset": 3.335,
	"time_offset": 3.169
}, {
	"origin": "GB",
	"location_adjusted_text_components": [
		"T1BPC"
	],
	"ocr_text": "T1BPC",
	"shape": "regular",
	"confidence": 99,
	"source_region_coordinates": [{
		"x": 33,
		"y": 300,
		"unit": "pixels"
	}, {
		"x": 70,
		"y": 300,
		"unit": "pixels"
	}, {
		"x": 70,
		"y": 317,
		"unit": "pixels"
	}, {
		"x": 33,
		"y": 317,
		"unit": "pixels"
	}],
	"start_time_offset": 4.17,
	"end_time_offset": 4.937,
	"time_offset": 4.703
}]

Optimize Results

The quality of the video file that you send can have a large effect on the quality of the API output. For example, you might need to check that:

  • in a paused video, the license plates are readable and in focus.
  • the contrast between the license plate characters and the background is high.
  • the license plate characters are distinguishable.
  • the license plate is viewable in the video for a reasonable duration.
  • the license plate is not hugely tilted away from horizontal.
  • the resolution of the image or video is at least 320x240 pixels
  • in a standard definition video, the width of the video frames is no greater than the width of a traffic lane, and the camera is manually focused on the middle of the region where number plates are read.
Asynchronous
https://api.havenondemand.com/1/api/async/recognizelicenseplates/v2

This API supports only asynchronous invocation.

Authentication

This API requires an authentication token to be supplied in the following parameter:

Parameter Description
apikey The API key to use to authenticate the API request.
Parameters

This API accepts the following parameters:

Required
Name Type Description
file
binary A media file that contains the license plates to recognize. Multipart POST only.
reference
string A Haven OnDemand reference obtained from either the Expand Container or Store Object API. The corresponding video is passed to the API.
url
string A publicly accessible HTTP URL from which a video can be retrieved.
source_location
enum The location code of the place where the source video is captured. This is the code as characterized in the International Organization for Standardization definitions: ISO-3166-1 alpha 2 (for countries), ISO 3166-2:US (for US states), ISO 3166-2:AU (for Australian states and territories), and ISO 3166-2:AE (for United Arab Emirates). For more information, see: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
Enumeration Types

This API's parameters use the enumerations described below:

source_location
The location code of the place where the source video is captured. This is the code as characterized in the International Organization for Standardization definitions: ISO-3166-1 alpha 2 (for countries), ISO 3166-2:US (for US states), ISO 3166-2:AU (for Australian states and territories), and ISO 3166-2:AE (for United Arab Emirates). For more information, see: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
AL Albania
DZ Algeria
AR Argentina
AU-NSW Australia - New South Wales
AU-QLD Australia - Queensland
AU-SA Australia - South Australia
AU-TAS Australia - Tasmania
AU-VIC Australia - Victoria
AU-WA Australia - Western Australia
AU-ACT Australia - Australian Capital Territory
AU-NT Australia - Northern Territory
AT Austria
BH Bahrain
BE Belgium
BR Brazil
CA Canada
CO Colombia
CZ Czech Republic
DK Denmark
FI Finland
FR France
DE Germany
GR Greece
IN India
ID Indonesia
IE Ireland
IL Israel
IT Italy
JP Japan
SA Kingdom of Saudi Arabia
KW Kuwait
MY Malaysia
MX Mexico
NL Netherlands
NZ New Zealand
NG Nigeria
NO Norway
OM Oman
PE Peru
PH Philippines
PL Poland
PT Portugal
QA Qatar
RU Russia
RS Serbia
SG Singapore
SL Slovenia
ZA South Africa
ES Spain
SE Sweden
CH Switzerland
SY Syria
TH Thailand
TR Turkey
UA Ukraine
AE-AZ United Arab Emirates - Abu Dhabi
AE-AJ United Arab Emirates - Ajman
AE-FU United Arab Emirates - Fujairah
AE-SH United Arab Emirates - Sharjah
AE-DU United Arab Emirates - Dubai
AE-RK United Arab Emirates - Ras al-Khaimah
AE-UQ United Arab Emirates - Umm al-Quwain
GB United Kingdom
US-AL United States - Alabama
US-AK United States - Alaska
US-AZ United States - Arizona
US-AR United States - Arkansas
US-CA United States - California
US-CO United States - Colorado
US-CT United States - Connecticut
US-DE United States - Delaware
US-FL United States - Florida
US-GA United States - Georgia
US-HI United States - Hawaii
US-ID United States - Idaho
US-IL United States - Illinois
US-IN United States - Indiana
US-IA United States - Iowa
US-KS United States - Kansas
US-KY United States - Kentucky
US-LA United States - Louisiana
US-ME United States - Maine
US-MD United States - Maryland
US-MA United States - Massachusetts
US-MI United States - Michigan
US-MN United States - Minnesota
US-MS United States - Mississippi
US-MO United States - Missouri
US-MT United States - Montana
US-NE United States - Nebraska
US-NV United States - Nevada
US-NH United States - New Hampshire
US-NJ United States - New Jersey
US-NM United States - New Mexico
US-NY United States - New York
US-NC United States - North Carolina
US-ND United States - North Dakota
US-OH United States - Ohio
US-OK United States - Oklahoma
US-OR United States - Oregon
US-PA United States - Pennsylvania
US-RI United States - Rhode Island
US-SC United States - South Carolina
US-SD United States - South Dakota
US-TN United States - Tennessee
US-TX United States - Texas
US-UT United States - Utah
US-VT United States - Vermont
US-VA United States - Virginia
US-WA United States - Washington
US-DC United States - Washington DC
US-WV United States - West Virginia
US-WI United States - Wisconsin
US-WY United States - Wyoming
VE Venezuela

This API returns a JSON response that is described by the model below. This single model is presented both as an easy to read abstract definition and as the formal JSON schema.

Asynchronous Use

Additional requests are required to get the result if this API is invoked asynchronously.

You can use /1/job/status/<job-id> to get the status of the job, including results if the job is finished.

You can also use /1/job/result/<job-id>, which waits until the job has finished and then returns the result.

Model
This is an abstract definition of the response that describes each of the properties that might be returned.
License Plate Recognition Response {
items ( array[Items] ) All of the detected license plates from the source media.
}
License Plate Recognition Response:Items {
start_time_offset ( number , optional) Time offset from the start of the video to where the license plate first appears. This value is expressed as a non integer number. This is only available if the source media is a video.
end_time_offset ( number , optional) Time offset from the start of the video to where the license plate is no longer visible. This value is expressed as a non integer number. This is only available if the source media is a video.
time_offset ( number , optional) Time offset from the start of the video to where the license plate was identified. This value is expressed as a non integer number. This is only available if the source media is a video.
page ( integer , optional) Page in the document where the license plate is located. This is only available if the source media is a multi-page image, presentation file, or PDF. The minimum possible value of this property is 1, which means that the license plate is located on the first page.
origin ( enum<Origin> ) The location that the license plate originates from (that is, the license plate registration location, rather than the location where the video was captured). This field has the same possible values as the source_location parameter.
location_adjusted_text_components ( array[string] ) An array of strings that represent the different textual information extracted from the license plate. For example, Saudi Arabian license plates consist of 3 letters and up to 4 numbers; these two components are represented as separate elements of the array. This field uses the ocr_text information and applies corrections, according to the format specified by the identified origin. This always contains at least one item, and each item contains at least one character.
ocr_text ( string ) The characters identified by Optical Character Recognition (OCR) before any corrections are applied according to the format specified by the recognized origin.
shape ( enum<Shape> ) The shape of the license plate.
confidence ( number ) A value (0-100) of confidence in the license plate identification.
source_region_coordinates ( array[Source_region_coordinates] ) A set of coordinates (relative to the top left of the source) that represents the bounding region where the license plate can be found in the source media. If the source media is a video then this region is where the license plate was found at time_offset in the video. This always contains at least 3 co-ordinates
}
enum<License Plate Recognition Response:Items:Origin> {
'AL'
'DZ'
'AR'
'AU-NSW'
'AU-QLD'
'AU-SA'
'AU-TAS'
'AU-VIC'
'AU-WA'
'AU-ACT'
'AU-NT'
'AT'
'BH'
'BE'
'BR'
'CA'
'CO'
'CZ'
'DK'
'FI'
'FR'
'DE'
'GR'
'IN'
'ID'
'IE'
'IL'
'IT'
'JP'
'SA'
'KW'
'MY'
'MX'
'NL'
'NZ'
'NG'
'NO'
'OM'
'PE'
'PH'
'PL'
'PT'
'QA'
'RU'
'RS'
'SG'
'SL'
'ZA'
'ES'
'SE'
'CH'
'SY'
'TH'
'TR'
'UA'
'AE-AZ'
'AE-AJ'
'AE-FU'
'AE-SH'
'AE-DU'
'AE-RK'
'AE-UQ'
'GB'
'US-AL'
'US-AK'
'US-AZ'
'US-AR'
'US-CA'
'US-CO'
'US-CT'
'US-DE'
'US-FL'
'US-GA'
'US-HI'
'US-ID'
'US-IL'
'US-IN'
'US-IA'
'US-KS'
'US-KY'
'US-LA'
'US-ME'
'US-MD'
'US-MA'
'US-MI'
'US-MN'
'US-MS'
'US-MO'
'US-MT'
'US-NE'
'US-NV'
'US-NH'
'US-NJ'
'US-NM'
'US-NY'
'US-NC'
'US-ND'
'US-OH'
'US-OK'
'US-OR'
'US-PA'
'US-RI'
'US-SC'
'US-SD'
'US-TN'
'US-TX'
'US-UT'
'US-VT'
'US-VA'
'US-WA'
'US-DC'
'US-WV'
'US-WI'
'US-WY'
'VE'
}
enum<License Plate Recognition Response:Items:Shape> {
'regular' The license plate is displayed as a single row of characters.
'square' The license plate is displayed as multiple rows of characters.
}
License Plate Recognition Response:Items:Source_region_coordinates {
x ( integer ) The horizontal co-ordinate that makes up part of a region.
y ( integer ) The vertical co-ordinate that makes up part of a region.
unit ( enum<Unit> ) The unit in which x and y are expressed.
}
enum<License Plate Recognition Response:Items:Source_region_coordinates:Unit> {
'pixels' Pixels.
'points' Points in the PDF co-ordinate system.
}
Model Schema
This is a JSON schema that describes the syntax of the response. See json-schema.org for a complete reference.
{
    "properties": {
        "items": {
            "items": {
                "properties": {
                    "start_time_offset": {
                        "type": "number",
                        "minimum": 0
                    },
                    "end_time_offset": {
                        "type": "number",
                        "minimum": 0
                    },
                    "time_offset": {
                        "type": "number",
                        "minimum": 0
                    },
                    "page": {
                        "type": "integer",
                        "minimum": 1
                    },
                    "origin": {
                        "enum": [
                            "AL",
                            "DZ",
                            "AR",
                            "AU-NSW",
                            "AU-QLD",
                            "AU-SA",
                            "AU-TAS",
                            "AU-VIC",
                            "AU-WA",
                            "AU-ACT",
                            "AU-NT",
                            "AT",
                            "BH",
                            "BE",
                            "BR",
                            "CA",
                            "CO",
                            "CZ",
                            "DK",
                            "FI",
                            "FR",
                            "DE",
                            "GR",
                            "IN",
                            "ID",
                            "IE",
                            "IL",
                            "IT",
                            "JP",
                            "SA",
                            "KW",
                            "MY",
                            "MX",
                            "NL",
                            "NZ",
                            "NG",
                            "NO",
                            "OM",
                            "PE",
                            "PH",
                            "PL",
                            "PT",
                            "QA",
                            "RU",
                            "RS",
                            "SG",
                            "SL",
                            "ZA",
                            "ES",
                            "SE",
                            "CH",
                            "SY",
                            "TH",
                            "TR",
                            "UA",
                            "AE-AZ",
                            "AE-AJ",
                            "AE-FU",
                            "AE-SH",
                            "AE-DU",
                            "AE-RK",
                            "AE-UQ",
                            "GB",
                            "US-AL",
                            "US-AK",
                            "US-AZ",
                            "US-AR",
                            "US-CA",
                            "US-CO",
                            "US-CT",
                            "US-DE",
                            "US-FL",
                            "US-GA",
                            "US-HI",
                            "US-ID",
                            "US-IL",
                            "US-IN",
                            "US-IA",
                            "US-KS",
                            "US-KY",
                            "US-LA",
                            "US-ME",
                            "US-MD",
                            "US-MA",
                            "US-MI",
                            "US-MN",
                            "US-MS",
                            "US-MO",
                            "US-MT",
                            "US-NE",
                            "US-NV",
                            "US-NH",
                            "US-NJ",
                            "US-NM",
                            "US-NY",
                            "US-NC",
                            "US-ND",
                            "US-OH",
                            "US-OK",
                            "US-OR",
                            "US-PA",
                            "US-RI",
                            "US-SC",
                            "US-SD",
                            "US-TN",
                            "US-TX",
                            "US-UT",
                            "US-VT",
                            "US-VA",
                            "US-WA",
                            "US-DC",
                            "US-WV",
                            "US-WI",
                            "US-WY",
                            "VE"
                        ]
                    },
                    "location_adjusted_text_components": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "minLength": 1
                        },
                        "minItems": 1
                    },
                    "ocr_text": {
                        "type": "string"
                    },
                    "shape": {
                        "enum": [
                            "regular",
                            "square"
                        ]
                    },
                    "confidence": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 100
                    },
                    "source_region_coordinates": {
                        "items": {
                            "type": "object",
                            "properties": {
                                "x": {
                                    "type": "integer",
                                    "minimum": 0
                                },
                                "y": {
                                    "type": "integer",
                                    "minimum": 0
                                },
                                "unit": {
                                    "enum": [
                                        "pixels",
                                        "points"
                                    ]
                                }
                            },
                            "required": [
                                "x",
                                "y",
                                "unit"
                            ]
                        },
                        "minItems": 3,
                        "type": "array"
                    }
                },
                "required": [
                    "confidence",
                    "source_region_coordinates",
                    "origin",
                    "location_adjusted_text_components",
                    "ocr_text",
                    "shape"
                ],
                "type": "object"
            },
            "type": "array"
        }
    },
    "required": [
        "items"
    ],
    "type": "object"
}
https://api.havenondemand.com/1/api/async/recognizelicenseplates/v2
/api/api-example/1/api/async/recognizelicenseplates/v2
Examples
See this API for yourself - select one of our examples below.
GB plates from video.
SA plates from video.
GB plates from images.
Parameters
Required
Select file Change Remove
Name Type Value
source_location
enum

Note: This API will be invoked asynchronously.



Async – Response An error occurred making the API request
Response Code:
Response Body

	
Making API Request…
Checking result of job

To try this API with your own data and use it in your own applications, you need an API Key. You can create an API Key from your account page - API Keys.

Output Refresh An error occurred making the API request View Input
Rendered RawHtml Response
Result Display
Response Code:
Response Body:

			
Make this call with curl


If you would like to provide us with more information then please use the box below:

We will use your submission to help improve our product.