ESASky Javascript API - ESDC
ESASky Javascript API
All commands should be sent to the ESASky element as http postmessages. For example by:
document.getElementById(esaskyFrameName).contentWindow.postMessage(command, ‘http://sky.esa.int’)
Where esaskyFrameName is the elementId where the esasky page is embedded, command is a JSON containing ‘event’ for function name and ‘content’ with all parameters
There are a number of commands that will send back response from ESASky. These will also be sent as http messages directed to the sender element of the command sent to ESASky. Unless otherwise specified this will probably be the main window for you. Add a message listener if you want to handle the data sent back as:
window.addEventListener("message",function(e){
var data = e.data;
// Code to handle the data
});
Available events described here and can be tested in the iframe on this page. Every command has a submit button which will send it to the iframe and paste it to the custom function input below the iframe. Here all responses from ESASky are also displayed:
View:
Event: goToRaDec
Parameters:
ra (String, decimal degrees or sexagesimal format)
dec (String, decimal degrees or sexagesimal format)
Description:
Moves centre of the screen to supplied ra and dec in current coordinate frame
Example:
{event:'goToRaDec', content: {ra:'10.68470',dec:'41.26875'}}
Event: setFov
Parameters: fov (double, in deg)
Description:
Set the Field of View in degrees
Example:
{event:'setFov', content: {fov:'3.2'}}
Event:
goToTargetName
Parameters:
targetName (String)
Description:
Does a search against SIMBAD to get location of targetName and sets location in view
Example:
{event:'goToTargetName', content: {targetName:'Carina Nebula'}}
Event:
getCenter
Parameters:
cooFrame (String)(Optional) - Should be "J2000" or "GALACTIC", defaults to "J2000"
Returns:
values.ra (Double) - Right ascension (lon) of the center in decimal degrees
values.dec (Double) - Declination(lat) of the center in decimal degrees
values.fov (Double) - Field of view in horizontal (lat) direction in decimal degrees
Description:
Returns the center position of the screen
Example:
{event:'getCenter', content: {cooFrame:'J2000'}}
HiPS:
Event:
getAvailableHiPS
Parameters:
wavelength (String)(Optional) - Wavelength in capital e.g. "OPTICAL". Defaults to empty.
Returns:
values(JSON dictionary) - If wavelength is empty this is a dictionary of wavlengths otherwise this is a dictionary with available HiPS in that wavlength
Description:
Returns the available HiPS in ESASky
Example:
{event:'getAvailableHiPS', content: {wavelength:'OPTICAL'}}
Event:
changeHips
Parameters:
hipsName(String)
Returns:
extras (Dictionary) - Empty if succes
extras.message (String) - Not existing if success otherwise error message
Description:
Change HiPS programmatically by using a HiPS present in ESASky
Example:
{event:'changeHips', content: {hipsName:'AllWISE color'}}
Event:
addHips
Parameters:
hipsName(String)
Returns:
extras (Dictionary) - Empty if succes
extras.message (String) - Not existing if success otherwise error message
Description:
Add a HiPS programmatically to the skypanel list
Example:
{event:'addHips', content: {hipsName:'DSS2 color'}}
Event:
changeHiPSWithParams
Parameters:
hips.id (String)
hips.name (String)
hips.url (String)
hips.cooframe (String)
hips.maxnorder (Int)
hips.imgformat (String)
Description:
Change HiPS programmatically by using a new HiPS not present in ESASky
Example:
{event:'changeHipsWithParams', content: {'hips': {'name': 'Chandra', 'id': 'Chandra', 'url': 'https://cdaftp.cfa.harvard.edu/cxc-hips/', 'cooframe': 'J2000', 'maxnorder': '11', 'imgformat': 'png'}}}
Event:
addHiPSWithParams
Parameters:
hips.id (String)
hips.name (String)
hips.url (String)
hips.cooframe (String)
hips.maxnorder (Int)
hips.imgformat (String)
Description:
Add a HiPS programmatically to the sky panel list by using a new HiPS not present in ESASky
Example:
{event:'addHiPSWithParams', content: {'hips': {'name': 'Chandra', 'id': 'Chandra', 'url': 'https://cdaftp.cfa.harvard.edu/cxc-hips/', 'cooframe': 'J2000', 'maxnorder': '11', 'imgformat': 'png'}}}
Event:
setHipsColorPalette
Parameters:
colorPalette (String)
Description:
Changing color palette
Example:
{event:'setHipsColorPalette', content: {colorPalette:'PLANCK'}}
Event:
removeHips
Parameters:
index (Integer)
Returns:
extras (Dictionary) - Empty if succes
extras.message (String) - Not existing if success otherwise error message
Description:
Removes the hips in the sky panel list at described index with first starting at 0. Entering -1 will remove all except for the first row.
Example:
{event:'removeHips', content: {index:0}}
Event:
openSkyPanel
Parameters:
Description:
Opens the sky panel with all hips shown
Example:
{event:'openSkyPanel'}
Event:
closeSkyPanel
Parameters:
Description:
Closes the sky panel
Example:
{event:'closeSkyPanel'}
Event:
setHipsSliderValue
Parameters:
value (Double)
Description:
Sets the hips slider to specified value. 0.0 for first in skypanel list 1.0 for second etc. For everything in between a interpolation of the 2 nearby HiPS will be shown
Example:
{event:'setHipsSliderValue', content: {value:0.5}}
Event:
getNumberOfSkyRows
Parameters:
Returns:
values (Integer)
Description:
Returns the current number of rows in the sky panel
Example:
{event:'getNumberOfSkyRows'}
Catalogues:
Event:
overlayCatalogue
Parameters:
overlaySet(String)
overlaySet. type(String)
overlaySet. overlayName(String)
overlaySet. cooframe(String)
overlaySet. color(String)
overlaySet. lineWidth(Int)
overlaySet. skyObjectList(List)
overlaySet. skyObjectList. name(String)
overlaySet. skyObjectList. id(Int)
overlaySet. skyObjectList. ra(String)
overlaySet. skyObjectList. dec(String)
Description:
Overlay a catalogue
Example:
{'event': 'overlayCatalogue', content: {'overlaySet': {'type': 'SourceListOverlay', 'overlayName': 'test catalogue name', 'cooframe': 'J2000', 'color': '#ee2345', 'lineWidth': 10, 'skyObjectList': [{'name': 'source name A', 'id': 1, 'ra': '150.44963', 'dec': '2.24640'}]}}}
Event:
overlayCatalogueWithDetails
Parameters:
overlaySet(String)
overlaySet. type(String)
overlaySet. overlayName(String)
overlaySet. cooframe(String)
overlaySet. color(String)
overlaySet. lineWidth(Int)
overlaySet. skyObjectList(List)
overlaySet. skyObjectList. name(String)
overlaySet. skyObjectList. id(Int)
overlaySet. skyObjectList. ra(String)
overlaySet. skyObjectList. dec(String)
overlaySet. skyObjectList. data(List)
overlaySet. skyObjectList. data.name(String)
overlaySet. skyObjectList.data. type(String)
overlaySet. skyObjectList.data. value(type)
Description:
Overlay a catalogue with data
Example:
{'event':'overlayCatalogueWithDetails', content: {'overlaySet': {'type': 'SourceListOverlay', 'overlayName': 'test catalogue name', 'cooframe': 'J2000', 'color': '#ee2345', 'lineWidth': 10, 'skyObjectList': [{'name': 'source name A', 'id': 1, 'ra': '150.44963', 'dec': '2.24640', 'data': [{'name': 'Flux 1', 'value': '10.5', 'type': 'STRING'}]}]}}}
Event:
deleteCatalogue
Parameters:
overlayName(String)
Description:
Remove an existing catalogue
Example:
{'event': 'deleteCatalogue',content: { 'overlayName': 'test catalogue name'}}
Event:
clearCatalogue
Parameters:
overlayName(String)
Description:
Clear an existing catalogue
Example:
{'event': 'clearCatalogue', content: {'overlayName': 'test catalogue name'}}
Footprints:
Event:
overlayFootprints
Parameters:
overlaySet(String)
overlaySet. type(String)
overlaySet. overlayName(String)
overlaySet. cooframe(String)
overlaySet. color(String)
overlaySet. lineWidth(Int)
overlaySet. skyObjectList(List)
overlaySet. skyObjectList. name(String)
overlaySet. skyObjectList. id(Int)
overlaySet. skyObjectList. stcs(stcs)
Description:
Overlay a list of footprints
Example:
{'event': 'overlayFootprints', content: {'overlaySet': {'type': 'FootprintListOverlay', 'overlayName': 'test footprints', 'cooframe': 'J2000', 'color': 'red', 'lineWidth': 5, 'skyObjectList': [{'name': '1', 'id': 1, 'stcs': 'Polygon J2000 187.33912535049 -62.6616054228651 187.343512531474 -62.7116786437002 187.235239903703 -62.7136263115712 187.231036216914 -62.6635488923945', 'ra_deg': '187.287228500645', 'dec_deg': '-62.6876148176328'}]}}}
Event:
overlayFootprintsWithDetails
Parameters:
overlaySet(JSON)
overlaySet. type(String)
overlaySet. overlayName(String)
overlaySet. cooframe(String)
overlaySet. color(String)
overlaySet. lineWidth(Int)
overlaySet. skyObjectList(List)
overlaySet. skyObjectList. name(String)
overlaySet. skyObjectList. id(Int)
overlaySet. skyObjectList. stcs(stcs)
overlaySet. skyObjectList. data(List)
overlaySet. skyObjectList. data.name(String)
overlaySet. skyObjectList.data. type(String)
overlaySet. skyObjectList.data. value(type)
Description:
Overlay a list of footprints with data
Example:
{'event': 'overlayFootprintsWithDetails', content: {'overlaySet': {'type': 'FootprintListOverlay', 'overlayName': 'test footprints', 'cooframe': 'J2000', 'color': 'red', 'lineWidth': 5, 'skyObjectList': [{'name': '1', 'id': 1, 'stcs': 'Polygon J2000 187.33912535049 -62.6616054228651 187.343512531474 -62.7116786437002 187.235239903703 -62.7136263115712 187.231036216914 -62.6635488923945', 'ra_deg': '187.287228500645', 'dec_deg': '-62.6876148176328', 'data': [{'name': 'wid', 'value': '0.0562381572800632', 'type': 'STRING'}, {'name': 'hei', 'value': '0.0260104443530693', 'type': 'STRING'}, {'name': 'score', 'value': '0.99999988079071', 'type': 'STRING'}]}]}}}
Event:
deleteFootprintsOverlay
Parameters:
overlayName(String)
Description:
Remove an existing catalogue
Example:
{'event': 'deleteFootprintsOverlay', content: {'overlayName': 'test catalogue name'}}
Event:
clearFootprintsOverlay
Parameters:
catalogueName(String)
Description:
Clear an existing catalogue
Example:
{'event': 'clearFootprintsOverlay', content: {'overlayName': 'test catalogue name'}}
Results panel
Event: closeDataPanel
Parameters:
Description:
Minimises the datapanel
Example:
{event:'closeDataPanel'}
Event: closeResultPanelTab
Parameters:
index (Integer)
Description:
Closes the result panel tab at index, starting with 0. -1 closes the current active tab.
Example:
{event:'closeResultPanelTab', content: {index: -1}}
Event: closeAllResultPanelTabs
Parameters:
Description:
Closes all result panel tabs
Example:
{event:'closeAllResultPanelTabs'}
Event: getResultPanelData
Parameters:
Returns:
values (Dictionary) - All data in the currently active result panel tab
Description:
Closes all result panel tabs
Example:
{event:'getResultPanelData'}
Plotting ESASky data:
Event:
plotObservations
Parameters:
missionId (String)
Returns:
extras (Dictionary) - Empty if succes
extras.message (String) - Not existing if success otherwise error message
Description:
Plot available image observation footprints in ESASky for he currently shown area for the given missionID
Example:
{event:"plotObservations", content: {missionId: 'HST-UV'}}
Event:
plotCatalogues
Parameters:
missionId (String)
Returns:
extras (Dictionary) - Empty if succes
extras.message (String) - Not existing if success otherwise error message
Description:
Plot available catalogue data in ESASky for the currently shown area for the given missionID
Example:
{event:"plotCatalogues", content: {missionId: "GAIA DR2"}}
Event:
plotSpectra
Parameters:
missionId (String)
Returns:
extras (Dictionary) - Empty if succes
extras.message (String) - Not existing if success otherwise error message
Description:
Plot available spectra footprints in ESASky for he currently shown area for the given missionID
Example:
{event:"plotSpectra", content: {missionId: 'IUE'}}
Event:
plotSpectra
Parameters:
missionId (String)
Returns:
extras (Dictionary) - Empty if succes
extras.message (String) - Not existing if success otherwise error message
Description:
Plot available spectra footprints in ESASky for he currently shown area for the given missionID
Example:
{event:"plotSpectra", content: {missionId: 'IUE'}}
Counts
Event:
getObservationCount
Parameters:
Returns:
List of available observations in ESASky with associated counts in the visible sky area
Description:
Returns the observations count
Example:
{'event': 'getObservationsCount'}
Event:
getCataloguesCount
Parameters:
Returns:
List of available catalogues in ESASky with associated counts in the visible sky area
Description:
Returns the catalogues count
Example:
{'event': 'getCataloguesCount'}
Event:
getSpectraCount
Parameters:
Returns:
List of available spectra in ESASky with associated counts in the visible sky area
Description:
Returns the spectra count
Example:
{'event': 'getSpectraCount'}
Event:
getPublicationsCount
Parameters:
Returns:
Number of publications in the visible sky area
Description:
Returns the publications count
Example:
{'event': 'getPublicationsCount'}
JWST planning tool:
Event:
addJwst
Parameters:
instrument(String)
detector(String)
showAllInstruments(boolean)
Description:
Open the JWST planning tool and adds at center of screen
Example:
{'event': 'addJwst', content: {'instrument': 'NIRSpec', 'detector': 'NRS_FULL_MSA', 'showAllInstruments': false}}
Event:
addJwstWithCoordinates
Parameters:
instrument(String)
detector(String)
showAllInstruments(boolean)
ra(String, in degrees)
dec(String, in degrees)
rotation(String, in degrees)
Description:
Open the JWST planning tool and adds at supplied coordinates
Example:
{'event': 'addJwstWithCoordinates', content: {'instrument': 'NIRISS', 'detector': 'NIS_CEN', 'showAllInstruments': true, 'ra': '210', 'dec': '12', 'rotation': '90'}}
Event:
closeJwstPanel
Parameters:
Description:
Closes the JWST planning tool
Example:
{'event': 'closeJwstPanel'}
Event:
openJwstPanel
Parameters:
Description:
Opens the JWST planning tool
Example:
{'event': 'openJwstPanel'}
Event:
clearJwstAll
Parameters:
Description:
Clear all
Example:
{'event': 'clearJwstAll'}
Output window