_images/exomastLogo.png

Welcome to the Exo.MAST API documentation!

Getting Started

This is documentation for the Exo.MAST API, one of the Barbara A. Mikulski Archive for Space Telescopes’ (MAST) web service APIs. This API allows users to make a variety of queries related to exoplanets.

Information on MAST’s other APIs can be found here.

Resolving Exoplanets

These queries allow you to disambiguate planet names and query for planet properties.

The following web query is used to

To get a list of planet identifiers including the canonical planet name use the following query:

GET /api/v0.1/exoplanets/identifiers/?name=kepler%201b   HTTP/1.1
Host: exo.mast.stsci.edu


HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{"ra": 286.80847916603085,
 "tessTCE": null,
 "planetNames": ["KIC 11446443 b",
                 "Kepler-1 b",
                 "TrES-2 b",
                 "KOI 1.01",
                 "GSC 03549-02811 b"],
 "dec": 49.316388888888895,
 "tessID": null,
 "starName": "TrES-2",
 "keplerID": 11446443,
 "keplerTCE": "TCE_1",
 "canonicalName": "TrES-2 b"}

To get properties associated with a given exoplanet canonical name use the following query:

GET /api/v0.1/exoplanets/TrES-2%20b/properties  HTTP/1.1
Host: exo.mast.stsci.edu


HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{"eccentricity_ref": "O'Donovan 2006",
 "exoplanetID": 5149,
 "Tp_upper": null,
 "Fe/H_url": "http://adsabs.harvard.edu/abs/2008ApJ...677.1324T",
 "transit_time_lower": 0.0010000000474974513,
 ...}

Detrended Flux Time Series Data Queries

These services allow you to query the Kepler Data Validation Time Series data (DV Data). There are queries for metadata, light curves, and plots. All queries are made based on Kepler ID and transit crossing event (TCE) number.

Listing TCEs

To get a list of TCEs associated with a given Kepler ID use the following query:

GET /api/v0.1/dvdata/8394721/tces/  HTTP/1.1
Host: exo.mast.stsci.edu


HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json; charset=UTF-8

{"TCE": ["TCE_1", "TCE_3", "TCE_2", "TCE_4"]}

Metatdata queries

There are two metadata queries. To get the data column names, types, and descriptions for DV Data queries, use the following query:

GET /api/v0.1/dvdata/info  HTTP/1.1
Host: exo.mast.stsci.edu

HTTP/1.1 200 OK
Content-Length: 12694
Content-Type: application/json; charset=UTF-8

