Exoplanet Archive Application Programming Interface (API) User Guide

The Exoplanet Archive data are accessed primarily through a Web interface, but users who have some programming knowledge may write scripts that automate specific search queries. These queries must follow a structure that is compatible with the Exoplanet Archive's application programming interface (API). This page provides information on using the API to automate data retrieval.

There is an alternate method of customizing an interactive table by directly modifying the table's URL to specify which columns/parameters to display. That approach is described in the Pre-filtering Tables help document.

To see some pre-generated queries of common use cases (e.g. "all confirmed planets in the Kepler field") that can be copied and pasted into a command-line interface or web browser, see the API Queries page.


Skip to:

Data Available Through the API:

Query Syntax
Build a Sample Query
Data Column Names and Descriptions
Column Lists
Examples of Valid Queries
Troubleshooting


Data Available Through the API

Currently, the Exoplanet Archive allows the following data tables to be accessed through the API:

Confirmed Planets

Data and Common Names Table Name
(What to use in queries)
Data Column Definitions Click to download all default columns
All confirmed planets (and hosts) in the archive
("Confirmed Planets")
exoplanets documentation

Kepler Objects of Interest (KOI)

Data and Common Names Table Name
(What to use in queries)
Data Column Definitions Click to download all default columns
Kepler Objects of Interest
("Cumulative")
the delivery name:

cumulative
documentation
Kepler Objects of Interest
("Q1 through Q17 DR24 KOI")
the delivery name:

q1_q17_dr24_koi
documentation
Kepler Objects of Interest
("Q1 through Q16 KOI")
the delivery name:

q1_q16_koi
documentation
Kepler Objects of Interest
("Q1 through Q12 KOI")
the delivery name:

q1_q12_koi
documentation
Kepler Objects of Interest
("Q1 through Q8 KOI")
the delivery name:

q1_q8_koi
documentation
Kepler Objects of Interest
("Q1 through Q6 KOI")
the delivery name:

q1_q6_koi
documentation

Threshold-Crossing Events (TCEs)

Data and Common Names Table Name
(What to use in queries)
Data Column Definitions Click to download all default columns
Threshold-Crossing Events
("Q1 through Q17 DR24 TCE")
the delivery name:

q1_q17_dr24_tce
documentation
Threshold-Crossing Events
("Q1 through Q16 TCE")
the delivery name:

q1_q16_tce
documentation
Threshold-Crossing Events
("Q1 through Q12 TCE")
the delivery name:

q1_q12_tce
documentation

Kepler Names, Kepler Stellar Properties and Kepler Time Series

Data and Common Names Table Name
(What to use in queries)
Data Column Definitions Click to download all default columns
Kepler Stellar Table
("All Kepler Stellar, which includes Q1-Q12, Q1-Q16 & Q1-Q17 DR 24")
the delivery name:

keplerstellar
documentation
Kepler Stellar Table
("Q1 through Q17 DR 24 Stellar")
the delivery name:

q1_q17_dr24_stellar
documentation
Kepler Stellar Table
("Q1 through Q16 Stellar")
the delivery name:

q1_q16_stellar
documentation
Kepler Stellar Table
("Q1 through Q12 Stellar")
the delivery name:

q1_q12_stellar
documentation
Kepler Time Series Table
("Kepler Time Series")

keplertimeseries

Also, either the quarter or a Kepler ID must be specifed, e.g.

keplertimeseries
&quarter=14

or
keplertimeseries
&kepid=8561063

documentation We recommend using wget calls to retrieve Kepler time series data. Web browsers can time out when data sets are large.

See Examples of Valid Queries, below, for examples of wget commands that retrieve Kepler time series.
Kepler Numbers, KOI Numbers and KIC Identifiers Table
("Kepler Names")
keplernames documentation

KELT Time Series

Data and Common Names Table Name
(What to use in queries)
Data Column Definitions Click to download all default columns
KELT light curves
(not including KELT Praesepe data)
("KELT")
kelttimeseries
or
kelt

Also, the field name must be specifed, e.g.

&kelt_field=N02
or
&kelt_field=N04

Note: Only one field can be specified per query

documentation

We recommend using wget calls to retrieve large sets of KELT time series data (e.g. the entire N02 or N04 field). Web browsers can time out when data sets are large.

The following queries are for the N02 field with an R-band magnitude of less than 9.

SuperWASP Time Series

Data and Common Names Table Name
(What to use in queries)
Data Column Definitions Click to download all default columns
SuperWASP Time Series Table
("SuperWASP Time Series")
superwasptimeseries

Also, either the tile or a SuperWASP ID must be specifed, e.g.

&tile=tile168060

or

&sourceid=1SWASP J191645.46+474912.3
documentation We recommend using wget calls to retrieve SuperWASP time series data. Web browsers can time out when data sets are large.

K2

Data and Common Names Table Name
(What to use in queries)
Data Column Definitions Click to download all default columns
"K2 Targets" k2targets documentation

