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:
Click on the headers to expand them
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'}}
Event: showCoordinateGrid:
Parameters:
show (Boolean) shows for true, hides for false
Description:
Enables or disables the coordinate grid overlay
Example:
{event:'showCoordinateGrid', content: {show:true}}
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'}
Event:
selectShape
Parameters:
overlayName (String) - Name of the overlaySet where we eant to selesct a shape
shapeName (String) - Name of the shape (typical observation id. See overlayCatalogue/Footprint or response from shapeSelectionEvent
Description:
Selects a shape (catalogue source or footprint)
Example: ( will only work after you've run overlayFootprints example)
{'event': 'selectShape', content: {overlayName:'test footprints', shapeName:'test footprint1'}}
Event:
deselectShape
Parameters:
overlayName (String) - Name of the overlaySet where we eant to selesct a shape
shapeName (String) - Name of the shape (typical observation id. See overlayCatalogue/Footprint or response from shapeSelectionEvent
Description:
Deselects a shape (catalogue source or footprint)
Example: ( will only work after you've run overlayFootprints example and selected it)
{'event': 'deselectShape', content: {overlayName:'test footprints', shapeName:'test footprint1'}}
Event:
deselectAllShapes
Parameters:
Description:
Deselects all shapes selected (catalogue source or footprint)
Example: ( will only work after you've selected some shapes)
{'event': 'deselectAllShapes'}
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'}}
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': 'test footprint1', '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': 'test footprint1', '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'}}
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'}
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'}}
Event:
plotTapServiceWithDetails
Parameters:
name (String) - Will overwrite any exisitng dataPanel with the same name
tapUrl (String)
color (String) - Sets the color, use 'blue' or RGB format (e.g. '#FF008A')
adql (String) - ADQL used for the TAP query
Description:
Plot available image observation footprints in ESASky for he currently shown area for the given missionID
Example:
{'event':'plotTapServiceWithDetails', content: {"name":"myTAP22",color:"#FF00FF", dataOnlyInView: false, tapUrl:"http://archive.eso.org/tap_obs", adql:"SELECT TOP 100 * FROM ivoa.obscore"}}
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'}
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'}
Event:
addMOC
Parameters:
name(String) - Name of the MOC (will overwrte existing MOC with same name)
options.color(String) - Sets the color, use 'blue' or RGB format (e.g. '#FF008A')
options.opacity(Float) - Opacity of the MOC in range 0.0 - 1.0 (1.0 will only show the borders)
options.lineStyle(String)(optional) - Sets the linestyle of the borders in case only the borders are shown. Possible parameters are "solid" and "dashed"
options.mode(String)(optional) - Default: "healpix" Choose to display in "healpix" or "q3c" system
options.addTab(Boolean)(optional) - Default: false Adds a resultspanel tab to control style on true
mocData(Javascript Object) - Object where the keys are the orders and the values are lists of pixels in the order
Description:
Adds a MOC ( HEALPix Multi-Order Coverage map) on the sky
Example:
{event:'addMOC', content: {name:"myMOC",options:{color:"#FF00FF",lineStyle:"dashed",opacity:.5, mode:"healpix", addTab:true}, mocData:{8:[0,1,2,3,4,5], 6:[165]}}}}
Event:
removeMOC
Parameters:
name(String) - Name of the MOC (if it has already been added) MOC added without name will be "MOC"
Description:
Removes a MOC ( HEALPix Multi-Order Coverage map) from the sky
Example:
{'event':'removeMOC', "content": {"name":"myMOC"}}
Event:
addCustomTreeMap
Parameters:
treeMap.name(String) - The name/ID that will be used in any callbacks
treeMap.description(String)(Optional) - Description that will be shown when hovering on the button
treeMap.iconText(String)(Otional) - Text showing on the button, will default to name if not specified
treeMap.missions (List) - List of the missions that will show up in the treemap
treeMap.missions.name(String) - Name of the mission which will be ID in callbacks
treeMap.missions.color(String) - Default color showing up in the treeMap
Returns:
On click of one of the tree map missions this will return a message
values.action (String) - "treemap_mission_clicked"
values.info.treemap(String) - treemap name as specified in the parameter
values.info.mission (String) - mission name as specified in the parameter
Description:
Adds a custom treeMap button to ESASky and starts listening for clicks on the missions inside it
Example:
{'event': 'addCustomTreeMap', content: {'treeMap':{name:'JWST', iconText:'JWST', description:'James webb imgages....', missions:[{'name':'NIRSpec','color':'blue'},{'name':'NIRCam','color':'green'}]}}}
Event:
setModuleVisibility
Parameters:
modules(JSON Object) - Object on format: {key:boolean}. Possible keys are: scientific_toggle_button, language_button, coordinate_grid_button, screenshot_button, share_button, help_button, dropdown_menu, feedback_button, skies_menu, observations_button, catalogues_button, spectra_button, exttap_button, sso_button, publications_button, target_list_button, jwst_planning_button, dice_button, science_mode
Description:
Sets visibility of the buttons
Example:
{event:'setModuleVisibility', content: {modules:{coordinate_grid_button:false}}}
Event:
registerEventListener
Parameters:
Returns:
Will return values on change of view and on selection of shapes
View changed:
values.action (String) - "view_changed"
values.values.ra (float) - Right ascension of center of screen in deg
values.values.dec (float) - Declination of center of screen in deg
values.values.fov (float) - Field of View in deg
Shape selected:
values.action (String) - "shape_selected"
values.values.overlay (String) - Overlayname to which the shape selected is attached
values.values.name (String) - Name of the shape
values.values.id (String) - Id of the shape
Description:
Adds a event listener which returns values of certain events
Example:
{'event': 'registerEventListener'}
Output window