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

Will show any text returned from ESASky