Mission Stars

Data and Common Names Table Name
(What to use in queries)
Data Column Definitions Click to download all default columns

Mission Stellar List

"Mission Stars"

missionstars documentation

Mission and ExoCat Stellar List

mission_exocat documentation

Query Syntax

The Exoplanet Archive's API is based on the Structured Query Language (SQL), but only a subset of the SQL functionality is available to the user. Specifically, the user supplies fragments of a simple SQL SELECT statement and the full query is constructed from these (after syntax/content checking). These fragments are given as standard HTTP Web service parameter values, as described below.

An Exoplanet Archive API query can be submitted through a Web browser or entered as a wget command in a command-line interface (CLI). All queries must begin with the following base URL:

http://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?

Additional search parameters are appended to the base URL and can be customized to specify the type of information to be returned. The parameters are structured in a keyword-value pair format and separated by an ampersand (&). Parameters may be listed in any order, and all are optional except the table parameter.

The following table describes the allowed parameters and their usage:

Keyword Description Value Syntax and Examples
Table Specifies which table to query (see the table above for a full list of tables)

Note: This is a required parameter.

For Confirmed Planets: &table=exoplanets

For KOI Q1-16: &table=q1_q16_koi

Columns Specifies which columns within the chosen table to return. Columns must use a valid column name. If this keyword is not included in the query, all default columns are returned.

One column: &select=columnname

Multiple columns:

&select=columnname1,columnname2,columnname3

Distinct values can also be specified:

&select=distinct columnname1,columnname2,columnname3

To return all possible columns for the specified table, use &select=* (Note that this may return several hundred columns.)

Note: Column name text is not case-senstive. For example, "dec," "DEC," "Dec" and "dEC" are all acceptable.

Where Specifies which rows to return. Use this to search for a range of values, such as rows with a declination greater than 0. Parameters must use a valid column name.

Only return rows with a parameter greater than a given value: &where=parameter>value

  • Example: &where=dec>0

Only return rows with a parameter less than a given value: &where=parameter<value

  • Example: &where=dec<0

Only return rows containing a specific string of text: &where=parameter like 'searchstring'

  • Example: &where=pl_hostname like 'Kepler-22'

Note: If you are searching for null values in the column data, use is instead of like and remove the single quotation marks.

  • Example: &where=pl_hostname is null

Also, if you are listing multiple values for the same parameter, use and instead of repeating the entire keyword-value pair. For example:

  • Yes: &where=pl_discmethod like 'Microlensing' and st_nts > 0
  • No: &where=pl_discmethod like 'Microlensing'&where=st_nts>0

Values are case-sensitive!

Order Controls the order the rows are returned.
Acceptable keywords are order, order_by, and orderby, followed by the column names in your preferred order. Separate column names with commas.
  • Example: &order=dec

Rows are listed in ascending order by default, based on the values within the row. For example, if the column Dec is selected, the rows with the lowest Dec values are always at the top of the list.

To list results in descending order, add desc to the statement, as in:

  • Example: &order=dec desc
Cone Search Specifies an area of the sky to search for all objects within that area.

Right Ascension (ra), Declination (dec) and radius (radius or rad) must be listed with their respective coordinates or units. The units must be included in the radius specification (degrees, minutes, arcsecs) with a space preceding the unit name.

These four columns are always returned for cone search queries: ra, dec, dist (arcsec) and angle (degrees).

  • Example: &ra=291&dec=48&radius=1 degree
  • Example: &ra=291&dec=48&radius=1 degree&select=pl_hostname, pl_letter,ra,dec&order=pl_hostname,pl_letter
  • Example: &ra=291&dec=48&radius=1 degree&select=kepid,ra,dec
File Format Specifies the preferred file format of the output file. There are four options:

For IPAC Table Format/ASCII, any of the following entries are allowed and return the same results:

  • &format=ascii
  • &format=ipac
  • &format=ipac-ascii
  • &format=ipacascii
  • &format=ipac_ascii

For bar/pipe delimited:

  • &format=bar
  • &format=bardelimited
  • &format=bar-delimited
  • &format=pipe
  • &format=pipedelimited
  • &format=pipe-delimited

For XML/VOTable:

  • &format=xml
  • &format=votable
  • &format=vo-table
  • &format=vo_table

Note: File format names are not case-sensitive, so &format=IPAC is the same as &format=ipac.

Build a Sample Query

