Carrida ANPR Server API documentation

Revision:1.2
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

The following API methods are specific to Carrida cameras. They are mostly used to get and set parameters related to HW/SW specific properties. The API offers most of the functionalities available in the Carrida ANPR Web Application. Implemented functionalities are split into the four separate groups, in correspondence to the organization of the mentioned Carrida Application. There are following groups available in the REST API implementation:

Beside mentioned groups there are also endpoints not belonging to any group, but used for login or to retrieve HW/SW information from the server. These endpoints will be mentioned in continuation of this section.

At the end there is a section General Error Responses which contains a list of errors that can occur in any API call.

Every description of an endpoint is followed by a short usage example using curl.

1.1   Login

Description

This API Endpoint is used to login with own credentials on the server. The login is required in order to perform any other action taken on the server. A session cookie will be generated and can be used for authentication. The cookie is valid for 365 days.

Format

URL Method URL Parameter Data Parameter
/login POST None login_string

Parameters

  • login_string:

    string with following format : "username=your_username&password=your_password"

Sample Call

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

1.2   Current Apps

Description

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

Format

URL Method URL Parameter Data Parameter
/live/apps GET None None

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
python3 camera.py -u admin -p secret -b http://192.168.13.231 --apps

Success Response

HTTP Status Code Method Sample Response
200 GET
[
    {
        "id": 0,
        "name": "default"
    }
]

1.3   Current Status

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

Format

URL Method URL Parameter Data Parameter
/live/status GET None None

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
python3 camera.py -u admin -p secret -b http://192.168.13.231 --status

Success Response

HTTP Status Code Method Sample Response
200 GET
{
  "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"
}

1.4   List all Properties

Description

Parameters from the t three mentioned groups (anpr, system, access, action) can be listed using this endpoint. As response it returns an array of properties for a section.

Section List

  • anpr
  • system
  • access
  • action

Format

URL Method URL Parameter Data Parameter
/properties/:section GET :section None

Parameters

  • section:

    string that defines the section for which the parameters should be listed

Sample Call

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

# get the system property list
curl --cookie cookies.log --cookie-jar cookies.log http://192.168.13.231/properties/anpr
python3 camera.py -u admin -p secret -b http://192.168.13.231 --properties system

Success Response

200
[
    "timezone",
    "dhcp",
    "ntp",
    "config",
    "time"
]

Error Response

HTTP Status Code Sample Response
404
{
    "status": "error",
    "msg": "Unkown component"
}

1.5   Retrieve a Live Image

Description

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

Format

URL Method URL Parameter Data Parameter
/live/snapshot GET None None

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
python3 camera.py -u admin -p secret -b http://192.168.13.231 --snapshot image.jpg

Success Response

HTTP Status Code Method Sample Response
200 GET image encoded as JPEG

2   System Properties

API Endpoints from this group are used for the configuration of operating system, such as time and network configuration. Furthermore there are endpoints in this section which are used to remotely restart/reboot the server/device. Via API editable system properties are listed in section Available System Properties.

2.1   Available System Properties

Property Name Value Format Description
time ISO 8601 formatted date This property represents the time configured on the operating system of the camera.
ntp true or false (enable or disable) NTP can be used to set the time (an alternative to setting it manually via the time property).
dhcp true (only activate) Set an IP address using DHCP. WARNING: The IP address may change after setting the property to true.
timezone Timezone string The current timezone of the system can be read and configured from this endpoint.
config INI configuration file INI file that contains the settings for the ANPR server (see anpr.ini on the camera for an example). NOTE: Only the Superuser can change this property.

2.2   Get and set System Properties

Description

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

Format

URL Method URL Parameter Data Parameter
/system/:property GET :property None
/system/:property PATCH :property :property=:value

Parameters

  • :property

    Name of a property from the list above.

  • :value

    Value to be set for specified property. The format of the value is also specified in the property list from above.

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"

# set a system property
curl --cookie cookies.log --cookie-jar cookies.log http://192.168.13.231/system/timezone --request PATCH
--data-urlencode "timezone=Europe/Vienna"

# get anpr.ini configuration
curl --cookie cookies.log --cookie-jar cookies.log http://192.168.13.231/system/config

# set anpr.ini configuration
curl --cookie cookies.log --cookie-jar cookies.log http://192.168.13.231/system/config --request PATCH
--data-urlencode config=@new-anpr.ini
python3 camera.py -u admin -p secret -b http://192.168.13.231 --get system time

python3 camera.py -u admin -p secret -b http://192.168.13.231 --change system time '2018-03-23T16:30:02+0100'

python3 camera.py -u admin -p secret -b http://192.168.13.231 --change system timezone 'Europe/Vienna'

python3 camera.py -u admin -p secret -b http://192.168.13.231 --get system config

ANPR_CONFIG=$(cat anpr.ini)
python3 camera.py -u admin -p secret -b http://192.168.13.231 --change system config "$ANPR_CONFIG"

Success Response

HTTP Status Code Method Sample Response
200 GET
{
    "time":"2019-05-14T05:48:20"
}
200 PATCH
{
    "status": "success",
    "msg": "Property changed"
}

Error Response

HTTP Status Code Method Sample Response
400 PATCH
{
    "status": "error",
    "msg": "Property value missing"
}
400 PATCH
{
    "status": "error",
    "msg": "Property not set (check the value)"
}
404 GET, PATCH
{
    "status": "error",
    "msg": "Unknown Property"
}

2.3   Digital IO

Description
On the camera with available Digital IO pins there can be used API Endpoint for pin status fetching and for activation/deactivation of available outputs. GET method can be used to fetch status of all pins and PATCH to set the status of an output pin.

Format

URL Method URL Parameter Data Parameter
/digitalio GET None None
/digitalio PATCH None :value

Parameters

  • :value

    Value that specifies output pin and the status to be set on given pin. Value is JSON struct with following format:

    {
      "index": pin number <integer>,
      "set": true to activate or false to deactivate selected pin
    }
    

Sample Call

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

# get status of digital IO pins
curl --cookie cookies.log --cookie-jar cookies.log -X GET http://192.168.13.231/digitalio

# activate status of the output pin #1
curl --cookie cookies.log --cookie-jar cookies.log -X PATCH http://192.168.13.231/digitalio --data '{"index":1, "set":true}'

