TableOfContents(3)

Heliophysics Events Registry web 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.

Maximum number of returned results

By default the maximum number of results given a query is 100. To change this limit, set

result_limit=Num

where Num is the maximum number of results to return. The results are returned sorted by reverse chronological order (Based on event_starttime). To avoid unreasonably time-consuming requests from hoarding API resources, a search will timeout after 60s. In that case, please breakup you query into small chunks and perform searches incrementally.

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.

The xml output is looks like this

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

The JSON output looks like this

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

If JSON output is requested, an optional parameter can be specified in the url to wrap the JSON with a call to a Javascript callback function. For instance, suppose the web client you are developing requests JSON from HER. If you want to handle the JSON with some function, say it's named processJSON, then simply provide the optional parameter 'callback=processJSON' in the query url. With this option, the output will have the string processJSON( ); wrapped around the JSON.

Returning a limited subset of parameters

By default, search results contain information about all the parameters that are either required or optional. If only most basic (required) parameters are needed, one can add the following string to the url

&return=required

Summary Page of a HER Event/Feature

Each event/feature in HER has a unique id (look for event_id parameter in the search results output). Let says, an entry has an event_id of 1011428. To view the summary page of the event, point your browser to

http://www.lmsal.com/her/dev/search-hpkb/hek?cmd=view-voevent&id=1011428

Clickable link is [http://www.lmsal.com/her/dev/search-hpkb/hek?cmd=view-voevent&id=1011428 here].

VOEvent XML of a HER Event/Feature

To get the VOEvent XML of an entry, use the [http://www.lmsal.com/her/dev/search-hpkb/hek?cmd=export-voevent&cosec=1&id=1011428 link]

http://www.lmsal.com/her/dev/search-hpkb/hek?cmd=export-voevent&cosec=1&id=1011428

where the value of id is the parameter given as 'event_id' (look for it in the search results output).

Recently Reported Events Page

To see the most recent submissions of events and featuresd detected by humans (i.e. not by software), go to

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

Clickable link is [http://www.lmsal.com/her/dev/search-hpkb/hek?cmd=home here]. Note that only those with frm_humanflag = true will be shown.