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: 

setCooFrame

Parameters: 

cooFrame (String) - J2000 or galactic

Description:

Set the coordinate frame

Example:

{event:'setCooFrame', content: {cooFrame: "galactic"}}

 

Event: 

clickExploreButton

Parameters: 

Description:

Explore a random target

Example:

{event:'clickExploreButton'}

 

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'}

 

Event: 

openOutreachPanel

Parameters: 

Description:

Open the outreach panel

Example:

{event: 'openOutreachPanel'}

 

Event: 

closeOutreachPanel

Parameters: 

Description:

Close the outreach panel

Example:

{event: 'closeOutreachPanel'}

 

Event: 

getOutreachImageIds

Parameters: 

Description:

Get all available outreach image IDs

Returns:

Returns a list of outreach image IDs

Example:

{event: 'getOutreachImageIds'}

 

Event: 

openOutreachImage

Parameters: 

id - The unique identifier of the outreach image to be opened

Description:

Close the outreach panel

Example:

{event: 'openOutreachImage', content: { id: "heic0406a"}}

 

Event: 

playerPlay

Parameters: 

Description:

Start the currently active player

Example:

{event: 'playerPlay'}

 

Event: 

playerPause

Parameters: 

Description:

Pause the currently active player

Example:

{event: 'playerPause'}

 

Event: 

playerNext

Parameters: 

Description:

Go to the next entry in the player queue

Example:

{event: 'playerNext'}

 

Event: 

playerPrevious

Parameters: 

Description:

Go to the previous entry in the player queue

Example:

{event: 'playerPrevious'}

 

Output window

Will show any text returned from ESASky