|
Size: 2039
Comment:
|
Size: 4916
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 3: | Line 3: |
| ##acl MoinPagesEditorGroup:read,write,delete,revert All:read | ##acl MoinPagesEditorGroup:read,write,delete,revert All:read GregSlater:write,delete,revert,read |
| Line 9: | Line 9: |
| 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/helio-informatics/hpkb/images/isolsearch_preview_small.jpg The [http://www.lmsal.com/helio-informatics/hpkb/hek_isolsearch.html iSolSearch] web application lets users query the Heliophysics Events Knowledgebase (HEK) in an interactive manner (much like Google Maps). iSolSearch interacts with HEK by means of our web application programming interface (API). The API enables developers to create new third party clients for HEK as well as scientists to write software code which interact with HEK 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) |
| Line 21: | Line 24: |
| }}} | }}} |
| Line 27: | Line 29: |
| }}} | }}} |
| Line 33: | Line 34: |
| }}} | }}} |
| Line 39: | Line 39: |
| }}} To get results in XML format, set ''cosec=1'' |
}}} 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 |
| Line 44: | Line 43: |
| 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 | 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 |
| Line 46: | Line 45: |
| To specify a bounding box in Stonyhurst coordinates, give the bounding longitude and latitude in degrees. For the full sphere, do | |
| Line 48: | Line 48: |
| 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 | 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 |
| Line 50: | Line 50: |
| === Display === xxx |
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. 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 === 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 want 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 {{{ ¶m0=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 escape code for a whitespace. |
Heliophysics Events Knowledgebase API
http://www.lmsal.com/helio-informatics/hpkb/images/isolsearch_preview_small.jpg
The [http://www.lmsal.com/helio-informatics/hpkb/hek_isolsearch.html iSolSearch] web application lets users query the Heliophysics Events Knowledgebase (HEK) in an interactive manner (much like Google Maps). iSolSearch interacts with HEK by means of our web application programming interface (API). The API enables developers to create new third party clients for HEK as well as scientists to write software code which interact with HEK 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.
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 want 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
¶m0=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 escape code for a whitespace.