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 have 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.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.

Success Response

[
    {
        "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.

Success Response

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

{
    "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.

Success Response

{
    "status": "success",
    "msg": "ok"
}

Error Response

{
    "status": "error",
    "msg": "JSON not recognized"
}

{
    "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.

Success Response

{
    "status": "success",
    "msg": "ok"
}

Error Response

{
    "status": "error",
    "msg": "JSON not recognized"
}

{
    "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.

Success Response

{
    "status": "success",
    "msg": "ok"
}

Error Response

{
    "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.

Success Response

{
    "status": "success",
    "msg": "ok"
}

Error Response

{
    "status": "error",
    "msg": "Invalid ID"
}

{
    "status": "error",
    "msg": "JSON not recognized"
}

{
    "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.

Success Response

{
    "status": "success",
    "msg": "ok"
}

Error Response

{
    "status": "error",
    "msg": "Invalid ID"
}

Sample Call

curl -H 'AccessToken: YOUR_ACCESS_TOKEN_HERE' -X PATCH https://demo.carrida.net/profile/1/default

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.

Success Response

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

{
    "status": "error",
    "msg": "Invalid ID"
}

{
    "status": "error",
    "msg": "Image format not recognized"
}

{
    "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.

Success Response

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

{
    "status": "error",
    "msg": "Invalid ID"
}

{
    "status": "error",
    "msg": "file at :url not found"
}

{
    "status": "error",
    "msg": "file at :url is too big"
}

{
    "status": "error",
    "msg": "Image format not recognized"
}

{
    "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.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.

Success Response

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

{
    "status": "error",
    "msg": "Invalid ID"
}

{
    "status": "error",
    "msg": "Image format not recognized"
}

{
    "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.

Success Response

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

{
    "status": "error",
    "msg": "Invalid ID"
}

{
    "status": "error",
    "msg": "file at :url not found"
}

{
    "status": "error",
    "msg": "file at :url is too big"
}

{
    "status": "error",
    "msg": "Image format not recognized"
}

{
    "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.1   Introduction to camera specific API extensions

The following API methods are specific to Carrida cameras. They are mostly used to get and set parameters related to hardware specific properties.

6.2   List all Properties

Description

This API consists of three main components:

• anpr
• sytem
• access

anpr manages the camera and ANPR-Server configuration, while the system component enables the configuration of the operating system settings. access is for the administration of access lists. Calling this endpoint returns a list of all available properties for the selected component.

Success Response

{
    "time",
    "dhcp",
    "ntp"
}

Error Response

{
    "status": "error",
    "msg": "Unkown component"
}

Sample Call

# login
curl --cookie cookies.log --cookie-jar cookies.log http://192.168.13.231/login --data "username=admin&password=secret"

# get a system property
curl --cookie cookies.log --cookie-jar cookies.log http://192.168.13.231/properties/anpr

6.3   Get and Set System Properties

Description

API Endpoints for getting or setting a system property of a Carrida camera. Use the GET method to retrieve the property and the PATCH method for setting it.

Available Properties

Success Response

{
    :property: :value
}

{
    "status": "success",
    "msg": "ok"
}

Error Response

{
    "status": "error",
    "msg": "Property value missing"
}

{
    "status": "error",
    "msg": "Property not set (check the value)"
}

{
    "status": "error",
    "msg": "Unknown Property"
}

Sample Call

# login
curl --cookie cookies.log --cookie-jar cookies.log http://192.168.13.231/login --data "username=admin&password=secret"

# get a system property
curl --cookie cookies.log --cookie-jar cookies.log http://192.168.13.231/system/time

# set a system property
curl --cookie cookies.log --cookie-jar cookies.log http://192.168.13.231/system/time --request PATCH --data-urlencode "time=2018-03-23T16:30:02+0100"

6.4   Get and Set ANPR Properties

Description

API Endpoints for getting or setting an ANPR property of a Carrida camera. Use the GET method to retrieve the property and the PATCH method to set it.

Success Response

{
    :property: :value
}

{
    "status": "success",
    "msg": "ok"
}

Error Response

{
    "status": "error",
    "msg": "Property value missing"
}

{
    "status": "error",
    "msg": "Invalid value given"
}

{
    "status": "error",
    "msg": "Unknown Property"
}

Sample Call

# login
curl --cookie cookies.log --cookie-jar cookies.log http://192.168.13.231/login --data "username=admin&password=secret"

# get an anpr property
curl --cookie cookies.log --cookie-jar cookies.log http://192.168.13.231/anpr/mode

# set an anpr property
curl --cookie cookies.log --cookie-jar cookies.log http://192.168.13.231/anpr/mode --request PATCH --data-urlencode "mode=fast"

6.5   Get and Set Access Lists

Description

API Endpoints for retrieving and adding the access lists of a Carrida camera. Normally there are three lists: - white list (with name 'white.txt') - black list (with name 'black.txt') - ignore list (with name 'ignore.txt') Use the GET method to retrieve the property and the PATCH method to set it.

*Retrieving an Access List*

With a GET request, a list of plates is returned. The plates can be filtered by sending a JSON document containing a pattern field that contains a RegEx.

*Add a Plate to an Access List*

With a POST request, a new entry for the list can be added. The body of the request should contain a JSON document that looks like the document for a successful GET request (see example response below).

*Delete a Plate from an Access List*

With a DELETE request, one or more entries can be deleted by either specifing one of the two fields in a JSON document inside the request body: - index - delete a single item with the given index number - pattern - delete every plate that matches the given pattern

Success Response

[
    {
        "always":false,
        "index":0,
        "plate":"foo",
        "schedules":[
            {
                "period":
                {
                    "end":"2018-10-31",
                    "start":"2018-10-01"
                },
                "time-span":
                {
                    "from":"16:13",
                    "to":"19:13"
                },
                "weekdays": ["Mo","Tu","We"]
            }
        ]
    },
    {
        "always":true,
        "index":1,
        "plate":"bar"
    },
    {
        "always":true,
        "index":2,
        "plate":"foobar"
    }
]

{
    "status": "success",
    "msg": "Entry added."
}

{
    "status": "success",
    "msg": "Entry removed."
}

Error Response

{
    "status": "error",
    "msg": "Property value missing"
}

{
    "status": "error",
    "msg": "Invalid value given"
}

{
    "status": "error",
    "msg": "Unknown Property"
}

Sample Call

# login
curl --cookie cookies.log --cookie-jar cookies.log http://192.168.13.231/login --data "username=admin&password=secret"

# get an anpr property
curl --cookie cookies.log --cookie-jar cookies.log http://192.168.13.231/anpr/mode

# set an anpr property
curl --cookie cookies.log --cookie-jar cookies.log http://192.168.13.231/anpr/mode --request PATCH --data-urlencode "mode=fast"

6.6   Retrieve a Live Result

Description

This API Endpoint returns the latest result that was captured by the Carrida camera.

Success Response

{
    "plates": [
        {
            "value": "LPR12345",
            "confidence": 90,
            "state": "AT",
            "state_confidence": 89,
            "position": {
                "x": 342,
                "y": 440,
                "width": 59,
                "height": 28
            },
            "rows": 1,
            "platecolor": "#FFFFFF",
            "charactercolor": "#000000"
        }
    ],
    "timestamp": 1525690269,
    "message": "",
    "image": {
        "width": 1920,
        "height": 1080,
          "step": 1920,
          "type": 0,
          "data": "YmFzZTY0IGVuY29kZWQgaW1hZ2U......"
    }
}

Error Response

{
    "status": "error",
    "msg": "No results found"
}

Sample Call

# login
curl --cookie cookies.log --cookie-jar cookies.log http://192.168.13.231/login --data "username=admin&password=secret"

# retrieve and save the snapshot
curl --cookie cookies.log --cookie-jar cookies.log http://192.168.13.231/live/result

6.7   Retrieve previous Results (without images)

Description

This API Endpoint returns a specified amount of results that were last captured by the Carrida camera. The image data is not included. The URL parameter specifies the number of returned results.

Note

This API Endpoint parses the results saved at the camera. The maximal count of saved results is set by the parameter "MaxHistoryEntries" and has a default value 0. In order to enable saving the results at the camera, this parameter should be set to some value >0. In the case that the specified count of results has a larger value than MaxHistoryEntries parameter, only the results found saved at the camera will be sent.

Success Response

[
    {
        "plates": [
            {
                "value": "LPR12345",
                "confidence": 90,
                "state": "AT",
                "state_confidence": 89,
                "position": {
                    "x": 342,
                    "y": 440,
                    "width": 59,
                    "height": 28
                },
                "rows": 1,
                "platecolor": "#FFFFFF",
                "charactercolor": "#000000"
            }
        ],
        "timestamp": 1525690269,
        "message": ""
    },
    ...
    ...
    ...
]

Sample Call

# login
curl --cookie cookies.log --cookie-jar cookies.log http://192.168.13.231/login --data "username=admin&password=secret"

# retrieve and  save the snapshot
curl --cookie cookies.log --cookie-jar cookies.log http://192.168.13.231/text/results/5

6.8   Retrieve previous Results (with images)

Description

This API Endpoint returns a specified amount of results that were last captured by the Carrida camera. The image data is included. The URL parameter specifies the number of returned results.

Note

This API Endpoint parses the results saved at the camera. The maximal count of saved results is set by the parameter "MaxHistoryEntries" and has a default value 0. In order to enable saving the results at the camera, this parameter should be set to some value >0. In the case that the specified count of results has a larger value than MaxHistoryEntries parameter, only the results found saved at the camera will be sent.

[
    {
        "plates": [
            {
                "value": "LPR12345",
                "confidence": 90,
                "state": "AT",
                "state_confidence": 89,
                "position": {
                    "x": 342,
                    "y": 440,
                    "width": 59,
                    "height": 28
                },
                "rows": 1,
                "platecolor": "#FFFFFF",
                "charactercolor": "#000000"
            }
        ],
        "timestamp": 1525690269,
        "message": "",
        "image": {
            "width": 1920,
            "height": 1080,
              "step": 1920,
              "type": 0,
              "data": "YmFzZTY0IGVuY29kZWQgaW1hZ2U......"
        }
    },
    ...
    ...
    ...
]

Sample Call

# login
curl --cookie cookies.log --cookie-jar cookies.log http://192.168.13.231/login --data "username=admin&password=secret"

# retrieve and save the snapshot
curl --cookie cookies.log --cookie-jar cookies.log http://192.168.13.231/text/results-with-images/5

6.9   Delete All Saved Results

Description

This API Endpoint is used to clear all text results saved on the camera. The return message contains count of deleted results and count of errors appeared during deletion.

Success Response

Sample Call

# login
curl --cookie cookies.log --cookie-jar cookies.log http://192.168.13.231/login --data "username=admin&password=secret"

# retrieve and save the snapshot
curl --cookie cookies.log --cookie-jar cookies.log -X PATCH http://192.168.13.231/text/remove-all

6.10   Delete Saved Results Using Pattern

Description

This API Endpoint is used to delete specified text results saved on the camera. The return message contains count of deleted results and count of errors appeared during deletion.

Note

When using pattern that contains character range there have to be used either quotation marks with backslash in front of squared brackets, or -g flag in front of URL. (See sample calls) Otherwise there will be returned error similar to the following one: "curl: (3) [globbing] bad range in column".

Success Response

Sample Call

# login
curl --cookie cookies.log --cookie-jar cookies.log http://192.168.13.231/login --data "username=admin&password=secret"

# delete plates starting with an "A"
curl --cookie cookies.log --cookie-jar cookies.log -X PATCH http://192.168.13.231/text/remove-pattern/A*

# delete plates ending with a "B"
curl --cookie cookies.log --cookie-jar cookies.log -X PATCH http://192.168.13.231/text/remove-pattern/*B

# delete plates containing "CD" as substring (at any position of the string)
curl --cookie cookies.log --cookie-jar cookies.log -X PATCH http://192.168.13.231/text/remove-pattern/*CD*

# delete plates having a "B" at the position 2 in the string
curl --cookie cookies.log --cookie-jar cookies.log -X PATCH http://192.168.13.231/text/remove-pattern/?B*

# delete plates starting either with an "A" or a "B"
curl --cookie test.txt --cookie-jar test.txt -X PATCH "http://192.168.13.245/text/remove-pattern/\[AB\]*"
curl --cookie test.txt --cookie-jar test.txt -g -X PATCH http://192.168.13.245/text/remove-pattern/[AB]*

# delete all plates
curl --cookie test.txt --cookie-jar test.txt -X PATCH http://192.168.13.245/text/remove-pattern/*

6.11   Retrieve a Live Image

Description

This API Endpoint returns a snapshot of the current image the Carrida camera. The image is encoded as JPEG.

Success Response

Sample Call

# login
curl --cookie cookies.log --cookie-jar cookies.log http://192.168.13.231/login --data "username=admin&password=secret"

# retrieve and save the snapshot
curl --cookie cookies.log --cookie-jar cookies.log http://192.168.13.231/live/snapshot > image.jpg

6.12   Current Apps

Description

This API Endpoint returns a list of currently running applications such as the ANPR server.

Success Response

[
    {
        "id": 0,
        "name": "default"
    }
]

Sample Call

# login
curl --cookie cookies.log --cookie-jar cookies.log http://192.168.13.231/login --data "username=admin&password=secret"

# get list
curl --cookie cookies.log --cookie-jar cookies.log http://192.168.13.231/live/apps

6.13   Current Status

Description

This API Endpoint returns common properties of the camera such as library versions, uptime and so on.

Success Response

{
  "addresses": "192.168.13.231",
  "carrida": {
    "active": "eu_006.dat",
    "anpr": "2.6.0",
    "classifiers": [
      "au_003.dat",
      "eu_006.dat",
      "nz_002.dat",
      "usa_004.dat"
    ],
    "lpr": "4.2.1"
  },
  "os": "Linux version 3.14.79-vc-z (root@vcbuilder2) (gcc version 4.8.4 (Ubuntu/Linaro 4.8.4-2ubuntu1~14.04.1) ) #2 SMP PREEMPT Wed Mar 21 11:12:01 CET 2018\n",
  "serialnumber": "4000702",
  "system-time": "2018-08-16T10:00:40.811701",
  "uptime": "1118641.87"
}

Sample Call

# login
curl --cookie cookies.log --cookie-jar cookies.log http://192.168.13.231/login --data "username=admin&password=secret"

# get list
curl --cookie cookies.log --cookie-jar cookies.log http://192.168.13.231/live/status

6.14   Restart ANPR Server

Description

This API Endpoint restarts the ANPR server on the camera.

Success Response

{
    "status": "ok",
    "msg": "Resetting..."
}

6.15   Reboot Camera

Description

This API Endpoint reboots the camera.

Success Response

{
    "status": "ok",
    "msg": "Rebooting..."
}