Success Response

HTTP Status Code Method Sample Response
200 GET
{
    "Inputs": [
        {
            "#1": "active"
        },
        {
            "#2": "active"
        }
    ],
    "Outputs": [
        {
            "#1": "passive"
        },
        {
            "#2": "passive"
        }
    ]
}
200 PATCH
{
    "msg": "Output #1 deactivated",
    "status": "success"
}

Error Response

HTTP Status Code Method Sample Response
400 PATCH
{
    "status": "error",
    "msg": "Output index missing"
}
400 PATCH
{
    "status": "error",
    "msg": "Set value missing"
}
400 GET
{
    "status": "error",
    "msg": "Output index out of range (available output lines: [1-2])"
}

2.4   Reinitialize ANPR Server

Description
This API Endpoint reinitializes the ANPR server on the camera.

Format

URL Method URL Parameter Data Parameter
/camera/reinit POST None None

Sample Call

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

# reinitialize ANPR server
curl --cookie cookies.log --cookie-jar cookies.log --request POST https://192.168.13.231/camera/reinit
python3 camera.py -u admin -p secret -b http://192.168.13.231 --reinit

Success Response

HTTP Status Code Method Sample Response
200 POST
{
    "status": "ok",
    "msg": "Reinitialized"
}

2.5   Restart ANPR Server

Description

This API Endpoint is used to restart the ANPR server on the camera.

Format

URL Method URL Parameter Data Parameter
/camera/reset POST None None

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 -X POST http://192.168.13.231/camera/reset
python3 camera.py -u admin -p secret -b http://192.168.13.231 --reset

Success Response

HTTP Status Code Method Sample Response
200 POST
{
    "status": "ok",
    "msg": "Resetting..."
}

2.6   Reboot Camera

Description

This API Endpoint is used for reboot of the camera.

Format

URL Method URL Parameter Data Parameter
/camera/reboot POST None None

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 -X POST http://192.168.13.231/camera/reboot
python3 camera.py -u admin -p secret -b http://192.168.13.231 --reboot

Success Response

HTTP Status Code Method Sample Response
200 POST
{
    "status": "ok",
    "msg": "Rebooting..."
}

3   ANPR Properties

ANPR Properties are related to the ANPR server application. This endpoint allows the configuration of many properties and parameters related to the camera, trigger settings, Carrida engine and visualization.

In the next section there are parameters with primitive value formats listed. For the detailed description of listed properties please visit the Camera User Documentation.

This section additionally contains API endpoints used to get and set ROI properties and to fetch information and to edit classifier properties.

Note

New in the 4.5.0 release is the usage of section in the names of parameters. The names of parameters are constructed as following: section-parameter. As example parameter binning is since 4.5.0 renamed to camera-binning. In order to provide compatibility with previous releases old names are going to be supported in this release as well.

The reason for this change is the support of usage of overview camera on different linux boards. On those boards there are multiple camera parameters with the same name. The main camera parameters are on those boards to be set using camera as section name and overview camera parameters belong to the overview section.

3.1   Available ANPR Properties

Property Name Value Format Short Description
camera-binning true or false Camera low resolution on/off
camera-rotate_image floating number [-180.0-180.0] Rotation of the image before ANPR detection in degrees
camera-use_anpr_autolum true or false Activate/deactivate automatic Brightness Control
camera-min_shutter integer number [10-] Sensor minimum exposure time in micro sec
camera-min_gain integer number [0-10] Sensor minimum gain in dB
camera-max_shutter integer number [10-50000] Sensor maximum exposure time in micro sec
camera-max_gain integer number [0-10] Sensor maximum gain in dB
camera-accepted_brightness_min_amount float number [0.0.-100.0] Brightness Control minimum amount of well lighted pixels inside ROI (%)
camera-saturated_max_amount float number [0.0-100.0] Brightness Control maximum amount of accepted saturated pixels inside ROI
camera-lightenabled true or false Enable/Disable LED Flash
camera-lightduration integer number [0-1000] Duration of the flash in micro sec
camera-lightcurrent integer number [0-1500] Flash current in mA [0-1500]. Note: at VC cameras flash is off for values < 150 mA
camera-lightbrightness

integer number [0-2]

  • 0 ... Dark
  • 1 ... Middle
  • 2 ... Bright
Set the brightness of the flash
trigger-triggertype

integer number

  • 0 ... None
  • 1 ... IO Trigger
  • 2 ... TCP Trigger
  • 3 ... HTTP Trigger
Select the trigger source, or disable trigger usage.
trigger-iotriggermode

integer number

  • 1 ... SingleLine
  • 2 ... Start-Stop
  • 3 ... Start-Time
  • 4 ... Start-Sequence
  • 5 ... SingleShot
Set trigger mode in combination with IO lines
trigger-stopdio integer number Input line for stop signal, used for trigger mode Start-Stop
trigger-startdio integer number Input line for start signal, used for all trigger modes except free run (depending on camera HW)
trigger-startdiopolarity true or false Define the trigger signal polarity: high->low when enabled, low->high when disabled
trigger-stopdiopolarity true or false Define the stop signal polarity: high->low when enabled, low->high when disabled
trigger-tcptriggermode

integer number

  • 1 ... SingleLine
  • 2 ... Start-Stop
  • 3 ... Start-Time
  • 5 ... SingleShot
Set trigger mode in combination with tcp messages
trigger-httptriggermode

integer number

  • 1 ... SingleLine
  • 2 ... Start-Stop
  • 3 ... Start-Time
  • 5 ... SingleShot
Set trigger mode in combination with http requests
trigger-tcptriggerport integer number Set port on that the server will listen to start and stop tcp messages in case of usage of TCP trigger.
trigger-timemax integer number [100-999999] Max waiting time in millisec for ANPR reading after trigger signal, used in mode Start-Time
triggersequencelength integer number [0-] The number of frames read after trigger signal, used for trigger mode Start-Sequence
anpr_engine-mode

integer number

  • 1 ... Fastest
  • 2 ... Fast
  • 3 ... Standard
  • 4 ... High
  • 5 ... Best
