## Please edit system and help pages ONLY in the moinmaster wiki! For more
## information, please see MoinMaster:MoinPagesEditorGroup.
##acl MoinPagesEditorGroup:read,write,delete,revert All:read GregSlater:write,delete,revert,read
##master-page:HelpTemplate
##master-date:Unknown-Date
#format wiki
#language en
== Heliophysics Events Knowledgebase API ==
Third party clients can communicate with the Heliophysics Events Knowledgebase (HER) via our web API. 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). Let (x1,y1) and (x2,y2) be the lower-left and upper-right coordinates of a bounding box respectively. 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 get 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.

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

=== Display ===
xxx
