TrafficEye.ai API

REST API to analyze images and extract valuable information related to objects, number plates, and vehicle details. Whether you're building toll systems, law enforcement applications, or contributing to smart city initiatives, our API is designed to meet your diverse needs.

API key

To access the API endpoints, you need to include your API key in the request header. You can find your API key here .

Endpoints

  • Endpoint: /info
  • HTTP Method: GET
  • Consumes Media Type: None
  • Produces Media Type: application/json
  • Headers:
    • apikey: Your API key

Data Parameters

  • apikey: Your API key

CURL Command Example

$ curl -X GET -H "apikey: YOUR_API_KEY_HERE" https://trafficeye.ai/info

Response

{
  "timestamp": 1697697742603,
  "engines": [
    {
      "engineName": "LPM",
      "engineType": "Detector",
      "engineVersion": "v7.6-2023-11-10-Ubuntu-18.04-hasp9.0",
      "moduleId": 802,
      "moduleVersion": "802-generic.gen-none-v7.2",
      "status": "RUNNING",
      "task": "DETECTION"
    },
    {
      "engineName": "LPM",
      "engineType": "OCR",
      "engineVersion": "v7.6-2023-11-10-Ubuntu-18.04-hasp9.0",
      "moduleId": 801,
      "moduleVersion": "801-generic.gen-gen-v7.9",
      "status": "RUNNING",
      "task": "OCR"
    },
    {
      "engineName": "LPM",
      "engineType": "OCR",
      "engineVersion": "v7.6-2023-11-10-Ubuntu-18.04-hasp9.0",
      "moduleId": 800,
      "moduleVersion": "800-frontal.lp-eu-v7.20",
      "status": "RUNNING",
      "task": "OCR"
    },
    {
      "engineName": "LPM",
      "engineType": "OCR",
      "engineVersion": "v7.6-2023-11-10-Ubuntu-18.04-hasp9.0",
      "moduleId": 553,
      "moduleVersion": "553-frontal.lp-na-v7.7",
      "status": "RUNNING",
      "task": "OCR"
    },
    {
      "engineName": "MMR",
      "engineType": "License Plate based",
      "engineVersion": "2.21.0-Ubuntu-18.04-x86_64-HASP",
      "moduleName": "MMR_VCMMGVCT_PREC_2023Q2.dat",
      "moduleVersion": "20230512",
      "status": "RUNNING",
      "task": "MMR"
    },
    {
      "engineName": "MMR",
      "engineType": "Box based",
      "engineVersion": "2.21.0-Ubuntu-18.04-x86_64-HASP",
      "moduleName": "MMRBOX_VCMMGVCT_PREC_2023Q2.dat",
      "moduleVersion": "20230513",
      "status": "RUNNING",
      "task": "MMR"
    }
  ]
}
Response Definitions

The following table describes each item in the response.

PropertyDescriptionType
timestampCurrent system time in milliseconds.integer
 enginesInformation about the SDK engines.array
costCost of the recognition. The cost of one automatic number plate recognition (ANPR) or make and model recognition (MMR) computation is 1 Eyecoin each. Maximal cost of recognition is 2 Eyecoins.integer
creditYour current credit balance in Eyecoins.integer

  • Endpoint: /recognition
  • HTTP Method: POST
  • Consumes Media Type: multipart/form-data
  • Produces Media Type: application/json
  • Headers:
    • apikey: Your API key

Data Parameters

  • apikey: Your API key
  • file: form data parameter containing input image
  • request: (optional) JSON object specifying the recognition request:
    • PropertyDescriptionType
    tasksAn array of requested computation tasks: "DETECTION", "OCR", "MMR" (case insensitive). Optional; if absent, all available tasks are applied depending on other request items.array
     combinationsAn array containing combinations of detected road user objects (box and/or plates). Road users in a combination belong to each other and are usually physically connected. If absent, the detections must be obtained by the detector using the DETECTION task. Allowed only in combination with the [OCR, MMR], [OCR] and [MMR] tasks (without DETECTION task).array
    requestedDetectionTypesAn array of object types to be detected by the detector: "BOX", "PLATE", "WINDSHIELD" (case insensitive). Optional; if absent, detections of all types supported by the detector will be returned. Allowed only if the tasks contain DETECTION.array
     roiThe area of the input image to be scanned by the detector. Optional; if absent, the whole image will be scanned. Allowed only if the tasks contain DETECTION.object
    detectionModuleIdThe three-digit LPM Detector identifier to be used for the detection (see the LPM modules table). If absent, the default one will be used. Allowed only if the tasks contain DETECTION.
    Allowed modules:
    • 802 - World Wide (default)
    		integer
    ocrModuleIdThe three-digit LPM Plate OCR identifier to be used for the OCR computation (see the LPM modules table). Optional; if absent, the default one will be used. Allowed only for the requestedDetectionTypes containing PLATE and tasks containing OCR.
    Allowed modules:
    • 553 - Americas
    • 555 - Middle East + Africa
    • 556 - Asia
    • 557 - Oceania
    • 800 - Europe
    • 801 - World Wide (default)
    		integer
    mmrPreferenceThe preferred type of object for which the MMR is computed. Either "BOX", or "PLATE" (case insensitive). Optional; if absent, BOX is preferred. Allowed only if the tasks contain MMR. Must not be combined with the mmrModuleNames containing a single module name.string
     mmrModuleNamesAn object containing the names of the binary modules used for the MMR computation. Optional; if absent, the default ones (depending on the mmrPreference) will be used. Allowed only if the tasks contain MMR.object
    saveImageSave the requested image to show in the history. Default is false.boolean
