Guide to the Carrida REST Programming Interface

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

Home page

Table of Contents

1   Introduction

This is the documentation for the Carrida Web API which is available on the Carrida cloud-based server and on the Carrida smart cameras. 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.

Both the camera and the cloud solution share a majority of features and their API is kept as similar as possible. The major differences between the smart camera API and the cloud-based API are:

  • The cloud-based Carrida solutions support make&model detection
  • The camera API has access only to the built-in imaging sensor, it is not possible to upload and process stored images
  • The camera API does not support profiles and does not need user authentication
  • The camera API supports settings to control imaging parameters of the onboard sensor

The Carrida camera API allows you to remotely access and control the ALPR on a camera using the REST interface. A such it is designed to fetch recent reading results and process them within your application.

The Carrida cloud-based solution is designed to provide ALPR reading 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

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