The APIS Service
The Auroral Planetary Imaging and Spectroscopy (APIS) service aims at providing a free and simple access to a database of high-level auroral data, in convenient formats (fits, jpg, pdf), and compatible with virtual observatory (VO) facilities. It is fully described in a dedicated publication and accessible online at : http://apis.obspm.fr
It consists of :
- a high level database of planetary auroral spectro-imaging observations. So far, this database includes most of the HST Far-UV observations of the planets and their satellites since 1997.
- a conditional search interface adapted to the needs of the magnetospheric and atmospheric communities (click on "search for data" within the APIS webpage).
- the ability to interactively work with the data online through plotting tools developed by the Virtual Observatory (VO) community (such as Aladin, Specview or Cassis).
APIS is fully operational since early 2012 and has been officially acknowledged by the CNRS (french institute of research) in 2015.
Making your data available through APIS
In addition to our internal HST database described above, the APIS search interface is aimed at being able to simultaneously query external databases as well.
To enable the APIS team to include such a connexion, the data provider shall :
- provide an access to the data themselves (in fits format) and quicklooks (in jpg and/or pdf formats) each accompanied by a thumbnail (in jpg format).
- set up an EPN-TAP service to share its data product catalog.
- indicate a scientific responsible for the provided data.
The purpose of this page is to detail the EPN-TAP mandatory fields to be fully compatible with the APIS search interface.
Setting your EPNcore table
Each data product (fits data, jpg plot, pdf plot etc.) is a granule, and shall thus be described in a single line in the EPNcore.
Example with one HST observation :
| granule_uid | granule_gid | processing_level | obs_id | access_url | access_format | thumbnail_url | Details |
|---|---|---|---|---|---|---|---|
| o5g202x4q_x2d | original_data | 2 | o5g202x4q | o5g202x4q_x2d.fits | image/fits | o5g202x4q_x2d_small.jpg | Original data file (CODMAC Level 2: edited) |
| o5g202x4q_x2d_jpg | original_data | 2 | o5g202x4q | o5g202x4q_x2d.jpg | image/jpg | o5g202x4q_x2d_small.jpg | JPEG version of original data (web) |
| o5g202x4q_x2d_pdf | original_data | 2 | o5g202x4q | o5g202x4q_x2d.pdf | application/pdf | o5g202x4q_x2d_small.jpg | PDF version of original data (print) |
| o5g202x4q_proc | processed_data | 3 | o5g202x4q | o5g202x4q_proc.fits | image/fits | o5g202x4q_proc_small.jpg | Calibrated data (CODMAC Level 3: calibrated) |
| o5g202x4q_proc_jpg | processed_data | 3 | o5g202x4q | o5g202x4q_proc.jpg | image/jpg | o5g202x4q_proc_small.jpg | JPEG version of calibrated data (web) |
| o5g202x4q_proc_pdf | processed_data | 3 | o5g202x4q | o5g202x4q_proc.pdf | application/pdf | o5g202x4q_proc_small.jpg | PDF version of calibrated data (print) |
| o5g202x4q_cyl | cylindrical_projection | 4 | o5g202x4q | o5g202x4q_cyl.jpg | image/jpg | o5g202x4q_cyl_small.jpg | Cylindrical projection (CODMAC Level 3: resampled) |
| o5g202x4q_pol_n | polar_projection_north | 4 | o5g202x4q | o5g202x4q_pol_n.jpg | image/jpg | o5g202x4q_pol_n_small.jpg | Northern polar projection (CODMAC Level 3: resampled) |
| o5g202x4q_pol_s | polar_projection_south | 4 | o5g202x4q | o5g202x4q_pol_s.jpg | image/jpg | o5g202x4q_pol_s_small.jpg | Southern polar projection (CODMAC Level 3: resampled) |
EPNcore Parameters Mandatory for APIS compliance
The other mandatory EPNcore parameters can be set to NULL.
| EPNcore parameter | Content | Notes |
|---|---|---|
| granule_uid | unique id of the granule | |
| granule_gid | group id. For APIS, this represents the data level | possible values :
|
| obs_id | original data id | unique identifier for each observation (Ex with HST : o5g202x4q) |
| dataproduct_type |
| sc refers to 'spectral cube' |
| target_name | target name | the first letter (only) must be capitalized (Ex : Jupiter) |
| target_class | target class (planet, satellite...) | in lowercase. The list of allowed values is specified in EPNcore documentation. |
| time_min | Start of Observation | in Julian days (not in modified Julian days) |
| time_max | End of Observation | in Julian days (not in modified Julian days) |
| time_exp_min | in seconds | |
| time_exp_max | in seconds | |
| spectral_range_min | in Hz. See EPNcore documentation for conversion factors. | |
| spectral_range_max | in Hz. See EPNcore documentation for conversion factors. | |
spectral_sampling_step_min spectral_resolution_min | one of these 2 should be set. in Hz. See EPNcore documentation for conversion factors. | |
spectral_sampling_step_max spectral_resolution_max | one of these 2 should be set. in Hz. See EPNcore documentation for conversion factors. | |
| spatial_frame_type | ||
phase_min phase_max | phase angle | can contain the same value |
| instrument_host_name | spacecraft / observatory name | the standard name should be used (Ex : HST) |
| instrument_name | instrument name | name of the spectro-imager (Ex with HST : STIS or ACS) |
| measurement_type |
| |
| access_url | URL of the product | |
| access_format | mime type of the product |
|
access_estsize | estimated file size | in kbyte |
thumbnail_url | URL of a thumbnail image with predefined size | jpg 250 pix wide |
| external_link | Link to a web page providing more details on the granule. | |
| processing_level | CODMAC data level |
|
| publisher | ||
| bib_reference | ||
| service_title | APIS | |
| target_region | Ex: magnetosphere | |
| feature_name | Ex: planetary aurorae | |
| filter | imaging filter (spectral filter) or slit configuration (spatial filter) | Ex with HST : F25SrF2 for images or 52x0.5 for long-slit spectroscopy |
| ra | ||
| dec | ||
| release_date | ||
| creation_date | ||
| modification_date | ||
| subobserver_latitude | in degree | |
| subsolar_latitude | in degree | |
| subobserver_longitude | in degree (IAU system III for Jupiter and Uranus, NULL for Saturn) | |
| subsolar_longitude | in degree (IAU system III for Jupiter and Uranus, NULL for Saturn) | |
target_distance_min target_distance_max |
| Observer-target distance (in km) |
sun_distance_min sun_distance_min |
| Sun-target distance (in AU) |
| file_name | name of the file that can be downloaded from access_url |
Extra Parameters for APIS
To be fully compliant with APIS, the EPNcore table must be completed with the following mandatory parameters.
| APIS extension parameter | Mandatory | Content | Notes |
|---|---|---|---|
| obs_mode | yes | observing mode | Ex with HST : ACCUM or TIME-TAG |
| detector_name | yes | detector | Ex with HST : FUV-MAMA (for STIS) or SBC (for ACS) |
| opt_elem | yes | optical element | Ex with HST : G140L (= grating for spectra) or MIRFUV (for images) |
| detector_orientation | yes | position angle of image y axis | in degrees, east of north |
| measurement_unit | yes | physical unit | (= bunit in the APIS internal table) |
| proposal_id | yes | proposal ID | NULL if non applicable Ex with HST = ID of HST proposal (unique) (= proposid in the APIS internal table) |
| proposal_pi | yes | last name of principal investigator | NULL if non applicable (= pr_inv_l in the APIS internal table) |
| proposal_title | yes | title of proposal | NULL if non applicable (= propttl1 in the APIS internal table) |
| platesc | yes | spatial resolution per pixel or platescale | in arcsec/pixels |
| campaign | yes | name of the observational campaign | Ex with HST : Saturn - 2005 26 Oct-02 Nov |
| target_apparent_radius | yes | apparent radius of the target | in arcsec |
| north_pole_position | yes | north pole position angle with respect to celestial north pole | in degree |
| target_primary_hemisphere | yes | primary observed hemisphere | south or north or NULL |
| target_secondary_hemisphere | yes | secondary observed hemisphere | south or north or NULL |
The following ephemeris parameters, also mandatory for a search with the APIS interface, will be added to each external EPNcore database by the APIS team.
| APIS extension parameters | Mandatory | Content | Notes |
|---|---|---|---|
| skr_n | only for Saturn | provided by APIS | Meudon SKR Northern variable phase (IAU SIII does not work for Saturn) |
| skr_s | only for Saturn | provided by APIS | Meudon SKR Southern variable phase (IAU SIII does not work for Saturn) |
| lon_io | only for Jupiter | provided by APIS | longitude of Io in system III (if Jupiter) |
| lt_io | only for Jupiter | provided by APIS | local time of Io (if Jupiter) |
| lon_eur | only for Jupiter | provided by APIS | longitude of Europa in system III (if Jupiter) |
| lt_eur | only for Jupiter | provided by APIS | local time of Europa (if Jupiter) |
| lon_gan | only for Jupiter | provided by APIS | longitude of Ganymede in system III (if Jupiter) |
| lt_gan | only for Jupiter | provided by APIS | local time of Ganymede (if Jupiter) |
| lon_cal | only for Jupiter | provided by APIS | longitude of Callisto in system III (if Jupiter) |
| lt_cal | only for Jupiter | provided by APIS | local time of Callisto (if Jupiter) |
| lt_mim | only for Jupiter | provided by APIS | local time of Mimas (if Saturn) |
| lt_enc | only for Saturn | provided by APIS | local time of Enceladus (if Saturn) |
| lt_the | only for Saturn | provided by APIS | local time of Tethys (if Saturn) |
| lt_dio | only for Saturn | provided by APIS | local time of Dione (if Saturn) |
| lt_rhe | only for Saturn | provided by APIS | local time of Rhea (if Saturn) |
| lt_tit | only for Saturn | provided by APIS | local time of Titan (if Saturn) |
| rs_cas | only for Saturn | provided by APIS | Distance of Cassini to Saturn |
| lat_cas | only for Saturn | provided by APIS | Latitude of Cassini |
| lt_cas | only for Saturn | provided by APIS | Local time of Cassini |
| rs_gal | only for Jupiter | provided by APIS | Distance of Galileo to Jupiter |
| lat_gal | only for Jupiter | provided by APIS | Latitude of Galileo |
| lt_gal | only for Jupiter | provided by APIS | Local time of Galileo |
| rs_jun | only for Jupiter | provided by APIS | Distance of Juno to Jupiter |
| lat_jun | only for Jupiter | provided by APIS | Latitude of Juno |
| lt_jun | only for Jupiter | provided by APIS | Local time of Juno |
Internal APIS conversion table
The internal APIS table (named apis_data) consists in one line per observation, with several products described in several columns.
| APIS | Mandatory | relation with EPNcore | Comment |
|---|---|---|---|
| id | yes | arbitrary ID (unique) | |
| calibrated_filename | yes | access_url for original_data granule | relative path of level 1 data (whether imaging or spectroscopy). FITS format. |
| calibrated_preview | yes | access_url for original_data granule | relative path of level 1 jpg plot (whether imaging or spectroscopy). JPEG format. |
| processed_filename | yes | access_url for processed_data granule | relative path of level 2 data (whether imaging or spectroscopy). FITS format. |
| processed_preview | yes | access_url for processed_data granule | relative path of level 2 jpg plot (whether imaging or spectroscopy). JPEG format. |
| processed_pdf | yes | access_url for processed_data granule | relative path of level 2 pdf plot (whether imaging or spectroscopy). PDF format. |
| spectrum_filename | depends on the provided data levels | access_url for 1D_spectra granule | relative path of level 3 data (= 1D spectra, applicable only to spectroscopic observations). FITS format. |
| spectrum_preview | depends on the provided data levels | access_url for 1D_spectra granule | relative path of level 3 jpg plot (= 1D spectra, applicable only to spectroscopic observations). JPEG format. |
| spectrum_pdf | depends on the provided data levels | access_url for 1D_spectra granule | relative path of level 3 pdf plot (= 1D spectra, applicable only to spectroscopic observations). PDF format. |
cylindric_filename | depends on the provided data levels | access_url for cylindric_proj granule | relative path of level 3 data (= cylindrical projection, applicable only to images). FITS format. |
cylindric_preview | depends on the provided data levels | access_url for cylindric_proj granule | relative path of level 3 jpg plot (= cylindrical projection, applicable only to images). JPEG format. |
cylindric_pdf | depends on the provided data levels | access_url for cylindric_proj granule | relative path of level 3 pdf plot (= cylindrical projection, applicable only to images). PDF format. |
polar_n_filename | depends on the provided data levels | access_url for polar_proj_north granule | relative path of level 3 data (= northern polar projection, applicable only to images). FITS format. |
polar_n_preview | depends on the provided data levels | access_url for polar_proj_north granule | relative path of level 3 jpg plot (= northern polar projection, applicable only to images). JPEG format. |
polar_n_pdf | depends on the provided data levels | access_url for polar_proj_north granule | relative path of level 3 pdf plot (= northern polar projection, applicable only to images). PDF format. |
polar_s_filename | depends on the provided data levels | access_url for polar_proj_south granule | relative path of level 3 data (= southern polar projection, applicable only to images). FITS format. |
polar_s_preview | depends on the provided data levels | access_url for polar_proj_south granule | relative path of level 3 jpg plot (= southern polar projection, applicable only to images). JPEG format. |
polar_s_pdf | depends on the provided data levels | access_url for polar_proj_south granule | relative path of level 3 pdf plot (= southern polar projection, applicable only to images). PDF format. |
| telescop | yes | instrument_host_name | Spacecraft / observatory name |
| instrume | yes | instrument_name | instrument name |
| targname | yes | target_name | target name. Uppercase for APIS (ex: JUPITER), Capitalized for EPNcore (ex: Jupiter) |
| tdateobs | no | yyyy-mm-dd (in UT time) of the start of the observation | |
| ttimeobs | no | hh:mm:ss (in UT time) of the start of the observation | |
| datetime | yes | time_min time_max | yyyy-mm-dd hh:mm:ss (in UT time) of the start of the observation EPNcore values are in Julian dates |
| texptime | yes | time_exp_min time_exp_max | exposure time in second |
| obstype | yes | dataproduct_type | IMAGING or SPECTROSCOPY or SPECTRO-IMAGING im, sp or cs for EPNcore |
| obsmode | yes | obs_mode | Photometric mode. Example with HST data = ACCUM or TIME-TAG |
| photmode | no | Example with HST data = FUV-MAMA (omit if non applicable) | |
| detector | yes | detector_name | Example with HST data = FUV-MAMA (for STIS) or SBC (for ACS) |
| opt_elem | yes | opt_elem | Example with HST data = G140L (= grating for spectra) or MIRFUV (for images) |
| filter | yes | filter | Example with HST data = F25SrF2 |
| orientat | yes | orientation | Position angle of image y axis (in degrees, east of north) |
| bandwid | spectral_resolution_min = 3E18/spectral_step OR 3E18/bandwid spectral_resolution_max = 3E18/spectral_step OR 3E18/bandwid | spectral bandwidth in Angstroms | |
| cenwave | |||
| specres | yes | approx. resolving power at central wavelength in Angstroms | |
| centrwv | no | central wavelength in Angstroms | |
| minwave | yes | spectral_range_min = 3E18/minwave | min wavelength of the spectrum in Angstroms |
| maxwave | yes | spectral_range_max = 3E18/minwave | max wavelength of the spectrum in Angstroms |
| spectral_step | yes | spectral_sampling_step_min = 3E18/spectral_step spectral_sampling_step_max = 3E18/spectral_step | spectral step in Angstroms |
| last_update | yes | last update of the line in the database (yyyy-mm-ddThh:mm:ss) | |
| bunit | yes | measurement_unit | unit |
| proposid | yes | proposal_id | Example with HST data = ID of HST proposal (unique) |
| pr_inv_l | yes | proposal_pi | last name of principal investigator |
| propttl1 | yes | proposal_title | title of proposal |
| tardescr | |||
| origin | yes | Example with HST data = NOAO-IRAF FITS Image Kernel July 2003 (omit if non applicable) | |
| ra_targ | yes | ra | Right ascencion of the target |
| dec_targ | yes | dec | Declination of the target |
| platesc | yes | platesc | spatial resolution per pixel or platescale (in arcsec/pixels) |
| date | yes | date when the data was written (yyyy-mm-ddThh:mm:ss) | |
| cal_ver | no | calibration pipeline version (omit if non applicable) | |
| rootname | yes | obs_id | rootname of the dataset (Example with HST : each observation has a unique name in 9 characters) |
| campaign | yes | campaign | name of the observational campaign (Example with HST : Saturn - 2005 26 Oct-02 Nov) |
| sunangle | |||
| moonangl | |||
| sun_alt | |||
| subelat | yes | sub-earth latitude in degree | |
| subslat | yes | sub-solar latitude in degree | |
| subelon | yes | sub-earth longitude in degree (system III for Jupiter, Uranus, NULL for Saturn) | |
| subslon | yes | sub-solar longitude in degree (system III for Jupiter, Uranus, NULL for Saturn) | |
| dists | yes | target-sun distance | |
| diste | yes | target_distance_min, target_distance_max | target-earth distance |
| rap | yes | target_apparent_radius | apparent radius of the target (in arcsec) |
| np_pos | yes | north_pole_position | north pole position angle with respect to celestial north pole in degree |
| phase | yes | phase_min phase_max | phase angle |
| hemis1 | yes | target_primary_hemisphere | primary observed hemisphere (= South or North) |
| hemis2 | yes | target_secondary_hemisphere | secondary observed hemisphere (= South or North or maybe NULL) |
| date_processed | yes | creation_date | first file writing date (yyyy-mm-ddThh:mm:ss)
|
modified_at | yes | modification_date | file modification date (yyyy-mm-ddThh:mm:ss) |
| skr_n | only for Saturn | Meudon SKR Northern variable phase (SIII does not work for Saturn) | |
| skr_s | only for Saturn | Meudon SKR Southern variable phase (SIII does not work for Saturn) | |
| lon_io | only for Jupiter | longitude of Io in system III (if Jupiter) | |
| lt_io | only for Jupiter | local time of Io (if Jupiter) | |
| lon_eur | only for Jupiter | longitude of Europa in system III (if Jupiter) | |
| lt_eur | only for Jupiter | local time of Europa (if Jupiter) | |
| lon_gan | only for Jupiter | longitude of Ganymede in system III (if Jupiter) | |
| lt_gan | only for Jupiter | local time of Ganymede (if Jupiter) | |
| lon_cal | only for Jupiter | longitude of Callisto in system III (if Jupiter) | |
| lt_cal | only for Jupiter | local time of Callisto (if Jupiter) | |
| lt_mim | only for Jupiter | local time of Mimas (if Saturn) | |
| lt_enc | only for Saturn | local time of Enceladus (if Saturn) | |
| lt_the | only for Saturn | local time of Tethys (if Saturn) | |
| lt_dio | only for Saturn | local time of Dione (if Saturn) | |
| lt_rhe | only for Saturn | local time of Rhea (if Saturn) | |
| lt_tit | only for Saturn | local time of Titan (if Saturn) | |
| rs_cas | only for Saturn | Distance of Cassini to Saturn | |
| lat_cas | only for Saturn | Latitude of Cassini | |
| lt_cas | only for Saturn | Local time of Cassini | |
| rs_gal | only for Jupiter | Distance of Galileo to Jupiter | |
| lat_gal | only for Jupiter | Latitude of Galileo | |
| lt_gal | only for Jupiter | Local time of Galileo | |
| rs_jun | only for Jupiter | Distance of Juno to Jupiter | |
| lat_jun | only for Jupiter | Latitude of Juno | |
| lt_jun | only for Jupiter | Local time of Juno |