Engine performance modes
anpr_engine-minletterheight integer number [6-1000] Minimum height of a plate letter in pixels
anpr_engine-maxletterheight integer number [0 - 1000] Maximum height of a plate letter in pixels
anpr_engine-maxplateangle integer number [0-90] Maximum allowed license plate rotation angle in degrees
anpr_engine-minplateconfidence integer number [0-100] Minimum confidence for a plate to be accepted, plates below this confidence will be dismissed
anpr_engine-mincontrast integer number [7-100] Min contrast to differentiate characters from the license plate. Reducing this parameter can increase reading performance but also processing time
anpr_engine-maxplates integer number [0-10, 0 = unlimited] Maximum number of plates which can be detected in a single image
anpr_engine-scalewidth integer number [1-200] Scale the image width by this factor (in percent) before ANPR processing
anpr_engine-scaleheight integer number [1-200] Scale the image height by this factor (in percent) before ANPR processing
anpr_engine-searchinverted

integer number

  • 0 ... disabled
  • 1 ... search
  • 2 ... always
Detection mode for white-on-black (inverted) License Plates (Disabled, Search only if no black-on-white plate found, or Always search). Search or Always will result in a lower processing frame rate
anpr_stream-streammode

integer number

  • 0 ... Single
  • 1 ... Parking
  • 2 ... Offline
  • 3 ... Freeflow
License plate sequence processing mode, Parking mode is recommended for access control
anpr_stream-minreadings integer number [0-20] Minimum detections of the same plate before accepting it-considering Maximum Characters Mismatch for comparison
anpr_stream-maxstringmatchingdistance integer number [0-10] Maximum difference between two license plates to be regarded as identical, recommended value: 1, 2
anpr_stream-noreadinterval integer number [0-99] Specifies the interval of images without plate reading after which the defined noread actions are triggered
anpr_stream-lowconflimit integer number [0-100] The threshold for which a confidence is considered low, this value must be >= Min Plate Confidence. Used in action type Low Confidence Read
application-hud_size

integer number

  • 0 ... small
  • 1 ... medium
  • 2 ... large
Size of the HUD
application-hud_position

integer number

  • 0 ... Upper Left
  • 1 ... Upper Right
  • 2 ... Lower Left
  • 3 ... Lower Right
Position of the HUD
application-cam_prefix string Text shown as info overlay
application-draw_info true or false Turn on/off info overlay in the HUD
application-draw_time true or false Turn on/off time display in the HUD
application-draw_date true or false Turn on/off date display in the HUD
application-draw_shutter true or false Turn on/off shutter display in the HUD
application-draw_gain true or false Turn on/off gain display in the HUD
application-displaylprrate true or false Display the current reading frame rate of the camera
application-displayframerate true or false Turn on/off camera framerate display in the HUD
application-visualiseplate true or false Draw licence plate result into the result image
application-visualisestate true or false Draw licence plate result into the result image
application-visualisecharconf true or false Draw single character confidences into the result image buffer
application-jpeg_compression integer number [1-100] JPEG compression level for live images in the user interface
application-maxhistoryentries integer number [0-10000] The maximum number of ANPR results which are kept in the history
application-historyhours integer number [0-10000]
The maximum time span in hours for which ANPR results are kept
in the history buffer
application-sendutf true or false Send result string UTF-8 encoded

3.2   Get and Set ANPR Properties

Description

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

Format

URL Method URL Parameter Data Parameter
/anpr/:property GET :property None
/anpr/:property PATCH :property :property=:value

Parameters

  • :property

    Name of one of properties listed above.

  • :value

    Value to be set for specified property. The format of the value is also specified in the property list from above.

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/anpr_engine-mode

# set an anpr property
curl --cookie cookies.log --cookie-jar cookies.log http://192.168.13.231/anpr/anpr_engine-mode --request PATCH --data-urlencode "anpr_engine-mode=1"
python3 camera.py -u admin -p secret -b http://192.168.13.231 --get anpr anpr_engine-mode

python3 camera.py -u admin -p secret -b http://192.168.13.231 --change anpr anpr_engine-mode 1

Success Response

HTTP Status Code Method Sample Response
200 GET
{
    :property: :value
}
200 PATCH
{
    "status": "success",
    "msg": "ok"
}

Error Response

HTTP Status Code Method Sample Response
400 PATCH
{
    "status": "error",
    "msg": "Property value missing"
}
400 PATCH
{
    "status": "error",
    "msg": "Invalid value given"
}
404 GET, PATCH
{
    "status": "error",
    "msg": "Unknown Property"
}

3.3   Get and set ROI properties

Description

API Endpoints from this section are used to get and set ROI properties. There are two ROIs used in the ALPR Server:

  • brightness ROI used by the Brightness Control
  • alpr ROI used by Carrida as region for plate detection

Use GET to fetch these properties from server and PATCH to set them.

Format

URL Method URL Parameter Data Parameter
/roi/:property GET selected ROI None
/roi/:property PATCH selected ROI :value

Parameters

  • :property

    ROI name (either brightness or alpr)

  • value

    JSON string with following format:

    • for brightness ROI:
    {
      "points":
        [
            { % point #1
                "x": "x_value <integer>"
                "y": "y_value <integer>"
            },
            { % point #2
                "x": "x_value <integer>"
                "y": "y_value <integer>"
            },
            ...,
            { % point #n (>= 3)
                "x": "x_value <integer>"
                "y": "y_value <integer>"
            }
        ]
    }
    
    • for alpr ROI:
    [
        { % Area #1
          "angle": {
                        "direction": "area_angle_direction<integer>",
                        "range": "area_angle_range<direction>"
                   },
          "name": "area_name",
          "points":
            [
                { % point #1
                      "x": "x_value <integer>"
                      "y": "y_value <integer>"
                },
                { % point #2
                    "x": "x_value <integer>"
                    "y": "y_value <integer>"
                },
                ...,
                { % point #n (>= 3)
                    "x": "x_value <integer>"
                    "y": "y_value <integer>"
                }
            ]
        },
        { % Area #2
          "angle": {
                        "direction": "area_angle_direction<integer>",
                        "range": "area_angle_range<direction>"
                   },
          "name": "area_name",
          "points":
            [
                { % point #1
                      "x": "x_value <integer>"
                      "y": "y_value <integer>"
                },
                { % point #2
                    "x": "x_value <integer>"
                    "y": "y_value <integer>"
                },
                ...,
                { % point #n (>= 3)
                    "x": "x_value <integer>"
                    "y": "y_value <integer>"
                }
            ]
        },
        ...
        { % Area #n (>= 1)
          "angle": {
                        "direction": "area_angle_direction<integer>",
                        "range": "area_angle_range<direction>"
                   },
          "name": "area_name",
          "points":
            [
                { % point #1
                      "x": "x_value <integer>"
                      "y": "y_value <integer>"
                },
                { % point #2
                    "x": "x_value <integer>"
                    "y": "y_value <integer>"
                },
                ...,
                { % point #n (>= 3)
                    "x": "x_value <integer>"
                    "y": "y_value <integer>"
                }
            ]
        }
    ]
    

