Exoplanet Archive Application Programming Interface (API) User Guide

Skip to:

Build a Sample Query
Data Available Through the API

Query Syntax
Data Column Names and Descriptions
Column Lists
Examples of Valid Queries
Best Practices and Troubleshooting

Read This First: The archive is gradually transitioning its data tables to the IVOA-compliant Table Access Protocol (TAP) service.

All but two tables listed on this page Mission Stars (missionstars) and Mission and ExoCat Star List (mission_exocat)—have been migrated to the TAP service, and all new data tables will only have TAP support. If you're planning to access any table programmatically except the Mission Stars table, please use our TAP service.

Also, note that the examples on this page may no longer work as a result of the recent migration.

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.

Build a Sample Query

The following procedure will build a query to return Exoplanet Archive data from a web browser. Detailed explanations of the data available, syntax, and best practices are provided further on in this document.

Note that all queries require steps 1 and 2; all other parameters are optional based on the desired data subset.

  1. (Required) Start with the base URL: https://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?

  2. (Required) Add the text that specifies which data table to query. In this example, we select the Kepler Objects of Interest (KOI) Cumulative Table, which is entered as cumulative:

    https://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?table=cumulative

  3. Next, add a where or select clause and associated values that specify which objects and their data to return. In this example, we specify data only for objects with a Kepler disposition of candidate (like 'CANDIDATE') with an orbital period (koi_period) more than 300 days and a planet radius (koi_prad) less than 2. Note the separator between the table and column parameters is an ampersand (&), and there are spaces before and after "and." Also, the Kepler disposition value is in all caps (i.e., 'CANDIDATE') because it appears as such in the database, and database values are case-sensitive. If in doubt, check the interactive table to see how the value appears in the data column. Lastly, the database value must be contained in single quotation marks ( ' ).

    https://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?table=cumulative&where=koi_disposition like 'CANDIDATE' and koi_period>300 and koi_prad<2
  4. Add the parameter to order the rows by orbital period:

    https://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?table=cumulative&where=koi_disposition like 'CANDIDATE' and koi_period>300 and koi_prad<2&order=koi_period

  5. Add the preferred output file format. Comma-separated values (CSV) format is returned when no format is specified. In this example, the output will be IPAC Table Format (ASCII).

    https://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?table=cumulative&where=koi_disposition like 'CANDIDATE' and koi_period>300 and koi_prad<2&format=ascii

  6. Run the query in a web browser and view the results: https://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?table=cumulative&format=ipac&where=koi_disposition like 'CANDIDATE' and koi_period>300 and koi_prad<2&order=koi_period

    Note: Your web browser will convert the spaces and special characters to URL-encoded characters. For example, a space will convert to %20. The query will continue to work after it's encoded, though it may be a challenge to edit. The following reference webpage may help.


    7. 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 koi_candidates.txt. To learn more about wget, see the wget help document.

    wget "https://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?table=cumulative&select=koi_period>300,koi_prad<2&order=koi_period&format=ascii" -O "koi_candidates.txt"
Top

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
with parameters derived from a single, published reference that are designated as the archive's default parameter set

"Confirmed Planets"

 This table has been retired. Please use the archive's TAP service to programmatically retrieve these data from the Planetary Systems (PS) Table.
All confirmed planets (and hosts) in the archive with parameters compiled from multiple, published references

"Composite Planet Data"

 This table has been retired. Please use the archive's TAP service to programmatically retrieve these data from the Planetary Systems Composite Parameters (PSCompPars) Table.

All sets of planet and stellar parameters for confirmed planets and hosts in the archive

"Extended Planet Data"

 This table has been retired. Please use the archive's TAP service to programmatically retrieve these data from the Planetary Systems (PS) Table.
All aliases for a particular planetary system

"Aliases"

API support for this table was discontinued in late August 2021. Please use the newer System Aliases Lookup Service to retrieve a complete list of all names associated with a specific object that the archive recognizes. The output is a structured JSON table (example).

This help document describes how to use the service.
All confirmed planets and parameters discovered using the microlensing method

"Microlensing"

 API support for this table was discontinued in October 2021. We recommend using TAP to programmatically retrieve these data from the Microlensing (ML) table.
Top

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"

 API support for this table was discontinued in November 2023. We recommend using TAP to programmatically retrieve these data from the KOI Cumulative Delivery (cumulative) table.

Kepler Objects of Interest

"Q1 through Q17 DR25 Supplemental"

 API support for this table was discontinued in November 2023. We recommend using TAP to programmatically retrieve these data from the KOI Q1-Q17 DR25 Supplemental Delivery (q1_q17_dr25_sup_koi) table.

Kepler Objects of Interest

"Q1 through Q17 DR25 KOI"

 API support for this table was discontinued in November 2023. We recommend using TAP to programmatically retrieve these data from the KOI Q1-Q17 DR25 Delivery (q1_q17_dr25_koi) table.

Kepler Objects of Interest

"Q1 through Q17 DR24 KOI"

 API support for this table was discontinued in November 2023. We recommend using TAP to programmatically retrieve these data from the KOI Q1-Q17 DR24 Delivery (q1_q17_dr24_koi) table.

Kepler Objects of Interest

"Q1 through Q16 KOI"

 API support for this table was discontinued in November 2023. We recommend using TAP to programmatically retrieve these data from the KOI Q1-Q16 Delivery (q1_q16_koi) table.

Kepler Objects of Interest

"Q1 through Q12 KOI"

 API support for this table was discontinued in November 2023. We recommend using TAP to programmatically retrieve these data from the KOI Q1-Q12 Delivery (q1_q12_koi) table.

Kepler Objects of Interest

"Q1 through Q8 KOI"

 API support for this table was discontinued in November 2023. We recommend using TAP to programmatically retrieve these data from the KOI Q1-Q8 Delivery (q1_q8_koi) table.

Kepler Objects of Interest

"Q1 through Q6 KOI"

 API support for this table was discontinued in November 2023. We recommend using TAP to programmatically retrieve these data from the KOI Q1-Q6 Delivery (q1_q6_koi) table.
Top

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 DR25 TCE"

 API support for this table was discontinued in November 2023. We recommend using TAP to programmatically retrieve these data from the TCE Q1-Q17 DR25 Delivery (q1_q17_dr25_tce) table.

Threshold-Crossing Events

"Q1 through Q17 DR24 TCE"

 API support for this table was discontinued in November 2023. We recommend using TAP to programmatically retrieve these data from the TCE Q1-Q17 DR24 Delivery (q1_q17_dr24_tce) table.

Threshold-Crossing Events

"Q1 through Q16 TCE"

 API support for this table was discontinued in November 2023. We recommend using TAP to programmatically retrieve these data from the TCE Q1-Q16 Delivery (q1_q16_tce) table.

Threshold-Crossing Events

"Q1 through Q12 TCE"

 API support for this table was discontinued in November 2023. We recommend using TAP to programmatically retrieve these data from the TCE Q1-Q12 Delivery (q1_q12_tce) table.
Top

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


API support for this table was discontinued in November 2023. We recommend using TAP to programmatically retrieve these data from the Kepler Stellar Delivery (keplerstellar) table.

Kepler Supplemental Stellar Table

API support for this table was discontinued in November 2023. We recommend using TAP to programmatically retrieve these data from the Kepler Stellar Supplemental Delivery (q1_q17_dr25_sup_ks) table.

Kepler Stellar Table

"Q1 through Q17 DR 25 Stellar"

 API support for this table was discontinued in November 2023. We recommend using TAP to programmatically retrieve these data from the Kepler Stellar Delivery (q1_q17_dr25_ks) table.

Kepler Stellar Table

"Q1 through Q17 DR 24 Stellar"

 API support for this table was discontinued in November 2023. We recommend using TAP to programmatically retrieve these data from the Kepler Stellar Delivery (q1_q17_dr24_ks) table.

Kepler Stellar Table

"Q1 through Q16 Stellar"

 API support for this table was discontinued in November 2023. We recommend using TAP to programmatically retrieve these data from the Kepler Stellar Delivery (q1_q16_ks) table.

Kepler Stellar Table

"Q1 through Q12 Stellar"

 API support for this table was discontinued in November 2023. We recommend using TAP to programmatically retrieve these data from the Kepler Stellar Delivery (q1_q12_ks) table.

Kepler Time Series Table

"Kepler Time Series"

 API support for this table was discontinued in November 2023. We recommend using TAP to programmatically retrieve these data from the Kepler Stellar Delivery (keplertimeseries) table.

Kepler Numbers, KOI Numbers, and KIC Identifiers Table

"Kepler Names"

 Please use the archive's TAP service to programmatically retrieve these data from the Kepler Names (keplernames) Table. The database column names have also changed; see the documentation for details.
Top

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"

API support for this table was discontinued in October 2021. We recommend using TAP to programmatically retrieve these data from the KELT (kelttimeseries) table.

Top

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"

 API support for this table was discontinued in October 2021. We recommend using TAP to programmatically retrieve these data from the SuperWASP (superwasptimeseries) table.

Top

K2

Data and Common Names Table Name
(What to use in queries)		 Data Column Definitions Click to download all default columns
K2 Targets API support for this table was discontinued in November 2023. We recommend using TAP to programmatically retrieve these data from the K2 Targets (k2targets) table.
K2 Candidates This table has been retired. Please use the archive's TAP service to programmatically retrieve these data from the K2 Planets and Candidates (k2pandc) Table. See the documentation for database column names.
K2 Confirmed Names Please use the archive's TAP service to programmatically retrieve these data from the K2 Confirmed Names (k2names) Table. The database column names have also changed; see the documentation for details.
Top

Mission and ExoCat Stars

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

Mission Star List

"Mission Stars"

 missionstars documentation

Mission and ExoCat Star List

 mission_exocat documentation

Top

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:

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

Additional search parameters are appended to the base URL and may 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.

Keywords For Specific Queries

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 KOI Q1-16: &table=q1_q16_koi

select

(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

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.)

To return only the default columns for the specified table:

&select=defaults

(For more information about defaults, see the FAQ.)

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

count Can be used to return the number of rows which fulfill the given query, including queries using where clauses or cone searches.

Usage: &select=count(*)

  • Example: &select=count(*)&where=ra>45
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.

**Please see the Best Practices and Troubleshooting section about a known issue when the where clause is used for filtering with very precise values.

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=kepler_name like 'Kepler-52 c'

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=kepler_name 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=discoverymethod like 'Microlensing' and st_nts > 0
  • No: &where=pl_discmethod like 'Microlensing'&where=st_nts>0

Wildcards may be used in API where clauses, but must take the URL-encoded form "%25". The following example returns all rows in the KOI Cumulative Table with a Kepler Name that begins with "Kepler."

https://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?table=cumulative&format=ipac&where=kepler_name like 'Kepler%25'

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

ra, dec

(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

format

(Output File Format)

Specifies the preferred file format of the output file. There are five 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

For JSON:

  • &format=json
  • &format=JSON

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

Top

Data Column Names and Descriptions

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

Top

Column Lists

The column list call retrieves just the names of the columns for a specific table, and not the archive data. This is helpful if you just want to check whether a table contains a specific parameter. Use the "getDefaultColumns" or "getAllColumns" keywords, in any format. Here are some examples:


Top

Examples of Valid Queries

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

The following is an example of a valid web-based query:

The following are examples of valid wget queries:

  • wget "https://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?table=keplertimeseries&quarter=14&format=ipac" -O "Qtr14.tbl"
  • wget "https://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.


Top

Best Practices and 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 URL-encoded form "%25". The following example returns all rows in the exoplanets table whose pl_hostname begins with "Kepler."
    https://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?table=cumulative&format=ipac&where=kepler_name like 'Kepler%25'
  • 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.

    https://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

  • Always encode special characters in web queries. For example, the encoding symbol for plus signs (+) is %2B, so a web query for object names requiring a plus sign, such as BD+20 594 b, would be:
    https://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?table=exoplanets&format=ipac&where=pl_name like 'BD%2B20 594 b'

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. Spaces invalidate the statement so the default file format, which is CSV, is returned instead.


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 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 "https://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?table=q1_q8_koi&format=csv" -O "defaults.csv"
  • Incorrect:    wget https://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?table=q1_q8_koi&format=csv -O "defaults.csv"

Problem: Your query works as a wget command, but not in a web browser.

Possible Solution: Check that you haven't specified an object name with a special character, such as +, which should be encoded as &2B. For example:

  • Correct:  https://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?table=exoplanets&format=ipac&where=pl_name like 'BD%2B20 594 b'
  • Incorrect:  https://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?table=exoplanets&format=ipac&where=pl_name like 'BD+20 594 b'

Problem: You filtered a column and received results containing entries that should not be included.

Possible Solution: The value you entered for filtering may have been too small (i.e. precise), which invokes a known issue in the database. This issue is known to affect some columns in the TCE table.

Users who wish to construct API constraints with very small or very large numbers may need to explicitly instruct the Oracle database how to process their constants. Oracle defaults having decimal numbers stored as custom "NUMBER" values, which fit in the range 1.0e-130 and 9.9999e+125. This can cause problems for queries against columns that are stored as "binary double" (and can therefore have values as small as 1.e-308 and large as 1.e+308). In order to pass Oracle constants in this extended range properly, the numerical arguments in where clause constraints should be formatted as follows:

to_binary_double ( 'your_limit' )

The quotes in the statement above are significant. Without them, Oracle will parse your limit as a NUMBER before handing to the to_binary_double() routine. This will result in zero being used for numbers below the lower NUMBER limit and fail with an overflow beyond the higher limit ( Example: where boot_fap < to_binary_double('1.e-200') ).

Last updated: 18 January 2024