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

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

 


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

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 (only works on DEV server (not in this window))

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 ( on dev server only)

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 ( on dev server only)

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

 

Output window

Will show any text returned from ESASky