Home
About the Archive
Data
Tools
User Guides & Helpdesk

System Notice: The NASA Exoplanet Archive will be unavailable on Thursday, June 20 from 4:30-5:00pm PDT.

Exoplanet Archive Application Programming Interface (API)

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.

Skip to:

Data Available Through the API

Query Syntax

Build a Sample Query

Data Column Names

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:

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
("Cumulative")		 the delivery name, e.g.

"cumulative" 		documentation
Kepler Objects of Interest
("Q1 thru Q6 Kepler Candidates")		 the delivery name, e.g.

"q1_q6_kepler_candidates" 		documentation
Kepler Objects of Interest
("Q1 thru Q8 KOI")		 the delivery name, e.g.

"q1_q8_koi" 		documentation
Kepler Objects of Interest
("Q1 thru Q12 KOI")		 the delivery name, e.g.

"q1_q12_koi" 		documentation
Threshold-Crossing Events
(Threshold-Crossing Events)		 "tce" documentation
Kepler Numbers, KOI Numbers and KIC Identifiers Table
("Kepler Names")		 "keplernames" documentation
Kepler Stellar Table
("Kepler Stellar")		 "keplerstellar" documentation
Kepler Time Series Table
("Kepler Time Series")		 "keplertimeseries"

Also the quarter must be specifed, eg.

"keplertimeseries
&quarter=14"		 documentation We recommend you use wget calls to retrieve Kepler time series data - browsers can time out when the data sets are large.

See Examples of Valid Queries, below, for examples of wget commands that retrieve Kepler time series.

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 Kepler Stellar, : &table=keplerstellar

For Threshold-Crossing Events: &table=tce
Columns Specifies which columns within the chosen table to return. Columns must use a valid column name.

One column: select=columnname

Multiple columns:

&select=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=plnthostname+like+'Gliese+876'

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=plnthostname+is+null
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 a plus (+) and desc to the statement, as in:

  • &order=dec+desc
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

The columns of each table are listed and described in the following documents:


Examples of Valid Queries

Here are some additional examples of working queries.

The following is an example of a Web-based query:

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

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"

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 (&)
  • Avoid using spaces to separate keyword-value pairs (i.e. after the &). Instead, use plus signs (+) as separators.
  • Never use the following keywords or symbols for parameter values because they are not allowed: delete, drop, select and ; (semicolon).

  • 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%3Eto_date%28%272013-02-10%27,%27yyyy-mm-dd%27%29&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: Check that there are no spaces before the &format= parameter, which invalidates the statement and thus returns the default file format, which is CSV.


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—all Confirmed Planets (exoplanets), all Kepler Objects of Interest (koi), or the Threshold Crossing Events table (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=koi&format=csv" -O "defaults.csv"
  • Incorrect:    wget http://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?table=koi&format=csv -O "defaults.csv"

NASA IPAC NExScI Caltech

Home
About the Archive
Data
Tools
User Guides & Helpdesk