Retrieval API

Reference for the EPICS Archiver Appliance data retrieval HTTP API. For a worked example of constructing URLs and fetching data, see Fetch data.

Optional request parameters

In addition to the required pv, from, and to parameters, the following optional parameters are accepted by the getData endpoint.

fetchLatestMetadata: If true, an extra call is made to the engine as part of the retrieval to get the latest values of the various fields (DESC, HIHI etc).
retiredPVTemplate: If specified, the archiving information (PVTypeInfo) for the PV specified in this parameter is used as a template for PVs that do not exist in the system. This is intended principally for use with legacy PVs (PVs that no longer exist on the LAN and do not have a PVTypeInfo).

For example, all the data for legacy PVs could be consolidated into yearly partitions and stored on tape.
When a user places a request for this data, it could be restored to some standard folder, for example /arch/tape.
A template PV (probably paused), for example, TEMPLATE:PV is added to the system with one of its stores pointing to /arch/tape.
For all data retrieval requests, this template PV is specified as the value of the retiredPVTemplate argument. For example, http://archiver.slac.stanford.edu/retrieval/data/getData.json?pv=LEGACY:PV&from=…&retiredPVTemplate=TEMPLATE:PV.
Because the archiver does not find a PVTypeInfo for LEGACY:PV, it uses the PVTypeInfo for TEMPLATE:PV to determine data stores for LEGACY:PV.
The data in /arch/tape is used to fulfil the data retrieval request.
Once the user is done with the data for LEGACY:PV, the data in /arch/tape can be deleted.

timeranges: Get data for a sequence of time ranges. Time ranges are specified as a comma-separated list of ISO 8601 strings.
donotchunk: Use this to skip HTTP chunking of the response. This is meant for clients that do not understand chunked responses.
ca_count: This is passed on to an external ChannelArchiver as the value of the count parameter in the archiver.values XMLRPC call. This limits the number of samples returned from the ChannelArchiver; if unspecified, this defaults to 100000. If this is too large, you may see timeouts from the ChannelArchiver.
ca_how: This is passed on to an external ChannelArchiver as the value of the how parameter in the archiver.values XMLRPC call. This defaults to 0; that is, by default, we ask for raw data.

Response format

The response typically contains

seconds - This is the Java epoch seconds of the EPICS record processing timestamp. The times are in UTC; so any conversion to local time needs to happen at the client.
nanos - This is the nano second value of the EPICS record processing timestamp.
Other elements - This set includes the value, status, severity and many other optional fields stored by the appliance.

Point-in-time retrieval (Save/Restore API)

The archiver also exposes a separate endpoint for fetching the value of multiple PVs as of a single point in time. This is primarily aimed at save/restore applications. POST a JSON list of PV names to http://archiver.slac.stanford.edu/retrieval/data/getDataAtTime?at=2018-10-19T15:22:37.000-07:00&includeProxies=true where

at - This specifies the point in time in ISO 8601 format.
includeProxies - Optional; set this to true if you want to fetch data from external archiver appliances as part of this call. This defaults to false, so, by default, we do not proxy external appliances for this API call. As of now, we also do not support Channel Archiver integration for this API call.
searchPeriod - Optional argument to control how far back in time to go to find data. Defaults to about a month. EAA uses a chunked data store; this argument determines which chunks to include in the search. The syntax is as specified in java.time.Period.parse, for example, to specify a year, use P365D.

The response is a JSON dict of dicts with the name of the PV as the key. For example, here’s a call asking for the value of a few PVs as of 2018-10-22T10:40:00.000-07:00

$ curl -H "Content-Type: application/json"  -XPOST -s "http://localhost:17665/retrieval/data/getDataAtTime?at=2018-10-22T10:40:00.000-07:00&includeProxies=true" -d '["VPIO:IN20:111:VRAW", "ROOM:LI30:1:OUTSIDE_TEMP", "YAGS:UND1:1005:Y_BM_CTR", "A_nonexistent_pv" ]'
{
    "ROOM:LI30:1:OUTSIDE_TEMP": {
        "nanos": 823158037,
        "secs": 1540229999,
        "severity": 0,
        "status": 0,
        "val": 60.358551025390625
    },
    "VPIO:IN20:111:VRAW": {
        "nanos": 754373158,
        "secs": 1540229999,
        "severity": 0,
        "status": 0,
        "val": 5.529228687286377
    },
    "YAGS:UND1:1005:Y_BM_CTR": {
        "nanos": 164648807,
        "secs": 1537710595,
        "severity": 0,
        "status": 0,
        "val": 0.008066000000000002
    }
}