Skip to content

Developer's Guide

Quick start

Follow these steps to execute a query on a live video stream using the REST API.

Info

In the following guide, it is assumed that the host name is u-query (substitute u-query with your host name).

Test the REST API

U-Query serves a swagger UI to test the REST API. You can access it from your browser:

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

API endpoints can be called from the swagger UI to test the REST API via the link above; to get information about all the videos in the system, for example, call the GET /v1/videos endpoint.

Register indexer

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

  1. Test if there are any indexers registered by calling the GET /v1/indexers endpoint.

  2. 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
}
  • ipAddress: For remote indexers, use the IP address of the remote machine. For standalone installation, the value should be uquerypyindexer.
  • indexerPort and videoStoragePort: Use port 54101
  1. Call GET /v1/indexers to test if the indexer has been registered. An example response is:
Response example
{
  "indexers": {
    "9eefa8f6-907d-406c-9851-783546bf0d65": {
      "ipAddress": "uquerypyindexer",
      "indexerPort": 54101,
      "videoStoragePort": 54101
    }
  }
}

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, its status can be checked:

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

Set indexing

No index is generated by default, unless explicitly started with the POST /v1/videos/{videoId}/index method. The default indexing parameters are ideal for a wide range of use cases. To fine-tune the indexer, advanced options can be used.

  1. Start indexing: POST /v1/videos/{videoId}/index

  2. Typically, the default value for the FPS should be changed to fit the user's needs. An example request:

{
  "params": {
    "fps": 1
  }
}
  1. Once the indexing has been set, status can be queried again with the GET /v1/videos method.

Run a query

U-Query can have several different registered Query Types (use cases).

As new Query Types can be registered during runtime, query parameters can be set over a generic interface. For some specific Query Types, a typed structure is defined; currently, typed interface exists only for the ObjectSearch Query Type.

To create a query, the Query Type ID and at least one video ID must be known.

  1. Use the GET /v1/queryTypes method to list Query Types.
Example response
{
  "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
    }
  }
}
  1. Use the GET /v1/videos method to list videos.
Example response
{
  "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":
      ...
    }
  }
}
  1. Create a generic object search query with the POST /v1/queries method. The example query below looks for person objects and returns 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"
      }
    }
  }
}

You will find the queryID in the response:

Example response
{
  "queryId": "0b530602-ec3f-4662-b309-c2587b62b8e5"
}
  1. 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 topic. It can be installed with the following command:

sudo apt install kafkacat