Hypatia Catalog API v2.1.1

What is this?

The Hypatia Catalog API allows you to write programs that access the Hypatia Catalog outside of the browser. Let's say that you've written a program in Python to do computational work for your next exoplanet-related discovery, and it takes in data from the Hypatia Catalog as input. You could manually copy and paste data from the plotting tool and get your program to parse the data, but after many requests it can become tedious over time. Instead, with a few simple commands, you can use the API to request the data and it will come to you in an easy to use, machine-readable format.

Should I use this?

Many computational researchers depend on APIs like this one for their work because it allows their code to access or update online data automatically, without going to the web interface by hand. The Hypatia API will allow you to access properties of the star, element abundances, catalog data, and scatter/histogram plots from the command line (outlined below). If you're not planning on writing code, or if you only need a few stellar abundances for a particular star, you may wish to use the interactive plotting tool instead.

What is an API?

An application programming interface (API) allows you to write code that interacts with websites. Most major websites provide an API as a courtesy to developers everywhere. For instance, here is what the API for Spotify looks like.

How do I try it out?

Many programming languages have libraries that can access web APIs. We will focus on the Python programming language and the Requests library for interfacing with APIs. Just like you need to put on socks before putting on shoes, you will need to make sure Python is installed before installing Requests. (We've linked to Requests version 2; you're welcome to use Requests III instead, but keep in mind the syntax may be different.)

Once you've downloaded Python and Requests, type in "python3" in your terminal to get started. For Windows users, Python 3 should be in your Start menu.

We've highlighted some text in yellow like this; as you go through the documentation, all you have to do is copy and paste the commands provided and it will go through the API.

Technical information

If this is your first time using an API and you're using Python and Requests, you may skip this section.

All users are restricted to 1000 requests per hour. Once you log in, the number of requests you have made in the past hour will show up here.
Rate limit information can be accessed through the response headers:

• X-Rate-Limit-Limit: The number of allowed requests in the current period
• X-Rate-Limit-Remaining: The number of remaining requests in the current period
• X-Rate-Limit-Reset: The number of seconds left in the current period

Any requests exceeding the limit will return an HTTP 429 error.

Authentication is via HTTP Basic Auth, using the API key as the username and "api_token" as the password. Logging in to this page on your web browser does not log you in to the API. Many API libraries have HTTP Basic Auth built in, but in case you need to do it manually:

• Take the string of the API key, followed by :api_token.
• Then encode it to base 64.
• Then stick Basic in the front, including the space.
• Set the header HTTP_AUTHORIZATION to the resulting string and you should be good to go.

Only HTTPS traffic is allowed. In the interest of security, any HTTP traffic will return a 400 error, without redirection to HTTPS.

All inputs are accepted as URL parameters and are optional unless otherwise marked.

All outputs are returned in JSON as long as they are valid (HTTP 200). Client errors (HTTP 4xx) are returned as plain text. Server errors (HTTP 5xx) are returned as the HTML for the "Internal error" page. Make sure your code is able to handle these error responses gracefully.

The API returns the following error codes:
200 = Valid code. Response is provided as JSON.
401 = Invalid API key, or API key not provided.
410 = API no longer in service. Check hypatiacatalog.com or nataliehinkel.com for a new version.
429 = Too many requests. User has exceeded quota.
Other 4xx = Something is wrong with the query. An error message will be left in the response.
503 = Temporarily down for maintenance. Try again later.
Other 5xx = Server error. Check your query; if it looks OK then check hypatiacatalog.com to see if the server is up. It may come back later.

GET solarnorm

Returns a list of solar normalizations used by Hypatia.

Inputs

none

Outputs

author Author(s) of the paper referencing the solar normalization.
year Year of the paper referencing the solar normalization.
version Letter following year of the paper referencing the solar normalization.
notes Additional notes as needed.
identifier Used to identify the solar normalization in later API commands (e.g. GET composition).

GET https://hypatiacatalog.com/hypatia/api/v2/solarnorm
Authentication: Basic (username: your-api-key-here, password: api_token)

Python code:
import requests
API_KEY = "your-api-key-here"
entry = requests.get("https://hypatiacatalog.com/hypatia/api/v2/solarnorm",auth=(API_KEY,"api_token"))
print(entry.json())

Result:
[
    {
      "notes": "",
      "identifier": "abs",
      "year": 0,
      "version": "",
      "author": "Absolute"
    },
    {
      "notes": "",
      "identifier": "and89",
      "year": 1989,
      "version": "",
      "author": "Anders & Grevesse"
    },
    ...
]

GET element

Returns a list of elements used by Hypatia.

Inputs

none

Outputs

An array with all the elements used in Hypatia, including singly ionized elements.

GET https://hypatiacatalog.com/hypatia/api/v2/element
Authentication: Basic (username: your-api-key-here, password: api_token)

