TableOfContents(3)

Heliophysics Events Registry API

Introduction

http://www.lmsal.com/helio-informatics/hpkb/images/HER_arch.jpg

Both SolarSoft and the [http://www.lmsal.com/helio-informatics/hpkb/hek_isolsearch.html iSolSearch] web application lets users query the Heliophysics Events Registry (HER) in an interactive manner (much like Google Maps). iSolSearch interacts with HER by means of our web application programming interface (API). The API enables developers to create new third party clients for HER as well as scientists to write software code which interact with HER in an automated manner.

Usage of an API function amounts to using HTTP to fetch a web document. The base url for all API calls is (including the question mark)

http://www.lmsal.com/her/dev/search-hpkb/hek?

Following the url base, one can append a list of keywords to specify the type of command and options for that specific command.

Simple Search for Features/Events in HER

To do a simple search for Features and Events in HER, one must append to the base url:

cmd=search&type=column

In addition to the command (cmd), one must specify which event type to search for. For all event types, use **

cmd=search&type=column&event_type=**

For some but not all event types, use a comma delimited list of two-letter abbreviations (see http://www.lmsal.com/helio-informatics/hpkb/VOEvent_Spec.html for full list of event types). E.g. the following specifies that one wishes to search for active regions, flares and emerging flux regions:

cmd=search&type=column&event_type=ar,fl,ef

One must also provide a time window using event_starttime and event_endtime

cmd=search&type=column&event_type=ar,fl,ef&&event_starttime=2007-04-29T00:00:00&event_endtime=2007-05-07T00:00:00

The spatial region must also be specified. At present, we support searches by helioprojective coordinates (from Earth's perspective) as well as Stonyhurst coordinates. Let (x1,y1) and (x2,y2) be the lower-left and upper-right coordinates of a bounding box respectively. For helioprojective coordinates, all values are assumed to be in arcseconds from the disk center. To get everything within the disk, it suffices to specify

cmd=search&type=column&event_type=ar,fl,ef&&event_starttime=2007-04-29T00:00:00&event_endtime=2007-05-07T00:00:00&event_coordsys=helioprojective&x1=-1200&x2=1200&y1=-1200&y2=1200

To specify a bounding box in Stonyhurst coordinates, give the bounding longitude and latitude in degrees. For the full sphere, do

cmd=search&type=column&event_type=ar,fl,ef&&event_starttime=2007-04-29T00:00:00&event_endtime=2007-05-07T00:00:00&event_coordsys=stonyhurst&x1=-180&x2=180&y1=-90&y2=90

To get query results in XML form, set cosec=1. To get JSON, set cosec=2.

The query for this example with XML output would then be

http://www.lmsal.com/her/dev/search-hpkb/hek?cmd=search&type=column&event_type=ar,fl,ef&event_starttime=2007-04-29T00:00:00&event_endtime=2007-05-07T00:00:00&cosec=1&event_coordsys=helioprojective&x1=-1200&x2=1200&y1=-1200&y2=1200

To show the search results in iSolSearch, simply point your browser to the iSolSearch link with and passing the full query as a hek_query parameter. For instance, click [http://www.lmsal.com/helio-informatics/hpkb/hek_isolsearch.html?hek_query=http://www.lmsal.com/her/dev/search-hpkb/hek?cmd=search&type=column&event_type=ar,fl,ef&event_starttime=2007-04-29T00:00:00&event_endtime=2007-05-07T00:00:00&cosec=1&event_coordsys=helioprojective&x1=-1200&x2=1200&y1=-1200&y2=1200 here].

Customizing searches with filters

Searches can be customized with filters based on keywords. For a list of keywords/parameters for the various event and feature types, see http://www.lmsal.com/helio-informatics/hpkb/VOEvent_Spec.html. A filter is a triplet consisting of the Parameter name (param), the comparison operation (op) and a value (value).

Suppose you wish to search for all events submitted by a particular Feature Recognition Method (FRM; could be person or a software code). The API allows you to specify the FRM_Name as a string. At present the API supports two comparison operations for strings, namely =, and like. To specify the exact FRM_Name, simply append the following string to the query url

&param0=FRM_Name&op0==&value0=Karel%20Schrijver

The example above tells the API to limit results to those with FRM_Name matching Karel Schrijver. The strange looking string %20 is simply the url-escaped code for a whitespace.

Instead of specify the exact string, one can also use a wildcard. For instance, if you wish to search for entries in the registry submitted by FRM's with first name equal to Karel, use the like operator with a '%' sign as a wildcard after Karel

&param0=FRM_Name&op0=like&value0=Karel%25

The string %25 is simply the url-escaped code for a percent sign.

To add a second filter, simply define another triplet. This time, the number after param, op and value is 1.

&param0=FRM_Name&op0==&value0=Karel%20Schrijver&param1=OBS_Observatory&op1==&value1=TRACE

These two filters limit search results to those events/features reported by Karel Schrijver using data from the TRACE observatory.

The full query url for a search with these two filters for the time period October 2003 is then

http://www.lmsal.com/her/dev/search-hpkb/hek?cmd=search&type=column&event_type=ar,fl,ef&event_starttime=2003-10-01T00:00:00&event_endtime=2003-11-01T00:00:00&cosec=1&event_coordsys=helioprojective&x1=-1200&x2=1200&y1=-1200&y2=1200&param0=FRM_Name&op0==&value0=Karel%20Schrijver&param1=OBS_Observatory&op1==&value1=TRACE

To see the results in iSolSearch, click on this [http://www.lmsal.com/helio-informatics/hpkb/hek_isolsearch.html?hek_query=http://www.lmsal.com/her/dev/search-hpkb/hek?cmd=search&type=column&event_type=ar,fl,ef&event_starttime=2003-10-01T00:00:00&event_endtime=2003-11-01T00:00:00&cosec=1&event_coordsys=helioprojective&x1=-1200&x2=1200&y1=-1200&y2=1200&param0=FRM_Name&op0==&value0=Karel%20Schrijver&param1=OBS_Observatory&op1==&value1=TRACE link]

One can learn add filters to queries in [http://www.lmsal.com/helio-informatics/hpkb/hek_isolsearch.html iSolSearch] by click on the Filters tab.

Output format of queries

To get query results in XML form, include the string &cosec=1 in the query url. To get JSON, use &cosec=2.