Notes:

Request can contain manual detections. In that case, the tasks must not contain "DETECTION" (the detector will not be used). Each roadUser (vehicle) can contain one box and/or one or more plates. The encapsulating combinations are sets of one or more roadUsers, e.g. a tractor with a trailer. The combinations structure will be projected into the response.

For the OCR of a manually specified plate, its position (all four corners) must be specified. In case of a license plate, the OCR needs to know whether it is a single-line or multi-line. The engine takes this information from isSingleLine, if available, or from dimension otherwise. If none of them is specified, the type will be estimated.

If a roadUser contains more than one detected object (and MMR task is requested), the MMR is computed using only one of them based on the mmrPreference. If there are multiple plates and one of them is to be used for the MMR, the license plate with the highest detection score will be selected.

If the mmrModuleNames element is specified with both box and plate, the box module will be used for the MMR Box computation, and the plate module will be used for the MMR Plate computation. If only one of these modules is specified, only the corresponding engine will be used for the MMR computation. The mmrPreference is allowed only when mmrModuleNames include both box and plate elements or when mmrModuleNames are not specified at all (using the default MMR modules).

For the MMR of a manually specified plate, its center coordinates (centerCol and centerRow), rotation and pixelsPerMeter needs to be known. If not specified, they can be estimated from the plate corners (position); however, for the more accurate estimation of pixelsPerMeter parameter, either dimension or isSingleLine should be also specified.

CURL Command Examples

Notes:

Content type of the request is multipart/form-data, where the inputs are stored in the form data fields.

Input image is referenced with filepath (starting with @) in the form field file.

Optional parameter request can be referenced with filepath (starting with @, referencing a text file containing JSON string) or can contain the whole JSON as a string (special characters must be escaped).

There are many conditions limiting the use of optional request items. If the element combination is not allowed, the Bad Request error code 400 is returned with a message describing the problem. Some of the illegal combinations:

  • tasks containing "DETECTION" with detections (if the detections element is present, no detector is used).
  • mmrPreference with tasks explicitly not containing "MMR" (the mmrPreference element is related to the MMR task).

If the requested detectionModuleId or ocrModuleId engines are not available, the Bad Request error code 400 is returned with a message describing the problem.

If the requested engines (specified explicitly by tasks, detectionModuleId or ocrModuleId elements) are available but not running, the Internal Server error code 500 is returned with a message describing the problem. This makes the difference between the following cases:

  • If the request contains tasks containing "MMR" (e.g.: "tasks":["DETECTION","OCR","MMR"]) and none of the MMR engines is running, the Internal Server error code 500 is returned.
  • If the request does not contain tasks element at all and all MMR engines are disabled, the server runs just the detection and plate OCR.

Response

