Argus Archive Catalog Service

Irv.Elshoff@Deltares.NL
12 May, 2013

Introduction

The Argus archive catalog service (AACS) produces lists of URLs to Argus images and data products in plain text or JSON format that match specified search criteria.

Argus images are timestamped with the epoch time when they were captured.  All AACS queries and replies use epoch times. Conversion to/from other date/time formats is the responsibility of client software.

Query Syntax

Queries are made using the GET method of HTTP(S).  The general form of a query is:

http://argus-public.deltares.nl/catalog/?parameter1=value1&parameter2=value2&...

Zero of more parameter/value pairs may be specified, in any order.  The following parameters are recognized:

site=string Limit search results to the specified site (e.g., aberdees, egmond, sete, zandmotor). If this clause is absent, a list of existing sites and the epoch times of the earliest and latest available data is produced; all other clauses except output will be ignored in this case.
startEpoch=integer
Specifies the earliest time for which results are returned. If omitted or zero, only the single most recent image or product is returned (useful only in combination with other clauses).  A negative value means "now" minus the specified number of seconds.
endEpoch=integer Specifies the latest time for which results are returned.  If omitted or non-positive, the current time is used.
camera=integer Limit results to the specified camera.  This only applies to raw image data (snap, timex, stack, etc.).
type=string The type of image or data product to return.  If unspecified, everything is returned.  The following types are recognized:
  • Basic images: snaptimexvarminmax
  • Pixel time series: stack
  • Merges: planpan
  • Other data products to be added in the future: shoreline, bathy, ???
timeOfDay=integer Limit results to the specified time of day, expressed as minutes after midnight, plus or minus 2.5 minutes, in the local time zone.  Argus images are typically collected on the whole and half hour.  Stacks can start any time, but usually last 17 minutes.
tide=state (Not yet fully implemented.) Limit results to data products near high or low tide. May not coexist with a timeOfDay clause.
output=format Produce output in the specifed format (see below):
  • list = Simple text output. This is the default.
  • json = JSON output.
limit=integer Limit the number of URLs to the specified value.  Default is 1000, which is also the maximum for anonymous users.  A negative value limits output to most recent results.  Zero means no limit (excercise caution with wide queries; there are 20 million entries in the database).
user=string
auth=string
Identifies the user for non-public data.  If an autorization code is required for the user, the HTTPS protocol must be used.

Output Format

Output is either in plain text or JSON.

Plain text records are delimited by a single newline ("\n").  Site list lines contain three alphanumeric fields delimited by a single space: the site name and the epoch times of the oldest and youngest image or data available. Image lists are one full URL per line.

JSON output for the site list is an array of objects that looks like:
[
{ "site" : "string", "startEpoch" : integer, "endEpoch" : integer },
...
]
JSON output for URL image lists looks like:
{
"urlPrefix" : "string",
"urlSuffix" : "string",
"data" :
[
{ "path" : "string", "epoch" : integer, "camera" : integer, "type" : "string" },
...
]
}
In the preceeding examples whitespace is used for readability.  Actual output will usually not contain whitespace, and as such not deemed human-readable.

Most output fields correspond to query parameters.   In order to download actual data using JSON output, URL's must be constructed by concatenating the urlPrefix, path and urlSuffix fields.  Without the URL prefix and suffix the path given is usable if one knows a prefix (root directory) for a local or network file system.

URL lists are normally ordered in ascending epoch time. If a negative limit is specified the output order is descending epoch time.

If the search critera are invalid, or there are problems on the server, no results will be produced.  There are no error codes or other diagnostic messages.  An error is indistinguisable from an empty search result. [ Is this acceptable? ]

Users

While Argus data is in general open to everyone, some data may be restricted to a select group of users. By providing a user name, and perhaps an authorization code, more data may be become visible.

Anonymous users only have access to the last year's worth of images, no derived data, and are limited to 1000 results per query. [ Perhaps controversial. ]