Public API for the Sloan Digital Sky Survey III Spectral Data

Introduction

Data Release 9 of the Sloan Digital Sky Survey contains spectra for over 1.5 million galaxies, 230,000 quasars, and 670,000 stars covering 14,500 square degrees of the sky. This web site documents a programmatic interface (API) to all of this data. Using web calls, the data set can be queried, retrieving results as FITS files or JSON data objects.

This API is designed to allow you to build your own applications on top of SDSS data without having to worry about the details of how the data is stored or needing to parse FITS files. This API also saves the need to actually host the data itself (which, for the spectra, is roughly 800GB on disk for DR9). We look forward to seeing what you can do with it.

Note that the API will only serve data from Data Release 9 and above.

The API

The documentation for each API call can be accessed through the menu on the left. Please note that this is a public "preview release", which means that we are ready to have people start using the API, but we reserve the right to make changes to the calls or data responses. We strongly encourage feedback as people use the interface and will incorporate that into a final specification. While the current release only allows access to spectra, future releases will incorporate imaging and point source catalog data.

Forum

There is a public forum dedicated to the discussion of the SDSS API:

https://groups.google.com/d/forum/sdss-api

Styles

A few styles are employed to signify different types of information on these pages. The API works through HTTP requests for which responses are returned. Requests are styled like this:

http://api.sdss3.org/spectrum?id=boss.3840.55574.029.v5_4_45&format=json

Responses from the server are shown in a different color:

{
    "6300": [
        55555,
        55756
    ]
}

Keywords that are literal parameters or values of an API call are styled like this: mjd, instrument.

Downloading Files With wget or curl

There is a known issue in downloading files using curl or wget. A URL like these on the command line can be used to directly download a spectrum file:

% wget "http://api.sdss3.org/spectrum?plate=276&fiber=627&mjd=51909"
% curl -O "http://api.sdss3.org/spectrum?plate=276&fiber=627&mjd=51909"

Currently, the resulting filename will be "spectrum?plate=276&fiber=627&mjd=51909" instead of "spec-0276-51909-0627.fits".

As a (hopefully) temporary fix, you can specify these flags on wget or curl:

% wget --content-disposition "http://api.sdss3.org/spectrum?plate=276&fiber=627&mjd=51909"
% curl --remote-header-name -O "http://api.sdss3.org/spectrum?plate=276&fiber=627&mjd=51909"

Alternately (preferably), you can add "content_disposition = on" to a ~/.wgetrc file and/or "--remote-header-name" to a ~/.curlrc file. Any suggestions on how to fix this welcome!

Errors

Errors are returned as JSON objects for improperly formed requests or when no data matches the query provided. The error is in the form of a dictionary with at least two keywords: "type" and "detail". For example:

{
    "SDSSAPIError": {
        "type": "Required Parameter Missing",
        "detail": "A plate, mjd, and fiber number are required."
    }
}

Current error types are:

JSON

Most the responses to the API calls will return JSON objects. JSON is a format similar to XML, but lighter, more human-readable, and directly parseable by JavaScript. JSON objects can be encoded and decoded natively by Python; examples on how to do this with the SDSS API are forthcoming, but you can look at the Python documentation in the meantime.

Contact

Questions/comments/feedback can be sent to Demitri Muna: muna at astronomy dot ohio-state dot edu.

Updates

2013.02.07 Added new randomPlate API call, updated some examples to be valid calls, addressed some reported bugs.
2013.01.30 The plateMJDs call can now take an MJD and return the list of plates observed on that date.
2012.10.03 Added new "spectrumLines" API call, fixed some bugs.
2012.09.20 Initial public preview release.