Sample Call

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

# get ROI properties
curl --cookie cookies.log --cookie-jar cookies.log http://192.168.13.231/roi/brightnes
curl --cookie cookies.log --cookie-jar cookies.log http://192.168.13.231/roi/alpr

# set ROI properties
curl --cookie cookies.log --cookie-jar cookies.log -X PATCH http://192.168.13.231/roi/brightness --data
'{"points": [{"x": 22,"y": 320},{"x": 1220,"y": 150},{"x": 1226,"y": 734},{"x": 22,"y": 32}]}'
curl --cookie cookies.log --cookie-jar cookies.log -X PATCH http://192.168.13.231/roi/alpr --data
'[{"angle": {"direction": 0,"range": 128},"name": "area_1","points": [{"x": 1226,"y": 734},{"x": 374,"y": 778},
{"x": 338,"y": 70},{"x": 1226,"y": 112}]},{"angle": {"direction": 180,"range": 112},"name": "area_2","points":
[{"x": 422,"y": 730},{"x": 486,"y": 84},{"x": 26,"y": 116},{"x": 30,"y": 736}]},{"angle":
{"direction": 78,"range": 79},"name": "area_3","points": [{"x": 326,"y": 844},{"x": 368,"y": 60},
{"x": 28,"y": 116},{"x": 42,"y": 736}]}]'
python3 camera.py -u admin -p secret -b http://192.168.13.231 roi --get alpr

python3 camera.py -u admin -p secret -b http://192.168.13.231 roi --get brightness

python3 camera.py -u admin -p secret -b http://192.168.13.231 roi --set alpr pointdata.json

python3 camera.py -u admin -p secret -b http://192.168.13.231 roi --set brightness areadata.json

Success Response

HTTP Status Code Method Sample Response
200 GET
{
    "points": [
        {
            "x": 22,
            "y": 320
        },
        {
            "x": 1220,
            "y": 150
        },
        {
            "x": 1226,
            "y": 734
        },
        {
            "x": 22,
            "y": 32
        }
    ]
}
200 GET
[
   {
        "angle": {
            "direction": 0,
            "range": 128
        },
        "name": "area_1",
        "points": [
            {
                "x": 1226,
                "y": 734
            },
            {
                "x": 374,
                "y": 778
            },
            {
                "x": 338,
                "y": 70
            },
            {
                "x": 1226,
                "y": 112
            }
        ]
    },
    {
        "angle": {
            "direction": 180,
            "range": 112
        },
        "name": "area_2",
        "points": [
            {
                "x": 422,
                "y": 730
            },
            {
                "x": 486,
                "y": 84
            },
            {
                "x": 26,
                "y": 116
            },
            {
                "x": 30,
                "y": 736
            }
        ]
    },
    {
        "angle": {
            "direction": 78,
            "range": 79
        },
        "name": "area_3",
        "points": [
            {
                "x": 326,
                "y": 844
            },
            {
                "x": 368,
                "y": 60
            },
            {
                "x": 28,
                "y": 116
            },
            {
                "x": 42,
                "y": 736
            }
        ]
    }
]
200 GET
{
   "msg": "ROI updated",
   "status": "success"
}

Error Response

HTTP Status Code Method Sample Response
404 GET
{
    "status": "error",
    "msg": "Unknown property"
}
404 GET
{
    "status": "error",
    "msg": "Invalid value given"
}

3.4   Classifier Information

Description

This API Endpoint returns information regarding the currently used classifier.

Format

URL Method URL Parameter Data Parameter
/classifier/info GET None None

Sample Call

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

# get info
curl --cookie cookies.log --cookie-jar cookies.log http://192.168.13.231/classifier/info
python3 camera.py -u admin -p secret -b http://192.168.13.231 classifier --info

Success Response

HTTP Status Code Method Sample Response
200 POST
{
    "classifier": "West Europe",
    "states": [
        "Austria",
        "Belgium",
        "Bulgaria",
        "Czech Republic",
        "France", "Germany",
        "Hungary", "Italy",
        "Latvia", "Lithuania"
    ],
    "date": "2018-08-28",
    "name": "eu_001.dat"
}

3.5   List available Classifiers

Description

This API Endpoint returns a list of all available classifiers on the camera.

Format

URL Method URL Parameter Data Parameter
/classifier/list GET None None

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/classifier/list
python3 camera.py -u admin -p secret -b http://192.168.13.231 classifier --list

Success Response

HTTP Status Code Method Sample Response
200 POST
{
    "classifiers": [
      "au_003.dat",
      "eu_006.dat",
      "nz_002.dat",
      "usa_004.dat"
    ]
}

3.6   Modify and add Classifiers

Description

This API Endpoint returns a list of all available classifiers on the camera.

Format

URL Method URL Parameter Data Parameter
/classifier/file/:filename GET :filename None
/classifier/file/:filename PATCH :filename None
/classifier/file/:filename DELETE :filename None
/classifier/file/:filename POST :filename classifier=:upload_filename overvrite=:overwrite_flag

Parameters

  • filename

    filename of the classifier available on the device.

  • upload_filename

    Filename of the local classifier used to upload on the device.

  • overwrite_flag

    It can take values 0 or 1. If set to 1 the classifier will be overwritten in case that there already exists a file with the same filename.

Sample Call

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

# get classifier
curl --cookie cookies.log --cookie-jar cookies.log https://192.168.13.231/classifier/file/eu.dat > eu.dat

# select 'eu.dat as new default classifier
curl --cookie cookies.log --cookie-jar cookies.log -X PATCH https://192.168.13.231/classifier/file/eu.dat

