Revision: | 1.1 |
---|---|
Date: | 2018-05-29 |
Contact: | support@carrida-technologies.com |
Copyright: | 2018 Carrida GmbH, Germany |
Author: | Carrida Support |
Table of Contents
This is the documentation for the Carrida Web API which is available on the Carrida cloud-based server. The API is implemented as REST interface, which is very easy to use from your application. In the course of this document, we provide examples as Python code.
The Carrida cloud-based solution is designed to provide ANPR reading and make & model detection capabilities using the REST interface for stored images, which are provided by your application. Every Carrida cloud user must apply for access to the cloud service by registering. Access to the server is controlled by using access tokens, which are required for every request made to the Carrida API (read further for more information).
TBD: graphic for the client-server structure
The Carrida 4 network API is implemented as a REST interface, which you can call and use within your application. The Carrida cameras run a small web server, which processes incoming requests and responds with JSON formatted results. The Carrida cloud service operates after the sample principle, but offers more features and functions than the camera, where the features and functions are, after all, just limited resources.
The following example shows how the latest reading result from the camera can be retrieved with some lines of Python code:
To gain access, visit our website at https://demo.carrida.net/_ and click on the `Register` field in the top right corner of the page. The register page will load and you will be prompted to enter the username, password and an e-mail address. After you've confirmed the data you entered and sent it, you will get an email containing the verification link. Next, open the link in your browser. Now, you should be able to login to https://demo.carrida.net/_ using the your username and password.
After logging in, you can visit the `Settings` link in the menu. Here you can see an overview of your request quota, your subscription and so on. There is also a button labeled Generate Token. By clicking on it you can generate an access token for the API. With this token, you can get started with using the Carrida License Plate Recognition API.
Although, the default settings are very good for license plate recognition, it is still possible to further fine-tune the license plate recognition engine by creating profiles. Profiles contain several settings for the Carrida License Plate Recognition engine that can define things such as the minimum confidence for plates and characters or which features should be and should not be used during the recognition process.
For more information, see Carrida LPR Profiles.
URL | Method | URL Parameter | Data Parameter |
/profiles | GET | None | None |
Success Response
HTTP Status Code | Sample Response |
200 | [ { "default": true, "type": "LPR", "name": "Europa", "id": 1 }, { "type": "LPR", "name": "United States of America", "id": 6 }, { "default": true, "type": "MM", "name": "Europe MM", "id": 8 } ] |
Sample Call
curl -H 'AccessToken: YOUR_ACCESS_TOKEN_HERE' https://demo.carrida.net/profiles
URL | Method | URL Parameter | Data Parameter |
/profile/:id | GET | id - Profile ID (required) | None |
Success Response
HTTP Status Code | Sample Response |
200 | { "Border": { "bottom": "0", "left": "0", "right": "0", "top": "0" }, "Classifier": "eu", "Deinterlace": false, "FilterNoise": false, "FilterOnlyDigits": false, "FilterOnlyLetters": false, "MaxCharactersToAccept": 9, "MaxLetterHeight": 200, "MaxPlateAngle": 20, "MinCharConfidence": 14, "MinCharConfidenceStacked": 14, "MinCharactersToAccept": 3, "MinContrast": 30, "MinLetterHeight": 12, "MinPlateConfidence": 40, "Mode": "best", "OneRowOnly": false, "ScaleHeight": 100, "ScaleWidth": 100, "SearchInverted": true, "SearchInvertedAlways": false, "StateRecognition": true, "id": 1, "name": "Europa" } |
Error Response
HTTP Status Code | Sample Response |
400 | { "msg": "Invalid ID", "status": "error" } |
Sample Call
curl -H 'AccessToken: YOUR_ACCESS_TOKEN_HERE' https://demo.carrida.net/profile/1
URL | Method | URL Parameter | Data Parameter |
/profile/create | POST | None | JSON payload |
Success Response
HTTP Status Code | Sample Response |
200 | { "status": "success", "msg": "ok" } |
Error Response
HTTP Status Code | Sample Response |
400 | { "status": "error", "msg": "JSON not recognized" } |
400 | { "status": "error", "msg": "unsupported key in JSON" } |
Sample Call
curl -H 'AccessToken: YOUR_ACCESS_TOKEN_HERE' https://demo.carrida.net/profile/create --data @newprofile.json
URL | Method | URL Parameter | Data Parameter |
/mmprofile/create | POST | None | HTTP body payload needs to be valid JSON. Parameters can be ‘Checkpoint’, ‘Labels’ and ‘name’. |
Success Response
HTTP Status Code | Sample Response |
200 | { "status": "success", "msg": "ok" } |
Error Response
HTTP Status Code | Sample Response |
400 | { "status": "error", "msg": "JSON not recognized" } |
400 | { "status": "error", "msg": "unsupported key in JSON" } |
Sample Call
curl -H 'AccessToken: YOUR_ACCESS_TOKEN_HERE' https://demo.carrida.net/mmprofile/create --data @newprofile.json
URL | Method | URL Parameter | Data Parameter |
/profile/:id/delete | DELETE | id – Profile ID (required) | None |
Success Response
HTTP Status Code | Sample Response |
200 | { "status": "success", "msg": "ok" } |
Error Response
HTTP Status Code | Sample Response |
400 | { "msg": "Invalid ID", "status": "error" } |
Sample Call
curl -H 'AccessToken: YOUR_ACCESS_TOKEN_HERE' -X DELETE https://demo.carrida.net/profile/1/delete
URL | Method | URL Parameter | Data Parameter |
/profile/:id/edit | POST | id – Profile ID (required) | JSON payload |
Success Response
HTTP Status Code | Sample Response |
200 | { "status": "success", "msg": "ok" } |
Error Response
HTTP Status Code | Sample Response |
400 | { "status": "error", "msg": "Invalid ID" } |
400 | { "status": "error", "msg": "JSON not recognized" } |
400 | { "status": "error", "msg": "unsupported key in JSON" } |
Sample Call
curl -H 'AccessToken: YOUR_ACCESS_TOKEN_HERE' https://demo.carrida.net/profile/1/edit --data @diff_profile.json
URL | Method | URL Parameter | Data Parameter |
/profile/:id/default | PATCH | id – Profile ID (required) | None |
Success Response
HTTP Status Code | Sample Response |
200 | { "status": "success", "msg": "ok" } |
Error Response
HTTP Status Code | Sample Response |
400 | { "status": "error", "msg": "Invalid ID" } |
Sample Call
curl -H 'AccessToken: YOUR_ACCESS_TOKEN_HERE' -X PATCH https://demo.carrida.net/profile/1/default
URL | Method | URL Parameter | Data Parameter |
/upload | |||
/upload/:id | POST | id – Profile ID (optional) | Image contents. |
Success Response
HTTP Status Code | Sample Response |
200 | { "type": "lpr_result", "results": [ { "short-region": "", "vehicle": "0", "plate": "LPR12345", "state-confidence": "80", "state": "AT", "confidence": "95", "ending": "", "characters": [ { "character-color": "#000000", "character": "B", "row-index": "0", "position": { "height": "59", "x": "1469", "width": "30", "y": "1344" }, "confidence": "92", "background-color": "#FFFFFF" }, ... ], "plate-color": "#FFFFFF", "characters-color": "#000000", "short-ending": "", "plate-type": "0", "region": "", "coordinates": { "height": "72", "x": "1464", "width": "375", "y": "1331" }, "rows": "1", "city": "" } ], "image-height": "1920", "processtime": "214", "image-width": "2560" } |
Error Response
HTTP Status Code | Sample Response |
400 | { "status": "error", "msg": "Invalid ID" } |
415 | { "status": "error", "msg": "Image format not recognized" } |
429 | { "msg": "Limit reached. Please check the X-RateLimit-* headers in the response for more information.", "status": "error" } |
Sample Call
curl -H 'AccessToken: YOUR_ACCESS_TOKEN_HERE' https://demo.carrida.net/upload --form image=@car.jpg
URL | Method | URL Parameter | Data Parameter |
/upload/:url | |||
/upload/:id/:url | GET | url – urlencoded URL to an image (required), id – Profile ID (optional) | None |
Success Response
HTTP Status Code | Sample Response |
200 | { "type": "lpr_result", "results": [ { "short-region": "", "vehicle": "0", "plate": "LPR12345", "state-confidence": "80", "state": "AT", "confidence": "95", "ending": "", "characters": [ { "character-color": "#000000", "character": "B", "row-index": "0", "position": { "height": "59", "x": "1469", "width": "30", "y": "1344" }, "confidence": "92", "background-color": "#FFFFFF" }, ... ], "plate-color": "#FFFFFF", "characters-color": "#000000", "short-ending": "", "plate-type": "0", "region": "", "coordinates": { "height": "72", "x": "1464", "width": "375", "y": "1331" }, "rows": "1", "city": "" } ], "image-height": "1920", "processtime": "214", "image-width": "2560" } |
Error Response
HTTP Status Code | Sample Response |
400 | { "status": "error", "msg": "Invalid ID" } |
404 | { "status": "error", "msg": "file at :url not found" } |
413 | { "status": "error", "msg": "file at :url is too big" } |
415 | { "status": "error", "msg": "Image format not recognized" } |
429 | { "msg": "Limit reached. Please check the X-RateLimit-* headers in the response for more information.", "status": "error" } |
Sample Call
curl -H 'AccessToken: YOUR_ACCESS_TOKEN_HERE'
https://demo.carrida.net/upload/https%3A%2F%2Fcars.org%2Fpics%2Fexample%2Fplate.jpg
With the Make & Model Recognition, API offers an easy way to identify the model and the vendor of a car. It is similar to the LPR interface, as it takes an image or URL for processing.
URL | Method | URL Parameter | Data Parameter |
/classify | |||
/classify/:id | POST | id – Profile ID (optional) | Image contents. |
Success Response
HTTP Status Code | Sample Response |
200 | { "models": [ { "p": 44.125357270240784, "model": "Passat", "vendor": "Volkswagen" }, { "p": 32.45294690132141, "model": "Passat Variant", "vendor": "Volkswagen" }, { "p": 19.49639767408371, "model": "Touareg", "vendor": "Volkswagen" }, { "p": 0.6770712323486805, "model": "Golf Variant", "vendor": "Volkswagen" }, { "p": 0.5091906059533358, "model": "Golf", "vendor": "Volkswagen" } ] } |
Error Response
HTTP Status Code | Sample Response |
400 | { "status": "error", "msg": "Invalid ID" } |
415 | { "status": "error", "msg": "Image format not recognized" } |
429 | { "msg": "Limit reached. Please check the X-RateLimit-* headers in the response for more information.", "status": "error" } |
Sample Call
curl -H 'AccessToken: YOUR_ACCESS_TOKEN_HERE' https://demo.carrida.net/classify --form image=@car.jpg
URL | Method | URL Parameter | Data Parameter |
/classify/:url | |||
/classify/:id/:url | GET | url – urlencoded URL to an image (required), id – Profile ID (optional) | None |
Success Response
HTTP Status Code | Sample Response |
200 | { "models": [ { "p": 44.125357270240784, "model": "Passat", "vendor": "Volkswagen" }, { "p": 32.45294690132141, "model": "Passat Variant", "vendor": "Volkswagen" }, { "p": 19.49639767408371, "model": "Touareg", "vendor": "Volkswagen" }, { "p": 0.6770712323486805, "model": "Golf Variant", "vendor": "Volkswagen" }, { "p": 0.5091906059533358, "model": "Golf", "vendor": "Volkswagen" } ] } |
Error Response
HTTP Status Code | Sample Response |
400 | { "status": "error", "msg": "Invalid ID" } |
404 | { "status": "error", "msg": "file at :url not found" } |
413 | { "status": "error", "msg": "file at :url is too big" } |
415 | { "status": "error", "msg": "Image format not recognized" } |
429 | { "msg": "Limit reached. Please check the X-RateLimit-* headers in the response for more information.", "status": "error" } |
Sample Call
curl -H 'AccessToken: YOUR_ACCESS_TOKEN_HERE' https://demo.carrida.net/classify/https%3A%2F%2Fcars.org%2Fpics%2Fexample%2Fmodel.jpg
The following HTTP errors can occur on every request:
HTTP Status Code | Sample Response |
400 | { "status": "error", "msg": "The browser (or proxy) sent a request that this server could not understand." } |
403 | { "msg": "Token invalid", "status": "error" } |
500 | { "status": "erro", "msg": "Request failed" } |