Guide to the Carrida REST Programming Interface

Revision:	1.1
Date:	2018-05-29
Contact:	support@carrida-technologies.com
Copyright:	2018 Carrida GmbH, Germany
Author:	Carrida Support

Table of Contents

1 Introduction

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

2 Overview of the API

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:

2.1 How to register for Carrida API access?

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.

3 Profiles

3.1 What is a profile?

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.

3.2 List all profiles

Description: API Endpoint for retrieving a list of the user's 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 } ]

Error Response: None

Sample Call

curl -H 'AccessToken: YOUR_ACCESS_TOKEN_HERE' https://demo.carrida.net/profiles

3.3 View a Profile

Description: API Endpoint for viewing the profile with the given ID.

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

3.4 Create a License Plate Recognition Profile

Description: API Endpoint for creating a new LPR profile. See ‘View a Profile’ for a valid example. ‘Classifier’ is the only mandatory parameter. HTTP body payload needs to be valid JSON.

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

3.5 Create a Make/Model Profile

Description: API Endpoint for creating a new MM profile.

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

3.6 Delete a Profile

Description: API Endpoint for deleting a profile with the given ID.

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

3.7 Edit a Profile

Description: API Endpoint for editing the profile with the given ID. HTTP body payload needs to be valid JSON with valid profile parameters.

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

3.8 Set a Default Profile

Description: API Endpoint for setting a default profile.

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

4 License Plate Recognition

4.1 Identify a License Plate Number in an Image

Description: API Endpoint for uploading images and finding license plate numbers. HTTP body payload needs to be an image. This endpoint is rate-limited.

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

4.2 Identify a License Plate Number via an URL

Description: API Endpoint for uploading images via an URL and finding license plate numbers. This endpoint is rate-limited.

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

5 Make&Model Recognition

5.1 Introduction to Make&Model Recognition

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.

5.2 Recognize the Make and the Model of a Car in an Image

Description: API Endpoint for classifying images. HTTP body payload needs to be an image. This endpoint is rate-limited.

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

5.3 Classify the Make and the Model of a Car via an URL

Description: API Endpoint for classifying images via an URL. This endpoint is rate-limited.

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

6 General Error Responses

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" }