269 lines
6.9 KiB
ReStructuredText
269 lines
6.9 KiB
ReStructuredText
API
|
|
====
|
|
|
|
This document will provide an overview of ZoneMinder's API. This is work in progress.
|
|
|
|
Overview
|
|
^^^^^^^^
|
|
|
|
In an effort to further 'open up' ZoneMinder, an API was needed. This will
|
|
allow quick integration with and development of ZoneMinder.
|
|
|
|
The API is built in CakePHP and lives under the ``/api`` directory. It
|
|
provides a RESTful service and supports CRUD (create, retrieve, update, delete)
|
|
functions for Monitors, Events, Frames, Zones and Config.
|
|
|
|
Examples
|
|
^^^^^^^^
|
|
|
|
Here be a list of examples. Some results may be truncated.
|
|
|
|
You will see each URL ending in either ``.xml`` or ``.json``. This is the
|
|
format of the request, and it determines the format that any data returned to
|
|
you will be in. I like json, however you can use xml if you'd like.
|
|
|
|
(In all examples, replace 'server' with IP or hostname & port where ZoneMinder is running)
|
|
|
|
API Version
|
|
^^^^^^^^^^^
|
|
To retrieve the API version:
|
|
|
|
::
|
|
|
|
http://server/zm/api/host/getVersion.json
|
|
|
|
|
|
Return a list of all monitors
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
::
|
|
|
|
curl -XGET http://server/zm/api/monitors.json
|
|
|
|
Retrieve monitor 1
|
|
^^^^^^^^^^^^^^^^^^^
|
|
|
|
::
|
|
|
|
curl -XGET http://server/zm/api/monitors/1.json
|
|
|
|
|
|
Change State of Monitor 1
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
This API changes monitor 1 to Modect and Enabled
|
|
|
|
::
|
|
|
|
curl -XPOST http://server/zm/api/monitors/1.json -d "Monitor[Function]=Modect&Monitor[Enabled]:true"
|
|
|
|
Add a monitor
|
|
^^^^^^^^^^^^^^
|
|
|
|
This command will add a new http monitor.
|
|
|
|
::
|
|
|
|
curl -XPOST http://server/zm/api/monitors.json -d "Monitor[Name]=Cliff-Burton \
|
|
&Monitor[Function]=Modect \
|
|
&Monitor[Protocol]=http \
|
|
&Monitor[Method]=simple \
|
|
&Monitor[Host]=usr:pass@192.168.11.20 \
|
|
&Monitor[Port]=80 \
|
|
&Monitor[Path]=/mjpg/video.mjpg \
|
|
&Monitor[Width]=704 \
|
|
&Monitor[Height]=480 \
|
|
&Monitor[Colours]=4"
|
|
|
|
Edit monitor 1
|
|
^^^^^^^^^^^^^^^
|
|
|
|
This command will change the 'Name' field of Monitor 1 to 'test1'
|
|
|
|
::
|
|
|
|
curl -XPUT http://server/zm/api/monitors/1.json -d "Monitor[Name]=test1"
|
|
|
|
|
|
Delete monitor 1
|
|
^^^^^^^^^^^^^^^^^
|
|
|
|
This command will delete Monitor 1, but will _not_ delete any Events which
|
|
depend on it.
|
|
|
|
::
|
|
|
|
curl -XDELETE http://server/zm/api/monitors/1.json
|
|
|
|
|
|
Return a list of all events
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
::
|
|
|
|
curl -XGET http://server/zm/api/events.json
|
|
|
|
|
|
Note that events list can be quite large and this API (as with all other APIs in ZM)
|
|
uses pagination. Each page returns a specific set of entries. By default this is 25
|
|
and ties into WEB_EVENTS_PER_PAGE in the ZM options menu.
|
|
|
|
So the logic to iterate through all events should be something like this (pseudocode):
|
|
(unfortunately there is no way to get pageCount without getting the first page)
|
|
|
|
::
|
|
|
|
data = http://server/zm/api/events.json?page=1 # this returns the first page
|
|
# The json object returned now has a property called data.pagination.pageCount
|
|
count = data.pagination.pageCount;
|
|
for (i=1, i<count, i++)
|
|
{
|
|
data = http://server/zm/api/events.json?page=i;
|
|
doStuff(data);
|
|
}
|
|
|
|
|
|
Retrieve event Id 1000
|
|
^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
::
|
|
|
|
curl -XGET http://server/zm/api/events/1000.json
|
|
|
|
|
|
Edit event 1
|
|
^^^^^^^^^^^^^
|
|
|
|
This command will change the 'Name' field of Event 1 to 'Seek and Destroy'
|
|
|
|
::
|
|
|
|
curl -XPUT http://server/zm/api/events/1.json -d "Event[Name]=Seek and Destroy"
|
|
|
|
Delete event 1
|
|
^^^^^^^^^^^^^^
|
|
This command will delete Event 1, and any Frames which depend on it.
|
|
|
|
::
|
|
|
|
curl -XDELETE http://server/zm/api/events/1.json
|
|
|
|
|
|
Return a list of events for a specific monitor Id =5
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
::
|
|
|
|
curl -XGET http://server/zm/api/events/events/index/MonitorId:5.json``
|
|
|
|
|
|
Note that the same pagination logic applies if the list is too long
|
|
|
|
|
|
Return a list of events for a specific monitor within a specific date/time range
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
::
|
|
|
|
http://server/zm/api/events/events/index/MonitorId:5/StartTime >=:2015-05-15 18:43:56/EndTime <=:2015-05-16 18:43:56.json
|
|
|
|
|
|
To try this in CuRL, you need to URL escape the spaces like so:
|
|
|
|
::
|
|
|
|
curl -XGET "http://server/zm/api/events/index/MonitorId:5/StartTime%20>=:2015-05-15%2018:43:56/EndTime%20<=:2015-05-16%2018:43:56.json"
|
|
|
|
|
|
Return a list of events for all monitors within a specified date/time range
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
::
|
|
|
|
curl -XGET "http://server/zm/api/events/index/StartTime%20>=:2015-05-15%2018:43:56/EndTime%20<=:208:43:56.json"
|
|
|
|
|
|
|
|
Configuration Apis
|
|
^^^^^^^^^^^^^^^^^^^
|
|
|
|
The APIs allow you to access all the configuration parameters of ZM that you typically set inside the web console.
|
|
This returns the full list of configuration parameters:
|
|
|
|
::
|
|
|
|
curl -XGET http://server/zm/api/configs.json
|
|
|
|
|
|
Each configuration parameter has an Id, Name, Value and other fields. Chances are you are likely only going to focus on these 3.
|
|
|
|
(Example of changing config TBD)
|
|
|
|
Run State Apis
|
|
^^^^^^^^^^^^^^^
|
|
|
|
ZM API can be used to start/stop/restart/list states of ZM as well
|
|
Examples:
|
|
|
|
::
|
|
|
|
curl -XGET http://server/zm/api/states.json # returns list of run states
|
|
curl -XPOST http://server/zm/api/states/change/restart.json #restarts ZM
|
|
curl -XPOST http://server/zm/api/states/change/stop.json #Stops ZM
|
|
curl -XPOST http://server/zm/api/states/change/start.json #Starts ZM
|
|
|
|
|
|
|
|
Create a Zone
|
|
^^^^^^^^^^^^^^
|
|
|
|
::
|
|
|
|
curl -XPOST http://server/zm/api/zones.json -d "Zone[Name]=Jason-Newsted \
|
|
&Zone[MonitorId]=3 \
|
|
&Zone[Type]=Active \
|
|
&Zone[Units]=Percent \
|
|
&Zone[NumCoords]=4 \
|
|
&Zone[Coords]=0,0 639,0 639,479 0,479 \
|
|
&Zone[AlarmRGB]=16711680 \
|
|
&Zone[CheckMethod]=Blobs \
|
|
&Zone[MinPixelThreshold]=25 \
|
|
&Zone[MaxPixelThreshold]= \
|
|
&Zone[MinAlarmPixels]=9216 \
|
|
&Zone[MaxAlarmPixels]= \
|
|
&Zone[FilterX]=3 \
|
|
&Zone[FilterY]=3 \
|
|
&Zone[MinFilterPixels]=9216 \
|
|
&Zone[MaxFilterPixels]=230400 \
|
|
&Zone[MinBlobPixels]=6144 \
|
|
&Zone[MaxBlobPixels]= \
|
|
&Zone[MinBlobs]=1 \
|
|
&Zone[MaxBlobs]= \
|
|
&Zone[OverloadFrames]=0"
|
|
|
|
PTZ Control APIs
|
|
^^^^^^^^^^^^^^^^
|
|
PTZ controls associated with a monitor are stored in the Controls table and not the Monitors table inside ZM. What that means is when you get the details of a Monitor, you will only know if it is controllable (isControllable:true) and the control ID.
|
|
To be able to retrieve PTZ information related to that Control ID, you need to use the controls API
|
|
|
|
This returns all the control definitions:
|
|
::
|
|
|
|
curl http://server/zm/api/controls.json
|
|
|
|
This returns control definitions for a specific control ID=5
|
|
::
|
|
|
|
curl http://server/zm/api/controls/5.json
|
|
|
|
Host APIs
|
|
^^^^^^^^^^
|
|
|
|
ZM APIs have various APIs that help you in determining host (aka ZM) daemon status, load etc. Some examples:
|
|
|
|
::
|
|
|
|
curl -XGET http://server/zm/api/host/daemonCheck.json # 1 = ZM running 0=not running
|
|
curl -XGET http://server/zm/api/host/getLoad.json # returns current load of ZM
|
|
curl -XGET http://server/zm/api/host/getDiskPercent.json # returns in GB (not percentage), disk usage per monitor (that is, space taken to store various event related information,images etc. per monitor) ``
|
|
|