External API

Integrating CaptureGRID with an external system

CaptureGRID can be integrated with an external system by using the External API feature. This provides two key channels of communication:

  • Publisher of event information

  • Server for handling command requests

The External API uses the ZeroMQ library for managing the communication transport layer. See http://zeromq.org for more information on how to use ZeroMQ from your system. This also defines the programming model for using the event publisher and request/reply server, as these are implementated as ZeroMQ socket endpoints.

All messages passed over the External API are encoded in JSON format. See http://json.org for more information on how to handle this type of message format.


Sample python code for the External API is available at:


Listening to Events

The event publisher will broadcast messages about important events that happen inside the app. This includes:

  • When a new photo is taken

  • When a photo changes state (downloaded/deleted/renamed etc)

  • When a new camera is detected

  • When a camera changes state

  • When a camera property changes state

Below is an example of a listener application written in Python. This can be run from the command line, and simply prints out each message that is received from the app’s publisher endpoint.

#!/usr/bin/env python3
# Copyright (c) 2015-2019, Kuvacode Oy
# All rights reserved. No warranty, explicit or implicit, provided.

import zmq

def main():
    context = zmq.Context()
    sub_address = "tcp://"
    sub_socket = context.socket(zmq.SUB)
    sub_socket.setsockopt(zmq.SUBSCRIBE, b"")
    print("Opened listener to: {0}".format(sub_address))
    while (True):
        raw = sub_socket.recv()
        json_msg = raw.decode("utf-8")
        print("Received: {0}".format(json_msg))

if __name__ == '__main__':


For example, the text below shows the output from this after a new photo has been taken:

Opened listener to: tcp://
Received: {
  "msg_type": "Event",
  "msg_id": "PhotoUpdated",
  "msg_seq_num": 187,
  "msg_user_id": 0,
  "msg_result": true,
  "NetworkAddress": "",
  "NetworkEndpoint": "tcp://",
  "PhotoSelection": "Single",
  "PhotoKey": "5752505c-07f1-4cd3-ab47-d70b4f8a5d02",
  "CameraKey": "Nikon Corporation|D5300|4337807",
  "PhotoLocation": "Local Disk",
  "PhotoOriginalName": "DSC_0000.NEF",
  "PhotoComputedName": "SSP_30.nef",
  "PhotoDateCaptured": "20190530 19:53:07.000",
  "PhotoOrigin": "ui",
  "PhotoFormat": "Raw",
  "PhotoOrientation": "None",
  "PhotoAperture": "5",
  "PhotoShutterSpeed": "1/10",
  "PhotoISO": "400",
  "PhotoFocalLength": "52.0",
  "PhotoWidth": 6000,
  "PhotoHeight": 4000,
  "PhotoFilesize": 24755185,
  "PhotoIsImage": true,
  "PhotoSequenceNum": 30,
  "PhotoBatchNum": 141,
  "PhotoHash": "095A4317"

Sending Requests

The request/reply server inside the app can handle requests to do various actions such as:

  • Connect/Disconnect camera

  • Take photo

  • Download/rename/delete photo

  • Change camera property

  • Auto focus camera

  • Change sequence/batch number


For further documentation see the public git repo:


And in particular the API documenation stored here:


Configuring the External API

By default the External API is disabled. To enable it, go to the Network/API tab in the Options window and enable the checkbox, as shown below. This also allows customisation of the ZeroMQ endpoints that are used for the event publisher and request/reply server, so that it can be opened up for access from other computers on a network.