# delete classifier 'eu.dat'
curl --cookie cookies.log --cookie-jar cookies.log -X DELETE https://192.168.13.231/classifier/file/eu.dat

# add a new classifier and overwrite it if there already exists a file with the same name
curl --cookie cookies.log --cookie-jar cookies.log https://192.168.13.231/classifier/file/eu.dat --form
classifier=@new_classifier.dat -d overwrite=1
python3 camera.py -u admin -p secret -b http://192.168.13.231 classifier --download localfile_eu.dat eu.dat

python3 camera.py -u admin -p secret -b http://192.168.13.231 classifier --default eu.dat

python3 camera.py -u admin -p secret -b http://192.168.13.231 classifier --delete eu.dat

python3 camera.py -u admin -p secret -b http://192.168.13.231 classifier --overwrite --upload localfile_eu.dat eu.dat

Success Response

HTTP Status Code Method Sample Response
200 GET file contents of specified classifier
200 PATCH
{
    "status": "success",
    "msg": "Classifier now active"
}
200 DELETE
{
    "status": "success",
    "msg": "Classifier deleted"
}
200 POST
{
    "status": "success",
    "msg": "Saved Classifier"
}

Error Response

HTTP Status Code Method Sample Response
404 GET, PATCH, DELETE
{
    "status": "error",
    "msg": "Classifier not found"
}
400 DELETE
{
    "status": "error",
    "msg": "Cannot delete active Classifier"
}
400 POST
{
    "status": "error",
    "msg": "Classifier already exists"
}
400 POST
{
    "status": "error",
    "msg": "Classifier contents not found in request"
}

4   Access Properties

API Endpoints from this section are used to handle Access feature that is consisted of two parts:

Available Lists

List Key List Name
white.txt Whitelist
black.txt Blacklist
ignore.txt Ignorelist

4.1   Lists handling

Description

List handling can be done using single API Endpoint with 3 separate methods.

*Retrieving an Access List*
With a GET request, a list of plates is returned. The plates can be filtered by sending the JSON containing a pattern field that contains a RegEx.
*Add Plates to an Access List*
With a POST request, a new entries 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

Beside these methods there is also an API endpoint used to download/upload(replace) the specified list file in its raw format. This endpoint is described in the next section.

Format

URL Method URL Parameter Data Parameter
/access/:listkey GET :listkey :filter (optional, can be empty)
/access/:listkey POST :listkey :entries
/access/:listkey DELETE :listkey :specifier

Parameters

  • listkey

    Key used to specify list from table from Available Lists.

  • filter

    Either empty (to request all list entries) or a JSON string containing a RegEx pattern to match license plates.

    {
      "pattern": "license-plate<regex>"
    }
    
  • entries

    JSON string of the following format:

    [
        {
          "always": true or false,  % if true specified plate will be always valid, otherwise it will be valid for defined schedules %
          "plate": "plate string",
          "schedules":  % if `always` is set to false, a schedule needs to be specified %
                      [
                        {
                            "period":
                            {
                              "start": "yyyy-mm-dd",
                              "end": "yyyy-mm-dd"
                            },
                            "time-span":
                              {
                                  "from": "hh:mm",
                                  "to": "hh:mm"
                              },
                              "weekdays": ["Mo", "We", "Fr"] % list of days for which entry is valid ("Mo", "Tu", "We", "Th", "Fr", "Sa", "Su") %
                          } % this can be repeated 0 or more times %
                      ]
        },
        .
        .
        . % multiple plates can be added with a single call %
        {
          "always": true, % no schedule needed, because `always` is set to true, plate will always be searched for %
          "plate": "plate string"
        }
    ]
    
  • specifier

    JSON string containing either an index of a list entry or a RegEx pattern to match license plates.

    {
       "index" : "entry-index<integer>"
    }
    
    {
       "pattern": "license-plate<regex>"
    }
    

Sample Call

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

# get all Whitelist entries
curl --cookie cookies.log --cookie-jar cookies.log http://192.168.13.231/access/white.txt

# get filtered Whitelist entries
curl --cookie cookies.log --cookie-jar cookies.log -X GET http://192.168.13.231/access/white.txt --data '{"pattern":"ABC*"}'

# delete entries using pattern
curl --cookie cookies.log --cookie-jar cookies.log -X DELETE http://192.168.13.231/access/white.txt --data '{"pattern":"ABC*"}'

# delete an entry using index
curl --cookie cookies.log --cookie-jar cookies.log -X DELETE http://192.168.13.231/access/white.txt --data '{"index":0}'

# add an entry to Whitelist
curl --cookie cookies.log --cookie-jar cookies.log -X POST http://192.168.13.231/access/white.txt --data
    '[{"always": false, "plate": "new","schedules":[{"period":{"end":"2018-10-31", "start":"2018-10-01"},
    "time-span":{"from":"16:13","to":"19:13"},"weekdays": ["Mo","Tu","We"]},
    {"period":{"end":"2018-11-3","start":"2018-12-01"},"time-span":{"from":"1:25","to":"12:00"},
    "weekdays": ["Fr","Sa", "So"]}] }]'
python3 camera.py -u admin -p secret -b http://192.168.13.231 access --list white.txt

python3 camera.py -u admin -p secret -b http://192.168.13.231 access --pattern 'ABC*' --list white.txt

python3 camera.py -u admin -p secret -b http://192.168.13.231 access --delete-pattern 'ABC*' white.txt

python3 camera.py -u admin -p secret -b http://192.168.13.231 access --delete-entry 0 white.txt

python3 camera.py -u admin -p secret -b http://192.168.13.231 access --add entry.json white.txt

Success Response

HTTP Status Code Method Sample Response
200 GET
[
    {
        "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"
    }
]
200 POST
{
    "status": "success",
    "msg": "Entry added."
}
200 DELETE
{
    "status": "success",
    "msg": "Entry removed."
}
200 DELETE
{
    "status": "success",
    "msg": "3 entries removed"
}

Error Response