The following procedure will build a query to return Exoplanet Archive data from a Web browser.

  1. Start with the base URL:

    http://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?
  2. Add the text that specifies which data table to query (e.g. Confirmed Planets, Kepler Objects of Interest or Threshold-Crossing Events). In this example, we select Confirmed Planets, which is the exoplanets table:

    http://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?table=exoplanets
  3. Add the names of the column(s) in the table to be returned. If there are multiple selections, separate each with a comma. In this example, we select the Planet Host Name (pl_hostname), RA (ra) and Dec (dec). Note the separator between the table and column parameters is an ampersand (&).

    http://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?table=exoplanets&select=pl_hostname,ra,dec
  4. Add the parameter to order the rows by Dec in ascending order (lowest value at the top).

    http://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?table=exoplanets&select=pl_hostname,ra,dec&order=dec
  5. Add the preferred output file format. In this example, the output will be IPAC Table Format (ASCII).

    http://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?table=exoplanets&select=pl_hostname,ra,dec&order=dec&format=ascii
  6. Run the query in a Web browser and view the results:

    http://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?table=exoplanets&select=pl_hostname,ra,dec&order=dec&format=ascii

    Alternate method: To run the query on the command line using wget, put double quotation marks (") around the URL, add -O, and then the name of the output file (also in double quotations). In the example below, the output file will be named planets.txt. To learn more about wget, see the wget help document.

    wget "http://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?table=exoplanets&select=pl_hostname,ra,dec&order=dec&format=ascii" -O "planets.txt"

Data Column Names and Descriptions

The data columns in each table are named and described in the following documents:

Column Lists

Column lists for each table can be retrieved using the "getDefaultColumns" or "getAllColumns" keywords, in any format. Here are some examples:


Examples of Valid Queries

For more pre-generated queries that you can copy and paste into a command-line interface or web browser, see the API Queries page.

The following are examples of valid Web-based queries:

http://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?table=exoplanets&select=hd_name,st_mass&format=ascii

http://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?table=exoplanets&select=distinct pl_hostname&order=pl_hostname&format=ascii

http://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?table=k2targets&format=ipac&ra=90&dec=24&rad=1 degree

The following are examples of valid wget queries:

wget "http://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?table=exoplanets&format=csv" -O "defaults.csv"

wget "http://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?table=keplertimeseries&quarter=14&format=ipac" -O "Qtr14.tbl"

wget "http://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?table=keplertimeseries&kepid=8561063&format=ipac" -O "KIC8561063.tbl"

Note: Due to the large amount of metadata with Kepler releases, Kepler queries must specify a quarter. Each quarter is approximately 170 MB.



Troubleshooting

The Exoplanet Archive's API is based on the Structured Query Language (SQL), so make sure your queries follow some basic guidelines, including:

  • Always specify a table

  • Always separate multiple keyword-value pairs with an ampersand (&)

  • Always string multiple values for the same parameter with and instead of repeating the entire keyword-value pair. For example:

    Do: &where=pl_discmethod like 'Microlensing' and st_nts > 0
    Don't: &where=pl_discmethod like 'Microlensing'&where=st_nts>0

  • Avoid using spaces to separate keyword-value pairs.

  • Never use the following keywords or symbols for parameter values because they are not allowed: delete, drop, select and ; (semicolon).

  • Clauses are case-sensitive, e.g. "Microlensing" vs. "microlensing" or "kepler-22" vs. "Kepler-22."

  • Wildcards may be used in API where clauses, but must take the form "%25".
    The following example returns all rows in the exoplanets table whose pl_hostname begins with "Kepler."

    http://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?table=exoplanets&format=ipac&where=pl_hostname like 'Kepler%25'&order=pl_hostname

  • Date fields may be filtered in API where clauses using the SQL to_date() function.
    The following example returns all rows in the q1_q8 table with a KOI vet date that is after February 10, 2013.

    exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?table=q1_q8_koi&select=kepoi_name,koi_vet_date&format=ipac&where=koi_vet_date>to_date('2013-02-10','yyyy-mm-dd')&order=koi_vet_date

Here are some additional issues you may encounter and their suggested fixes:

Problem: The output is delivered in CSV format instead of the specified file format.

Possible Solution: Verify there are no spaces before or after the "format" keyword in your url - they invalidate the statement and the default file format, which is CSV, is returned.



Problem: You receive the following error message: ERROR Error Type: UserError - "table" parameter Message: "" is not a valid table.

Possible Solution: Your query doesn't specify which data table—such as all Confirmed Planets (exoplanets) or the Threshold Crossing Events table (q1_q16_tce). Add the appropriate parameter, beginning with &table=. Also, check that the parameter doesn't have a typo, such as "tble" vs. "table."



Problem:You receive the following error: ERROR Error Type: SystemError Message: -201:0:A syntax error has occurred.

Possible Solution: Check that the values for &select= are separated by commas, and not spaces. For example, uniqueid ra dec is invalid, and uniqueid,ra,dec is valid. Also, if you are selecting all columns, check that the parameter is select=* and not select=select*.



Problem: Your query works in a web browser, but not when submitted on the command line as a wget command.

Possible Solution: Make sure the query (the URL and appended parameters) is contained by double quotation marks ("). For example:

  • Correct:    wget "http://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?table=q1_q8_koi&format=csv" -O "defaults.csv"
  • Incorrect:    wget http://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?table=q1_q8_koi&format=csv -O "defaults.csv"

Last updated: 1 May 2015