Python code:
import requests
API_KEY = "your-api-key-here"
entry = requests.get("https://hypatiacatalog.com/hypatia/api/v2/element",auth=(API_KEY,"api_token"))
print(entry.json())

Result:
[
  "FeH",
  "OH",
  "MgH",
  "AlH",
  "CaH",
  "TiH",
  "CH",
  "LiH",
  "NaH",
  ...
]

GET catalog

Returns a list of catalogs used by Hypatia.

Inputs

none

Outputs

author Author(s) of the paper referencing the solar normalization.
year Year of the paper referencing the solar normalization.
version Letter following year of the paper referencing the solar normalization.
override_name Used to override the name of the paper as needed.
li Returns true for the lithium versions of Luck et al. 2007 and 2015.
id Used to identify the catalog in later API commands (e.g. GET data).

GET https://hypatiacatalog.com/hypatia/api/v2/catalog
Authentication: Basic (username: your-api-key-here, password: api_token)

Python code:
import requests
API_KEY = "your-api-key-here"
entry = requests.get("https://hypatiacatalog.com/hypatia/api/v2/catalog",auth=(API_KEY,"api_token"))
print(entry.json())

Result:
[
  {
    "author": "Adamow et al.",
    "override_name": null,
    "li": false,
    "version": "",
    "year": 2014,
    "id": 514
  },
  {
    "author": "Luck et al.",
    "override_name": null,
    "li": true,
    "version": "",
    "year": 2015,
    "id": 515
  },
  ...
]

GET star

Returns data for each star in the Hypatia database as well as its planets. Multiple stars can be submitted at once.

Inputs

name Searches all names for a star (e.g. name=HIP 57 instead of hip=57 ). Search is case insensitive. Any name can be used, not just the preferred name returned by Hypatia. Multiple IDs can be submitted. New in v2.
hip The Hipparcos ID of the star. Multiple IDs can be submitted.
hd The Henry Draper ID of the star, case sensitive. Multiple IDs can be submitted.
twomass The 2MASS ID of the star. Multiple IDs can be submitted.
gaiadr2 The Gaia Data Release 2 ID of the star. Multiple IDs can be submitted.
tyc The TYC ID of the star. Multiple IDs can be submitted.
other Searches other names of the star, case insensitive. Multiple IDs can be submitted.
Note: Only one of the above needs to be submitted. Submit multiple IDs to look up multiple stars. IDs can be a mix of the above if needed.

Outputs

status Returns "found" if the star is found and "not-found" if the star is not found.
name The preferred name for the star, in the order of these available: HIP, HD, 2MASS, Gaia DR2, WDS, other names. hip,hd,bd,dist,2mass,gaia_dr2,tyc,other_names,...,ra_proper_motion,dec_proper_motion,bmag The property of the star as mentioned in the Hypatia Catalog. Changed in v2, see notes.
planets Returns each planet hosted by the star. For each planet we get these variables: name,p,p_min_err,p_max_err,m_p,m_p_min_err,m_p_max_err,e,e_min_err,e_max_err,a,a_min_err,a_max_err. Changed in v2, see notes.

GET https://hypatiacatalog.com/hypatia/api/v2/star?hip=12345&hip=56789&hip=113044
Authentication: Basic (username: your-api-key-here, password: api_token)

Python code:
import requests
API_KEY = "your-api-key-here"
params = {"name": ["HIP 12345","HIP 56789","HIP 113044"]}
entry = requests.get("https://hypatiacatalog.com/hypatia/api/v2/star",auth=(API_KEY,"api_token"),params=params)
print(entry.json())

Result:
[
  {
    HIP 12345 wasn't found
    "hip": 12345,
    "status": "not-found"
  },
  {
    HIP 56789 was found and has no planets
    "bd": "B+47 1894",
    "dist": 99.206,
    "teff": 6829.0,
    "logg": null,
    "planets": [], no planets
    ...
    "hip": 56789, there's the HIP
    ...
    "status": "found", there's the status
    ...
  },
  {
    HIP 113044 was found and has one planet
    "bd": null,
    ...
    "planets": [ one planet found
      {
        "e_err": 0.078,
        "p": 1311.0,
        "m_p_err": 0.13,
        "e": 0.07,
        "name": "b",
        "a": 2.56,
        "p_err": 49.0,
        "m_p": 1.26,
        "a_err": 0.17
      }
    ],
    ...
    "hip": 113044, there's the HIP
    ...
    "status": "found", there's the status
    ...
  }
]

GET composition

Returns a list of compositions for a given element, star, and solar normalization, and computes the median and mean value for that group. More than one group can be supplied by submitting the groups one after the other: element, star, solar normalization, element, star, solar normalization, etc. Alternatively, you can submit element, star, element, star, etc., in which case Lodders et al. 2009 is assumed.