HTTP Status Code Method Sample Response
400 POST
{
    "status": "error",
    "msg": "entry is missing \"plate\" field"
}
400 GET, DELETE
{
    "status": "error",
    "msg": "Invalid pattern"
}
400 POST
{
    "status": "error",
    "msg": "Invalid value given"
}
400 DELETE
{
    "status": "error",
    "msg": "Index out of range"
}
400 DELETE
{
    "status": "error",
    "msg": "Index invalid"
}
400 DELETE
{
    "status": "error",
    "msg": "No index or pattern given"
}
404 GET, POST, DELETE
{
    "status": "error",
    "msg": "Unknown list"
}

4.2   Read and write to Access Lists files

Description

While the API endpoints from the previous section provide a simplified interface to add/parse list entries, this endpoint is used to download and/or to upload (in this case replace) full list file. The format of those files is described in <link to the description>. This endpoint is recommended to use in order to make a backup of the lists or to share list files across multiple devices. Use GET method to retrieve the a file and the PUT method to write to it.

Format

URL Method URL Parameter Data Parameter
/access/:listkey/file GET :listkey None
/access/:listkey/file PUT :listkey list=:filename

Parameters

  • listkey

    Key used to specify list from table from Available Lists.

  • filename

    Filename of the local list file used for upload.

Sample Call

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

# read access list file
curl --cookie cookies.log --cookie-jar cookies.log http://192.168.13.231/access/white.txt/file

# write to access list file
curl --cookie cookies.log --cookie-jar cookies.log http://192.168.13.231/access/white.txt/file -X PUT --form list=@new-list.txt
python3 camera.py -u admin -p secret -b http://192.168.13.231 access --download access_list.txt white.txt

python3 camera.py -u admin -p secret -b http://192.168.13.231 access --upload access_list.txt white.txt

Success Response

HTTP Status Code Method Sample Response
200 GET ABCDEF;20190426-20190510;00:00-23:59(0111110)
200 PATCH
{
    "status": "success",
    "msg": "List set."
}

Error Response

HTTP Status Code Method Sample Response
400 GET, PATCH
{
    "status": "error",
    "msg": "List parameter missing."
}
400 GET, PATCH
{
    "status": "error",
    "msg": "Unknown list"
}

4.3   Retrieve the list of available action types

Description

API Endpoint for retrieving the list of available action types with related parameters. These actions can be used to define actions for the given event types. The event types can be listed by fething the action properties.

Format

URL Method URL Parameter Data Parameter
/available_actions GET None None

Sample Call

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

# read access list file
curl --cookie cookies.log --cookie-jar cookies.log http://192.168.13.231/available_actions
python3 camera.py -u admin -p secret -b http://192.168.13.231 actions --available

Note

Overview parameters are new in the 4.5.0 Release and are currently not used on Carrida cameras, but on other platforms only. On carrida cameras, or on the boards where overview is supported but not used those parameters have to be specified in order to add actions correctly, but upload overview parameter must be set to false.

Success Response

HTTP Status Code Method Sample Response
200 GET
{
    "digitalout": [
        "enable",
        "areas",
        "output line",
        "invert signal",
        "output duration",
        "non-blocking"
    ],
    "ftpdatabase": [
        "enable",
        "areas",
        "host",
        "user",
        "password",
        "filename",
        "entry pattern"
    ],
    "ftpupload": [
        "enable",
        "areas",
        "host",
        "user",
        "password",
        "naming pattern",
        "image upload",
        "final width",
        "final height",
        "crop percentage",
        "jpeg quality",
        "upload overview",
        "overview width",
        "overview heigth",
        "overview crop",
        "overview jpeg"
    ],
    "http": [
        "enable",
        "areas",
        "request type",
        "url",
        "user",
        "password",
        "message"
    ],
    "serial": [
        "enable",
        "areas",
        "message",
        "baud rate"
    ],
    "store": [
        "enable",
        "areas",
        "folder",
        "free space",
        "filename",
        "image upload",
        "final width",
        "final height",
        "crop percentage",
        "upload overview",
        "overview width",
        "overview heigth",
        "overview crop"
    ],
    "tcp": [
        "enable",
        "areas",
        "message",
        "ip",
        "port"
    ]
}

4.4   Get and set actions for the specified event type

Description

API Endpoints for manipulation of the actions for given event type. For each event type there can be defined one or multiple actions. As mentioned in previous section the action types together with their parameters can be listed using /available_actions endpoint. It is possible to define multiple actions of the same type for any event type. List of the event types together with their values is obtainable by fetching the action properties. Use GET method to retrieve the actions defined for specified property, PATCH method to add action to it and DELETE to delete action at the given index.

Event types

In the Release 4.3.2 there are following event types (action properties) available:

"blackmatch"
"blackmismatch"
"ignorematch"
"ignoremismatch"
"lcr"
"noread"
"read"
"whitematch"
"whitemismatch"
"wrongdir"

Format

URL Method URL Parameter Data Parameter
/action/:property GET event type None
/action/:property PATCH event type :action_struct
/action/:property DELETE event type :specifier

Parameters

  • property

    Event type from the list above.

  • action_struct

    In the section Retrieve the list of available action types is shown how to list action types available in the current release. As sample call there is given a list of action together with their names and parameters related to it. In order to define certain action for some event type there should be specified in a JSON string the name of the action and all parameters related to that action together with the values for those parameters. The JSON string should be constructed as follows:

    {
        "name": "action_name",
        "params": {
            "param #1 name": "param #1 value",
            "param #2 name": "param #2 value",
             ...,
            "param #n name": "param #n value"
        }
    }
    
  • specifier

    JSON of following format:

    {
       "index" : "entry-index<integer>"
    }
    

Sample Call

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

# read access list file
curl --cookie cookies.log --cookie-jar cookies.log -GET http://192.168.13.231/action/read

# add serial action to the read events
curl --cookie cookies.log --cookie-jar cookies.log  -X PATCH http://192.168.13.231/action/read --data '{"name":"serial",
"params":{"enable":false, "areas":-1, "baud rate":115200, "message":"message"}}'

# delete first action from the read action list
curl --cookie cookies.log --cookie-jar cookies.log  -X DELETE http://192.168.13.231/action/read --data '{"index":1}'
python3 camera.py -u admin -p secret -b http://192.168.13.231 actions --get read

python3 camera.py -u admin -p secret -b http://192.168.13.231 actions --add read action.json

python3 camera.py -u admin -p secret -b http://192.168.13.231 actions --delete read 1

