Skip to content

Developer's Guide

Quick start

Follow these steps to execute a query on a live video stream using the REST API. We will assume that the host name is u-query.

1. Test the REST API

U-Query servers a swagger UI to test the REST API. You can access it by opening this link in your browser (substitute u-query with your host name):

http://u-query:8051/swagger/

You can call API endpoints from the swagger UI to test the REST API via the link above.

For example you can get information about all the videos in the system by calling the GET /v1/videos endpoint.

2. Register indexer

Indexer nodes have to be registered once installation has been completed. In a standalone installation, this is not a separate node.

First test if there is any indexers registered by calling the GET /v1/indexers endpoint.

If there are no indexers registered, you can register one by calling the POST /v1/indexers endpoint with the following body:

{
  "ipAddress": "uquerypyindexer",
  "indexerPort": 54101,
  "videoStoragePort": 54101
}

For remote indexer use the ip address of the remote machine. For standalone installation, use uquerypyindexer. Use 54101 for both indexerPort and videoStoragePort.

Call GET /v1/indexers to test if it has been registered. An example response is:

{
  "indexers": {
    "9eefa8f6-907d-406c-9851-783546bf0d65": {
      "ipAddress": "uquerypyindexer",
      "indexerPort": 54101,
      "videoStoragePort": 54101
    }
  }
}

3. Add RTSP stream

A new RTSP stream can be added to the system with the POST /v1/videos/rtsp endpoint.

En example request:

{
  "indexerHostId": "9eefa8f6-907d-406c-9851-783546bf0d65",
  "videoMetadata": {
    "name": "Office main entrance",
    "technicalName": "office_main_entrance",
    "description": "The camera watching the main entrance of the office"
  },
  "rtspMetadata": {
    "rtspUrl": "rtsp://10.20.30.40:554/live.sdp",
    "retentionInSeconds": 86400
  }
}

Once the video is added, we can check its status:

  • Use the GET /v1/videos method to get all video status and config information.

  • Use the GET /v1/videos/{videoId}/frame/{time.milliseconds} method to get a frame as JPEG at a specific time.

4. Set indexing

No index is generated, unless explicitly started with the POST /v1/videos/{videoId}/index method.

The default indexing parameters are good for a wide range of use cases. Advanced options can be used to finetune the indexer.

Most frequently the user wants to override the FPS. En example request:

{
  "params": {
    "fps": 1
  }
}

Once the indexing has been, set we can query status again with the GET /v1/videos method.

5. Run a query

U-Query can have several different registered Query Types (use cases). The first step is to create a query from one of the Query Types and set its parameters. This can be done with the POST /v1/queries method.

As new Query Types can be registered to the system in runtime, query parameters can be set over a generic interface. However, for some specific Query Types, a typed structure is defined to make it easier to start with.

Currently, there is typed interface for the ObjectSearch Query Type.

To create a query we will need to know the Query Type ID and at least one video ID.

Use the GET /v1/queryTypes method to list the Query Types.

{
  "types": {
    "9fd8e821-ae59-4a7f-9db8-e3ebf139ddc3": {
      "name": "Generic Object Search",
      "description": "Generic object search. Filter detections by stream, time interval, object type, object attributes and free text.\n",
      "version": 1,
      "recommended": true
    }
  }
}

To list videos use the GET /v1/videos method.

{
  "indexedVideos": {
    "0cc5cbb0-b4ea-4508-90dd-a95e80594b4b": {
      "hostId": "8174b13f-9ec5-4102-90dd-117ce8941c59",
      "videoInfo": {
        "videoMetadata": {
          "name": "office2",
          "technicalName": "",
          "description": ""
        },
        "rtspMetadata": {
          "rtspUrl": "rtsp://....",
          "retentionInSeconds": 86400
        },
        "status": {
          "status": "RECORDING",
          "message": null,
          "progress": null
        },
        "start": {"millis": "1722493759625"},
        "end": {"millis": "1722507851700"}
      },
      "indexingInfo":
      ...
    }
  }
}

Now we can create a generic object search query with the POST /v1/queries method. This query look for persons and return 10 hits. The hits are sent to a Kafka topic test_query_1.

{
  "typeId": "9fd8e821-ae59-4a7f-9db8-e3ebf139ddc3",
  "name": "persons",
  "paramValues": {
    "objectSearchParams": {
      "videos": ["0cc5cbb0-b4ea-4508-90dd-a95e80594b4b"],
      "startTime": {"millis": "0"},
      "endTime": {"millis": "1822508157000"},
      "objectType": "person",
      "minConfidence": 0,
      "limit": 10,
      "windowSizeInMillisec": 5000,
      "output": {
        "broker": "broker:9092",
        "topic": "test_query_1"
      }
    }
  }
}

The call will return with the ID of the query: 

{
  "queryId": "0b530602-ec3f-4662-b309-c2587b62b8e5"
}

Once the query is created we need to start it by calling the POST /v1/queries/{queryId}/execution method.

If all went well, the query will start and the results will be sent to the Kafka topic.

It is recommended to use the kafkacat tool to test the Kafka topic. The tool can be installed with the following command:

sudo apt-get install kafkacat