|
Size: 3074
Comment:
|
Size: 9411
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 3: | Line 3: |
| ##acl MoinPagesEditorGroup:read,write,delete,revert All:read,write | ##acl MoinPagesEditorGroup:read,write,delete,revert All:read GregSlater:write,delete,revert,read |
| Line 8: | Line 8: |
| == 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) |
[[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) |
| Line 21: | Line 31: |
| }}} | }}} |
| Line 27: | Line 36: |
| }}} | }}} |
| Line 33: | Line 41: |
| }}} | }}} |
| Line 39: | Line 46: |
| }}} 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 |
}}} 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 46: | Line 52: |
| To specify a bounding box in Stonyhurst coordinates, give the bounding longitude and latitude in degrees. For the full sphere, do | |
| Line 47: | Line 54: |
| To get results in XML form, set ''cosec=1''. To get JSON, set ''cosec=2''. | {{{ 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''. |
| Line 51: | Line 62: |
| {{{ | |
| Line 52: | Line 64: |
| }}} 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]. |
|
| Line 53: | Line 68: |
| 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. | |
| Line 55: | Line 69: |
| 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 | ---- /!\ '''Edit conflict - other version:''' ---- === Customizing Searches with Filters === |
| Line 57: | Line 72: |
| === Display === xxx |
---- /!\ '''Edit conflict - your version:''' ---- === Customizing Searches with Filters === ---- /!\ '''End of edit conflict''' ---- 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 {{{ ¶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-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'' {{{ ¶m0=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''. {{{ ¶m0=FRM_Name&op0==&value0=Karel%20Schrijver¶m1=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¶m0=FRM_Name&op0==&value0=Karel%20Schrijver¶m1=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¶m0=FRM_Name&op0==&value0=Karel%20Schrijver¶m1=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''. 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. ---- /!\ '''Edit conflict - other version:''' ---- === Summary Page of a HER Event/Feature === ---- /!\ '''Edit conflict - your version:''' ---- === Summary Page of a HER Event/Feature === ---- /!\ '''End of edit conflict''' ---- 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 brower 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). ---- /!\ '''Edit conflict - other version:''' ---- === Recently Reported Events Page === ---- /!\ '''Edit conflict - your version:''' ---- === Recently Reported Events Page === ---- /!\ '''End of edit conflict''' ---- 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. |
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].
![/!\](/wiki/modern/img/alert.png "/!\"){kind=small}
Edit conflict - other version:
Customizing Searches with Filters
Edit conflict - your version:
Customizing Searches with Filters
End of edit conflict
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
¶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-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
¶m0=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.
¶m0=FRM_Name&op0==&value0=Karel%20Schrijver¶m1=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¶m0=FRM_Name&op0==&value0=Karel%20Schrijver¶m1=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¶m0=FRM_Name&op0==&value0=Karel%20Schrijver¶m1=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.
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.
Edit conflict - other version:
Summary Page of a HER Event/Feature
Edit conflict - your version:
Summary Page of a HER Event/Feature
End of edit conflict
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 brower 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).
Edit conflict - other version:
Recently Reported Events Page
Edit conflict - your version:
Recently Reported Events Page
End of edit conflict
To see the most recent submissions of events and featuresd detected by humans (i.e. not by software), go to