Success Responses

HTTP Status Code Method Sample Response
200 GET
[
    {
        "name": "serial",
        "params": {
            "areas": "-1",
            "baud rate": "34324",
            "enable": "False",
            "message": "message"
        }
    }
]
200 POST
{
    "msg": "Action added",
    "status": "success"
}
200 DELETE
{
    "msg": "Action deleted",
    "status": "success"
}

Error Responses

HTTP Status Code Method Sample Response
404 GET
{
    "status": "error",
    "msg": "Unknown property"
}
404 PATCH
{
    "status": "error",
    "msg": "Unknown property"
}
404 PATCH
{
    "status": "error",
    "msg": "Invalid value given (wrong param names given)"
}
404 PATCH
{
    "status": "error",
    "msg": "Invalid value given (wrong action name given)"
}
404 PATCH
{
     "status": "error"
     "msg": "Invalid parameter (wrong index given)"
}

5   Results

This section contains API Endpoints for manipulation of results captured by the camera. There are two types of results available on the camera:

5.1   Retrieve a Live Result

Description

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

Format

URL Method URL Parameter Data Parameter
/live/result GET None None

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
python3 camera.py -u admin -p secret -b http://192.168.13.231 results --live

Success Response

HTTP Status Code Method Sample Response
200 GET
{
    "plates": [
        {
            "value": "LPR12345",
            "value-with-spaces": "LPR 123 45",
            "confidence": 90,
            "state": "AT",
            "state-confidence": 89,
            "area-indexes":"1",
            "area-names":"area_1",
            "direction-angle":-1,'
            "coordinates": {
                "x": 342,
                "y": 440,
                "width": 59,
                "height": 28
            },
            "rows": 1,
            "plate-color": "#FFFFFF",
            "characters-color": "#000000",
            "first-reading": true,
            "direction-angle": -1,
            "ending": "",
            "ending-short": "",
            "region": "",
            "region-short": "",
            "city": "",
            "characters": [
                {
                    "confidence":82,
                    "coordinates":{"height":35,"width":20,"x":767,"y":214},
                    "property":0,"row-index":0,"value":"L"
                },
                ...
            ]
        },
        ...
    ],

    "timestamp": "20190730T153720.050900",
    "message": "",
    "image": {
        "width": 1920,
        "height": 1080,
          "step": 1920,
          "type": 0,
          "data": "YmFzZTY0IGVuY29kZWQgaW1hZ2U......"
    }
}

Error Response

HTTP Status Code Method Sample Response
404 GET
{
    "status": "error",
    "msg": "No results found"
}

5.2   Text Results Handling

Description

This API Endpoint returns a specified amount of results that were last captured by the Carrida camera.
Filter results

With a GET request, that has a JSON body containing a field "count" holding a number, a list of results is returned. The amount of results is smaller or equal to the specified number. The "count" field is mandatory on every GET request. With an additional "include-images" field in the JSON body, the JPEG image of the result is returned as a base64 encoded string. There are also some optional parameters for filtering:

  • "plate" - if a result's plate matches the given string in this field, it will be included in the output
  • "state" - if a result's state matches the given string, it will be included
  • "min-confidence" and "max-confidence" - only results that have at least or at most the specified confidence in percent will be included
  • "min-state-confidence" and "max-state-confidence" - same as the above parameter, but with the state confidence of the result
  • "min-date" and "max-date" - specify a certain date range for the results in the format of "YYY-MM-DD", e.g. "2019-02-02" for the 2nd February 2019
  • "min-time" and "max-time" - specify a certain daytime range for the results in the format of "HH:MM", e.g. "13:00" for 1:00 pm.
Delete results
Using a DELETE request with a JSON body containg either the field "all" or "pattern", results can be deleted. If "all" is set, all results will be deleted. If "pattern" is set and contains a regular expression string, every result that can be matched with the RegEx pattern will be deleted.

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.

Format

URL Method URL Parameter Data Parameter
/text/results GET None JSON
/text/results DELETE None JSON

Sample Call

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

# retrieve 5 results
curl --cookie cookies.log --cookie-jar cookies.log -X GET http://192.168.13.231/text/results
--data '{"count":5}'

# retrieve 5 results with images
curl --cookie cookies.log --cookie-jar cookies.log -X GET http://192.168.13.231/text/results
--data '{"count":5,"include-images":true}'

# retrieve 10 results with a minimum confidence of 60 percent
curl --cookie cookies.log --cookie-jar cookies.log -X GET http://192.168.13.231/text/results
--data '{"count":10,"min-confidence":60}'

# retrieve 10 results that were saved between 11:00 and 13:00
curl --cookie cookies.log --cookie-jar cookies.log -X GET http://192.168.13.231/text/results
--data '{"count":10,"min-time":"11:00","max-time":"13:00"}'

# retrieve 3 results that were saved between february and march
curl --cookie cookies.log --cookie-jar cookies.log -X GET http://192.168.13.231/text/results
--data '{"count":3,"min-date":"2019-02-01","max-date":"2019-03-31"}'

# retrieve 5 results which states contain the pattern 'AT'
curl --cookie cookies.log --cookie-jar cookies.log -X GET http://192.168.13.231/text/results
--data '{"count":5,"state": "*AT*"}'

# delete plates starting with an "A"
curl --cookie cookies.log --cookie-jar cookies.log -X GET http://192.168.13.231/text/results --request DELETE
--data '{"pattern": "A*"}'

# delete plates ending with a "B"
curl --cookie cookies.log --cookie-jar cookies.log http://192.168.13.231/text/results --request DELETE
--data '{"pattern": "*B"}'

# delete plates starting either with an "A" or a "B"
curl --cookie cookies.log --cookie-jar cookies.log http://192.168.13.231/text/results --request DELETE
--data '{"pattern": "[AB]*"}'

# delete results containing the string "ABC"
curl --cookie cookies.log --cookie-jar cookies.log http://192.168.13.231/text/results --request DELETE
--data '{"pattern": "*ABC*"}'

# delete all results
curl --cookie cookies.log --cookie-jar cookies.log http://192.168.13.231/text/results --request DELETE
--data '{"all": true}'
python3 camera.py -u admin -p secret -b http://192.168.13.231 results --text 5

