Next Previous Up Contents
Next: Authentication
Up: Input Schemes
Previous: class

#### 5.3.7 `hapi`

Usage: `:hapi:<server-url>;<dataset>;start=<start>;stop=<stop>[;maxChunk=<n>][;failOnLimit=<true|false>][;<key>=<value>...]`

Generates a table by interacting with a HAPI service. HAPI, the Heliophysics Data Application Programmer’s Interface is a protocol for serving streamed time series data.

In most cases it is not essential to use this scheme, since pointing the HAPI table input handler at a URL with suitable parameters will be able to read the data, but this scheme provides some added value by negotiating with the server to make sure that the correct version-sensitive request parameter names and the most efficient data stream format are used, and can split the request into multiple chunks if the service rejects the whole query as too large.

The first token in the specification is the base URL of the HAPI service, the second is the dataset identifier, and others, as defined by the HAPI protocol, are supplied as `<name>=<value>` pairs, separated by a semicolon ("`;`") or an ampersand ("`&`"). The `start` and `stop` parameters, giving ISO-8601-like bounds for the interval requested, are required.

Additionally, some parameters may be supplied which affect load behaviour but are not transmitted to the HAPI service. These are:

`maxChunk=<n>`
  divides the request up into at most `<n>` smaller chunks if the server refuses to supply the whole range at once.
`failOnLimit=<true|false>`
  determines what happens if the service does refuse to serve the whole range (in chunks or otherwise); if true, the table load will fail, but if false as many rows as are available will be loaded.

Some variant syntax is permitted; an ampersand ("`&`") may be used instead of a semicolon to separate tokens, and the names "`time.min`" and "`time.max`" may be used in place of "`start`" and "`stop`".

Note that since semicolons and/or ampersands form part of the syntax, and these characters have special meaning in some contexts, it may be necessary to quote the scheme specification on the command line.

Example:

    :hapi:https://vires.services/hapi;GRACE_A_MAG;start=2009-01-01T00:00:00;stop=2009-01-01T00:00:10;parameters=Latitude,Longitude
    +--------------------------+---------------+---------------+
    | Timestamp                | Latitude      | Longitude     |
    +--------------------------+---------------+---------------+
    | 2009-01-01T00:00:03.607Z | -74.136357526 | -78.905620222 |
    | 2009-01-01T00:00:05.607Z | -74.009378676 | -78.884853931 |
    | 2009-01-01T00:00:06.607Z | -73.945887793 | -78.874590667 |
    | 2009-01-01T00:00:07.607Z | -73.882397005 | -78.864406236 |
    | 2009-01-01T00:00:08.607Z | -73.818903534 | -78.854396448 |
    +--------------------------+---------------+---------------+

Next Previous Up Contents
Next: Authentication
Up: Input Schemes
Previous: class

STILTS - Starlink Tables Infrastructure Library Tool Set
Starlink User Note256
STILTS web page: http://www.starlink.ac.uk/stilts/
Author email: m.b.taylor@bristol.ac.uk
Mailing list: topcat-user@jiscmail.ac.uk