Inputs

element Name of the element, case insensitive. You may include or omit the trailing H.
name Searches all names for a star (e.g. name=HIP 57 instead of hip=57 ). Search is case insensitive. Any name can be used, not just the preferred name returned by Hypatia. New in v2.
solarnorm Identifier for the solar normalization. See GET solarnorm for solar normalization identifiers.
Note: There should be the same number of elements, stars, and (if included) solar normalizations. If solar normalizations are omitted, Lodders et al. 2009 is assumed for all compositions.

Outputs

name The preferred name for the star in the group, or the Hipparcos ID if available.
all_names All names for the star in the group. New in v2.
element The element for the group.
solarnorm The solar normalization for the group.
all_values All values referencing this group as well as their corresponding catalogs.
median The median value and any catalogs that reference it. More than one catalog may be returned in case of a tie.
mean The mean value.
plusminus_error For stars with multiple abundance vaules for a given element, this is half of the absolute range of all vaules. For stars with a single abundance value for a given element, this is a representative error.

GET https://hypatiacatalog.com/hypatia/api/v2/composition?name=HIP 98355&element=ca&solarnorm=asp05
Authentication: Basic (username: your-api-key-here, password: api_token)

Python code:
import requests
API_KEY = "your-api-key-here"
params = {"name": "HIP 98355", "element": "ca", "solarnorm": "asp05"}
entry = requests.get("https://hypatiacatalog.com/hypatia/api/v2/composition",auth=(API_KEY,"api_token"), params=params)
print(entry.json())

Result:
[
  {
    "hip": 98355,
    "solarnorm": "asp05",
    "all_values": [
      {
        "catalog": {
          "author": "Edvardsson et al.",
          "override_name": null,
          "li": false,
          "version": "",
          "year": 1993,
          "id": 584
        },
        "value": -0.49
      },
      ...
    ],
    "median": [
      {
        The median value is -0.49. Since two catalogs have this value, both values are returned
        "catalog": {
          "author": "Edvardsson et al.",
          "override_name": null,
          "li": false,
          "version": "",
          "year": 1993,
          "id": 584
        },
        "value": -0.49
      },
      {
        "catalog": {
          "author": "Bensby et al. 2014]",
          "override_name": null,
          "li": false,
          "version": "",
          "year": 2014,
          "id": 537
        },
        "value": -0.49
      }
    ],
    "element": "caH",
    "mean": -0.457 there's the mean
  }
]

Note: If you are using Requests, multiple sets of elements, stars and solar normalizations are defined using arrays like this:

params = {"hip": [98355,98355], "element": ["fe","ca"], "solarnorm": ["asp05","asp05"]}

You may omit the solar normalization, in which case Lodders et al. 2009 is assumed:

params = {"hip": [98355,98355], "element": ["fe","ca"]}

GET data

Returns scatter plot and histogram raw data for each graph on the Hypatia Catalog, as though it were submitted on this website. As a demonstration, try submitting this without any query variables; you will receive the X and Y coordinates of each point on the [Si/H] vs [Fe/H] default plot. Similarly, if you submit mode=hist, you will receive the default histogram provided by "Stars With/Without Planets".

Inputs

mode If mode is set to hist, returns a histogram provided by "Stars With/Without Planets". filter1_1 The first filter. This field can be a stellar property, planet property, or numerator for the element ratio. Stellar and planet properties are listed in GET star. Element ratios are listed in GET element; it is case sensitive and the trailing H should be omitted.
filter1_2 The denominator for the element ratio, if one is given for filter1_1. Leave blank for H.
filter1_3 Minimum value for the filter.
filter1_4 Maximum value for the filter.
filter2... Same for the second filter.
filter3... Same for the third filter.
xaxis1, xaxis2 X axis for the scatter plot or histogram. Follows the same pattern as filter1_1 and filter1_2. If omitted, [Fe/H] is assumed.
yaxis1, yaxis2 Y axis for the scatter plot. Follows the same pattern as filter1_1 and filter1_2. If omitted, [Si/H] is assumed.
zaxis1, zaxis2 Z axis for the scatter plot. Follows the same pattern as filter1_1 and filter1_2.
statistic Choose whether to return the median or the mean. If omitted, median is assumed.
cat_action Choose whether to allow or exclude given catalogs. If omitted, exclude is assumed.
catalogs Catalog IDs to allow or exclude. See GET catalogs to choose catalog IDs.
star_action Choose whether to allow or exclude given stars. If omitted, exclude is assumed.
star_list Stars to allow or exclude. Any name can be given, and names are case insensitive. If an integer is given, Hipparcos IDs are assumed (unless star_source is set to hd). Changed in v2.
star_source Choose wheter stars are Hipparcos IDs or Henry Draper IDs. If omitted, hip is assumed.
normalize Normalizes the histogram.
solarnorm Solar normalization identifier. See GET solarnorms to choose a solar normalization. If omitted, Lodders et al. 2009 is assumed.