python3 camera.py -u admin -p secret -b http://192.168.13.231 results --text 5 --include-images

python3 camera.py -u admin -p secret -b http://192.168.13.231 results --text 10 --min-confidence 60

python3 camera.py -u admin -p secret -b http://192.168.13.231 results --text 10 --min-time 11:00 --max-time 13:00

python3 camera.py -u admin -p secret -b http://192.168.13.231 results --text 3 --min-date 2019-02-01 --max-date 2019-03-31

python3 camera.py -u admin -p secret -b http://192.168.13.231 results --text 5 --state-pattern '*AT*'

python3 camera.py -u admin -p secret -b http://192.168.13.231 results --delete-pattern 'A*'

python3 camera.py -u admin -p secret -b http://192.168.13.231 results --delete-pattern '*B'

python3 camera.py -u admin -p secret -b http://192.168.13.231 results --delete-pattern '[AB]*'

python3 camera.py -u admin -p secret -b http://192.168.13.231 results --delete-pattern '*ABC*'

python3 camera.py -u admin -p secret -b http://192.168.13.231 results --delete-all

Success Response

HTTP Status Code Method Sample Response
200 GET
{
  "results":
      [
          {
              "plates": [
                  {
                      "value": "LPR12345",
                      "value-with-spaces": "LPR 123 45",
                      "confidence": 90,
                      "state": "AT",
                      "state_confidence": 89,
                      "position": {
                          "x": 342,
                          "y": 440,
                          "width": 59,
                          "height": 28
                      },
                      "rows": 1,
                      "plate-color": "#FFFFFF",
                      "character-color": "#000000",
                      ...
                      ...
                      ...
                  }
              ],
              "timestamp": 1525690269,
              "message": ""
          },
          ...
          ...
          ...
      ]
}
200 DELETE
{
    "status": "success",
    "msg": "ok",
    "removed_results": 3,
    "deletion_errors": 0
}

Error Response

HTTP Status Code Method Sample Response
400 GET
{
  "status": "error",
  "msg": "\"count\" not specified"
}
400 GET
{
    "status": "error",
    "msg": "Invalid Pattern for \"plate\""
}
400 GET
{
    "status": "error",
    "msg": "Invalid Pattern for \"state\""
}
400 GET
{
    "status": "error",
    "msg": "\"min-confidence\" should be a number"
}
400 GET
{
    "status": "error",
    "msg": "\"max-confidence\" should be a number"
}
400 GET
{
    "status": "error",
    "msg": "\"min-state-confidence\" should be a number"
}
400 GET
{
    "status": "error",
    "msg": "\"max-state-confidence\" should be a number"
}
400 GET
{
    "status": "error",
    "msg": "\"min-date\" should look like YYYY-MM-DD"
}
400 GET
{
    "status": "error",
    "msg": "\"max-date\" should look like YYYY-MM-DD"
}
400 GET
{
    "status": "error",
    "msg": "\"min-time\" should look like HH:MM"
}
400 GET
{
    "status": "error",
    "msg": "\"max-time\" should look like HH:MM"
}
400 DELETE
{
    "status": "error",
    "msg": "No criteria for deletion given"
}

5.3   Export all Results as ZIP archive

Description

This API Endpoint returns a ZIP archive file containing all the gathered results by the Carrida camera as CSV file. The images are included.

Format

URL Method URL Parameter Data Parameter
/export/results GET None None

Sample Call

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

# save ZIP archive
curl --cookie cookies.log --cookie-jar cookies.log http://192.168.13.231/export/results > results.zip
python3 camera.py -u admin -p secret -b http://192.168.13.231 --export results.zip

Success Response

HTTP Status Code Method Sample Response
200 GET ZIP archive

6   Deprecated API methods

6.1   Retrieve saved Results (without images)

Description

This API Endpoint returns a specified count 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 anpr 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.

Format

URL Method URL Parameter Data Parameter
/text/results/:count GET :count None

Parameters

  • count

    Number of results to be parsed by the server and returned as JSON.

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

Success Response

HTTP Status Code Method Sample Response
200 GET
[
    {
        "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": ""
    },
    ...
    ...
    ...
]

6.2   Retrieve saved 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.

Format

URL Method URL Parameter Data Parameter
/text/results-with-images/:count GET :count None

Parameters

  • count

    Number of results to be parsed by the server and returned as JSON.

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

Success response

HTTP Status Code Method Sample Response
200 GET
[
    {
        "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......"
        }
    },
    ...
    ...
    ...
]

6.3   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, which appeared during deletion.

Format

URL Method URL Parameter Data Parameter
/text/remove-all PATCH None None

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

Success Response

HTTP Status Code Method Sample Response
200 PATCH
{"deletion_errors": 0,
"msg": "ok", "removed_results": 4, "status": "success"}

6.4   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".
Format
URL Method URL Parameter Data Parameter
/text/remove-pattern/:pattern PATCH :pattern None

Parameters

  • pattern

    String used as pattern for entry deletion.

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 cookies.log --cookie-jar cookies.log -X PATCH "http://192.168.13.231/text/remove-pattern/\[AB\]*"
curl --cookie cookies.log --cookie-jar cookies.log -g -X PATCH http://192.168.13.231/text/remove-pattern/[AB]*

# delete all plates
curl --cookie cookies.log --cookie-jar cookies.log -X PATCH http://192.168.13.231/text/remove-pattern/*

Success Response

HTTP Status Code Method Sample Response
200 PATCH
{
    "deletion_errors": 0,
    "msg": "ok",
    "removed_results": 4,
    "status": "success"
}

7   General Error Responses

In the documentation for each API Endpoint there are errors listed that are specific to that Endpoint. This section contains errors that can occur on every request. Those errors are produced in following cases:

Following table contains example errors that can be produced if one of listed cases appears:

HTTP Status Code Sample Response
400
{
    "status": "error",
    "msg": "Invalid value given."
}
400
{
    "status": "error",
    "msg": "The browser (or proxy) sent a request that this server could not understand."
}
403
{
   "msg": "Token invalid",
   "status": "error"
}
405
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<title>405 Method Not Allowed</title>
<h1>Method Not Allowed</h1>
<p>The method is not allowed for the requested URL.</p>
500
{
    "status": "error",
    "msg": "Request failed"
}