{"DV Data Table Description": [
    {"description": "unique Kepler target identifier",
     "colname": "KEPLERID",
     "datatype": "int"},
    {"description": "name of extension",
     "colname": "EXTNAME",
     "datatype": "varchar(10)"}, ...

To get metadata about a specific Kepler target with or without associated TCE use the following query (if the TCE is ommitted, the TCE specific metatdata will simply not be returned):

GET /api/v0.1/dvdata/8394721/info/?tce=1 HTTP/1.1
Host: exo.mast.stsci.edu

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json; charset=UTF-8

{"DV Data Header": {DATE_OBS: "2009-05-13 00:01:07.137000",
                    PRADIUS; 7.414486640355018,
                    ...},
 "DV Primary Header": {NEXTEND: 6,
                       OBJECT: "KIC 8394721",
                       AV: 0.398,
                       ...} }

Data queries

To get the detrended lightcurve data table for a given Kepler ID and TCE use the following query:

GET /api/v0.1/dvdata/8394721/table/?tce=2 HTTP/1.1
Host: exo.mast.stsci.edu

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json; charset=UTF-8

{"fields":[{colname: "KEPLERID",
            datatype: "int",
            description: "unique Kepler target identifier"},
           ...],
 "data": [{'EXTNAME': 'TCE_2',
           'MODEL_WHITE': -0.02279440499842167,
           'PHASE': 8.375410079956055,
           'LC_INIT_ERR': 0.00019099553173873574,
           'LC_INIT': 0.0006834766245447099,
           'LC_WHITE': 2.559422492980957,
           'CADENCENO': 1105,
           'LC_DETREND': 0.0006834766245447099,
           'MODEL_INIT': 0.0,
           'TIMECORR': -0.0007000599289312959,
           'KEPLERID': 8394721,
           'TIME': 131.51169387994014},
          ...]}

Instead of getting the light curve as a data table, you can also directly query for phase folded plots of the light curve. The plots can be returned as html that can be directly viewed in a browser, or as embeddable componants suitable for inclusion in a larger website. You can request a simple phase folded plot for viewing in the browser with the following query:

GET /api/v0.1/dvdata/8394721/phaseplot/?tce=2 HTTP/1.1
Host: exo.mast.stsci.edu

HTTP/1.1 200 OK
Content-Type text/html; charset=UTF-8

<!DOCTYPE html>
<html lang="en">
  <head>
     <meta charset="utf-8">
     <title>Phased Light Curve</title>

     <link rel="s...
_images/phaseplot.png

To request the plot as embeddable elements simply add the embed argument:

GET /api/v0.1/dvdata/8394721/phaseplot/?tce=2&embed HTTP/1.1
Host: exo.mast.stsci.edu

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{resources: {js:   "\\n<script type=\\"text/ja...,
             css:"\\n<style>\\n /* BEGIN... },
 script: "\\n<script type-\\"text/ja...,
 div: "\\n<div class=\\"bk-root\\"...}

You can also request the plot split into even and odd phases:

GET /api/v0.1/dvdata/8394721/phaseplot/?tce=2&splitphase HTTP/1.1
Host: exo.mast.stsci.edu

HTTP/1.1 200 OK
Content-Type text/html; charset=UTF-8

<!DOCTYPE html>
<html lang="en">
  <head>
     <meta charset="utf-8">
     <title>Phased Light Curve</title>

     <link rel="s...
_images/evenodd.png

The phase plot can be displayed in a Jupyter Notebook as in the following example:

>>> import requests
>>> from IPython.display import display, HTML
>>> spectra_plot = requests.get("https://exo.mast.stsci.edu/api/v0.1/dvdata/6278762/phaseplot/?tce=TCE_1")
>>> display(HTML(str(spectra_plot.content.decode('utf-8'))))
_images/phaseplot.png

Exoplanet Spectra Queries

These queries allow you to access information about the spectra of a specific exoplanet.

This query allows you to get a list of spectra files associated with a given planet:

GET /api/v0.1/spectra/Hat-P-11%20b/filelist/   HTTP/1.1
Host: exo.mast.stsci.edu


HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json; charset=UTF-8

{"filename": ["HAT-P-11b_transmission_Fraine2014.txt"]}

To download a particular spectra file use the following query:

GET /api/v0.1/spectra/Hat-P-11%20b/file/HAT-P-11b_transmission_Fraine2014.txt  HTTP/1.1
Host: exo.mast.stsci.edu

HTTP/1.1 200 OK
Vary: Accept

# HAT-P-11b transmission spectrum
# This file contains:
# WFC3 G141 - GO 12449 - Fraine, et al., 2014, Nature
# Data history:
# Converted from: Fraine, et al., 2014, Nature
# ----------------------------------------------------------------------------------------
# Wavelength (microns)  Delta Wavelength (microns)  (Rp/Rs)^2   (Rp/Rs)^2 +/-uncertainty
# ----------------------------------------------------------------------------------------
         1.1530000    0.00950003   0.00350200   0.00004000
         1.1720001    0.00950003   0.00340700   0.00004700
         1.1900001    0.00950003   0.00342100   0.00004600
         1.2090000    0.00950003   0.00344500   0.00003800
         1.2280000    0.00950003   0.00335000   0.00004100
         1.2470000    0.00950003   0.00337700   0.00003800
         1.2660000    0.00950003   0.00338000   0.00004500
         1.2840000    0.00950003   0.00345700   0.00004000
         1.3030000    0.00950003   0.00343600   0.00003500
         1.3220000    0.00950003   0.00344800   0.00003900
         1.3410000    0.00950003   0.00347600   0.00004300
         1.3600000    0.00950003   0.00353600   0.00004400
         1.3789999    0.00950003   0.00349900   0.00004600
         1.3970000    0.00950003   0.00349800   0.00004000
         1.4160000    0.00950003   0.00352400   0.00004100
         1.4349999    0.00950003   0.00359100   0.00004400
         1.4540000    0.00950003   0.00352400   0.00004300
         1.4730000    0.00950003   0.00352000   0.00003900
         1.4920000    0.00950003   0.00344700   0.00003900
         1.5100000    0.00950003   0.00334400   0.00004500
         1.5290000    0.00950003   0.00351300   0.00004100
         1.5480000    0.00950003   0.00347100   0.00005000
         1.5670000    0.00950003   0.00343800   0.00004900
         1.5860000    0.00950003   0.00341400   0.00005300
         1.6040000    0.00950003   0.00338300   0.00004500
         1.6230000    0.00950003   0.00341500   0.00003800
         1.6420000    0.00950003   0.00348000   0.00004800
         1.6610000    0.00950003   0.00349800   0.00006000
         1.6799999    0.00950003   0.00337600   0.00007400

Instead of getting the spectra information as a data file, you can also directly query for spectra plots. The plot can be returned as html that can be directly viewed in a browser, or as embeddable componants suitable for inclusion in a larger website. You can request a spectra plot for viewing in the browser with the following query:

GET /api/v0.1/spectra/Hat-P-11%20b/plot/ HTTP/1.1
Host: exo.mast.stsci.edu

HTTP/1.1 200 OK
Content-Type text/html; charset=UTF-8

<!DOCTYPE html>
<html lang="en">
  <head>
     <meta charset="utf-8">
     <title>Time Series</title>

     <link rel="s...
_images/spectra.png

The spectra plot can be displayed in a Jupyter Notebook as in the following example:

>>> import requests
>>> from IPython.display import display, HTML
>>> spectra_plot = requests.get("https://exo.mast.stsci.edu/api/v0.1/spectra/Hat-P-11%20b/plot/")
>>> display(HTML(str(spectra_plot.content.decode('utf-8'))))
_images/spectra.png