Outputs

solarnorm Information about the given solarnorm.
count Number of stars or planets in the query.
labels Labels for each axis in the query.
values If a scatter plot, return all the names, X/Y/Z coordinates, and values for each filter provided. Changed in v2. For backwards compatibility in version 1, hip is set to the Hipparcos ID is given for stars that have them, and -9999 for those that don't.
all_hypatia If a histogram, return the values of each bin for all Hypatia stars.
exo_hosts If a histogram, return the values of each bin for only the Hypatia stars that host planets.
edges If a histogram, return the edges for each bin.

GET https://hypatiacatalog.com/hypatia/api/v2/data
Authentication: Basic (username: your-api-key-here, password: api_token)

Python code:
import requests
API_KEY = "your-api-key-here"
entry = requests.get("https://hypatiacatalog.com/hypatia/api/v2/data",auth=(API_KEY,"api_token"))
print(entry.json())

Result:
{
    "count": 5584,
    "solarnorm": {
      "notes": "",
      "identifier": "lod09",
      "year": 2009,
      "version": "",
      "author": "Lodders et al."
    },
    "labels": {
      "xaxis": "[Fe/H]",
      "yaxis": "[Si/H]"
    },
    "values": [
      {
        "hip": 111944,
        "xaxis": -0.195,
        "yaxis": 0.06
      },
      {
        "hip": 92512,
        "xaxis": -0.51,
        "yaxis": -0.18
      },
      ... 
    ]
}

GET https://hypatiacatalog.com/hypatia/api/v2/data?mode=hist
Authentication: Basic (username: your-api-key-here, password: api_token)

Python code:
import requests
API_KEY = "your-api-key-here"
params = {"mode":"hist"}
entry = requests.get("https://hypatiacatalog.com/hypatia/api/v2/data",auth=(API_KEY,"api_token"), params=params)
print(entry.json())

Result:
{
    "solarnorm": {
      "notes": "",
      "identifier": "lod09",
      "year": 2009,
      "version": "",
      "author": "Lodders et al."
    },
    "count": 6156,
    "exo_hosts": [
      0,
      0,
      0,
      ...
    ],
    "all_hypatia": [
      2,
      3,
      6,
      ...
    ],
    "labels": {
      "xaxis": "[Fe/H]",
      "yaxis": "Number of Stellar Systems"
    },
    "edges": [
      -2.5,
      -2.3225,
      -2.145,
      ...
    ]
}

ASCII tables

If you wish to convert JSON data to ASCII tables, we recommend using the astropy library, which contains tools for writing ASCII tables. A word of warning: many of the queries provided by the Hypatia API don't have the same number of columns for each row. For instance, if you submit a request for multiple stars and one of those stars has planet information in the catalog, it won't fit neatly into one table. In order for the astropy ASCII table functions to work, each row has to have the same number of columns.

Here is how to convert the default Hypatia scatter plot (x=[Fe/H], y=[Si/H]) to an ASCII table, assuming that astropy is installed:

import requests
from astropy.io import ascii

API_KEY = "your-api-key-here"
entry = requests.get("https://hypatiacatalog.com/hypatia/api/v2/data",auth=(API_KEY,"api_token"))
json = entry.json()
ascii.write(json['values'],format="fixed_width_two_line",formats={"xaxis":"%.2f","yaxis":"%.2f"})
  
Result:
   hip xaxis yaxis
------ ----- -----
111944 -0.20  0.06
 92512 -0.51 -0.18
 85805 -0.10  0.12
 88839 -0.00  0.09
 88788  0.04  0.23
  7539  0.19  0.22
 56278  0.06  0.07
 56363  0.40  0.46
 56572  0.26  0.34
 56884 -0.07 -0.07
...

Version history

2.1.1: October 31, 2023 - plusminus_error' is now a returned field for composition queries. For stars with multiple abundance vaules, this is half of the absolute range of the data, for stars with a single abundance value this is a representative error.

2.1.0: April 21, 2023 - The 'composition' API query has been redesigned to return data more quickly and to efficiently use the server's resources. The format of the query parameters and returned JSON are exactly the same.

2.0.2: Added support for NASA Exoplanet Archive. Fixed median value in GET composition.

2.0.1: Fixed star_list in GET data. Entering a Hipparcos or HD number by itself should return the correct star.

2.0.0: A major update to the API to handle stars without Hipparcos IDs, asymmetrical errors in planet properties, and non-numeric Henry Draper IDs. See above for full details.

1.0.1: Added clarification to GET element regarding multiple set requests.
1.0.0: Initial release.

Reference

This API is modeled on the Toggl API.
Further reference: here and here.