{
  "combinations": [
    {
      "roadUsers": [
        {
          "box": {
            "position": {
              "topLeftCol": 207.98956,
              "topLeftRow": 254.33014,
              "bottomRightCol": 1550.7578,
              "bottomRightRow": 1209.3694,
              "score": 0.9650459
            },
            "occlusion": 0.0010549176,
            "truncated": false
          },
          "plates": [
            {
              "position": {
                "topLeftCol": 817.24255,
                "topLeftRow": 892.5229,
                "topRightCol": 1181.434,
                "topRightRow": 879.9859,
                "bottomRightCol": 1184.0664,
                "bottomRightRow": 956.45624,
                "bottomLeftCol": 819.875,
                "bottomLeftRow": 968.9932,
                "score": 0.9058306
              },
              "occlusion": 0.0011757425,
              "truncated": false,
              "clusterScore": 1.0,
              "isSingleLine": true,
              "type": {
                "value": "N",
                "score": 0.99995106
              },
              "text": {
                "value": "CV50070",
                "score": 0.9999991
              },
              "dimension": {
                "width": 520,
                "height": 110,
                "score": 1.0
              }
            }
          ],
          "windshield": {
            "position": {
              "topLeftCol": 360.14645,
              "topLeftRow": 341.9826,
              "topRightCol": 1299.7959,
              "topRightRow": 321.45706,
              "bottomRightCol": 1304.929,
              "bottomRightRow": 556.4519,
              "bottomLeftCol": 365.27963,
              "bottomLeftRow": 576.9774,
              "score": 0.9375341
            },
            "occlusion": 4.424591e-05,
            "truncated": false,
            "clusterScore": 1.0
          },
          "mmr": {
            "view": {
              "value": "frontal",
              "id": 1,
              "score": 0.9999329
            },
            "category": {
              "value": "CAR",
              "id": 2,
              "score": 0.9997303
            },
            "make": {
              "value": "VW",
              "id": 43,
              "score": 0.9999216
            },
            "model": {
              "value": "Passat",
              "id": 3569,
              "score": 0.9990373
            },
            "generation": {
              "value": "Mk VI (2005)",
              "id": 3691,
              "score": 0.9979515
            },
            "color": {
              "value": "WHITE",
              "id": 13,
              "score": 0.94161624
            },
            "tags": [
              {
                "name": "ambulance",
                "value": "no",
                "id": 14,
                "score": 0.99998176
              },
              {
                "name": "caravan",
                "value": "no",
                "id": 10,
                "score": 0.99946773
              },
              {
                "name": "fire_brigade",
                "value": "no",
                "id": 16,
                "score": 0.9999783
              },
              {
                "name": "law_enforcement",
                "value": "yes",
                "id": 11,
                "score": 1.0
              },
              {
                "name": "pickup",
                "value": "no",
                "id": 38,
                "score": 0.6701908
              },
              {
                "name": "push_bumper",
                "value": "no",
                "id": 30,
                "score": 0.9948259
              },
              {
                "name": "towed",
                "value": "no",
                "id": 51,
                "score": 0.9955255
              },
              {
                "name": "wood_truck",
                "value": "no",
                "id": 46,
                "score": 0.9893941
              }
            ],
            "input": {
              "box": {
                "topLeftCol": 207.98956,
                "topLeftRow": 254.33014,
                "bottomRightCol": 1550.7578,
                "bottomRightRow": 1209.3694
              }
            }
          }
        }
      ]
    }
  ],
  "engines": [
    {
      "task": "DETECTION",
      "moduleId": 802,
      "moduleVersion": "802-generic.gen-none-v7.2"
    },
    {
      "task": "OCR",
      "moduleId": 801,
      "moduleVersion": "801-generic.gen-gen-v7.9"
    },
    {
      "task": "MMR",
      "moduleName": "MMRBOX_VCMMGVCT_PREC_2023Q2.dat",
      "moduleVersion": "20230513"
    }
  ]
}
Notes:

If the request contains combinations (manual detections), the corresponding elements with the input values are projected into the combinations response element (in the same order). However, the position element is copied from the request to the response only if its encapsulating object contains some information added by the analysis. This means that a manually detected plate will be returned as an empty element if it is not processed by the OCR; a manually detected box will always be returned as an empty element.

The engines element lists only SDK engines, which were used to obtain the results. For example, if the request contains combinations (manual detections), there is no "DETECTION" task in the engines element.

Response Definitions

The following table describes each item in the response.

PropertyDescriptionType
 combinationsAn array containing combinations of detected road users.array
 enginesAn array containing information about the engines involved in obtaining the results.array
costCost of the recognition. The cost of one automatic number plate recognition (ANPR) or make and model recognition (MMR) computation is 1 Eyecoin each. Maximal cost of recognition is 2 Eyecoins.integer
creditYour current credit balance in Eyecoins.integer

Example Usage in Python

To help you get started quickly, here's a simple Python example demonstrating how to use our REST API for object detection. Make sure to replace IMAGE_PATH and API_KEY with your actual image URL and API key. 


                


                
                
Make & Model Recognition Classes

                

                    The API provides the class name and ID for each identified tag. To understand the output of the Make & Model Recognition module, you can download the classification classes file here