DR7: Web API Reference

The recommended mechanism to access DASCH DR7 data is using the daschlab Python package. Under the hood, daschlab retrieves data using the web APIs documented on this page. You’re welcome to access these web APIs directly if the need arises. They are standard RESTful JSON-oriented interfaces that should be easy to access using any number of programming languages or client libraries.

The definitive listing of all endpoints may be found on the automatically-generated Web API Parameter Reference page. For DASCH users, the key endpoints are:

  • POST /dasch/dr7/querycat: Given a sky position and choice of photometric reference catalog, obtain a table of DASCH sources around that position, including the number of DASCH detections for each source.
  • POST /dasch/dr7/queryexps: Given a sky position, obtain a table of all exposures intersecting that position. The result indexes exposures rather than plates because some plates have multiple exposures, each of which has its own unique position on the sky.
  • POST /dasch/dr7/lightcurve: Given some of the metadata provided by a querycat invocation, obtain the lightcurve of a catalog source.
  • POST /dasch/dr7/cutout: Given some of the metadata provided by a queryexps invocation, obtain a cutout of a DASCH plate scan.
  • POST /dasch/dr7/mosaic_package: Obtain the information needed to download and construct a full-plate mosaic image.

These and other science-relevant endpoints are documented below.

The legacy “Cannon” data portal retrieves data using an entirely separate set of services. You can in principle fetch data from the Cannon portal programmatically, but this is strongly discouraged and there should never be a need to do so.

Overview

The DASCH DR7 web APIs are served using the same infrastructure that powers the user-facing Starglass website. They are standard RESTful JSON-oriented interfaces that can be accessed through one of two base URLs:

Base URLAPI key required?Rate limits
https://api.starglass.cfa.harvard.edu/public/NoLower
https://api.starglass.cfa.harvard.edu/full/YesHigher

The “full” API, which provides higher rate limits but requires you to provide a Starglass API key, is also known as the “registered” API in some contexts.

As a simple example, a fairly trivial Starglass API endpoint is GET /health. To invoke this endpoint via the “public” base URL (sometimes referred to as the public “definition”), you would fetch this URL:

https://api.starglass.cfa.harvard.edu/public/health

To invoke this endpoint from the command line with curl, you would run:

curl -H 'accept: application/json' https://api.starglass.cfa.harvard.edu/public/health

The result should be a very short JSON document:

{
  "status": "ready",
  "message": "DB is available and fully loaded"
}

To invoke the “registered” version of the API, a Starglass API key must be provided as an x-api-key HTTP header. To obtain such an API key, you must first create a Starglass account. Once signed in, click on the head-and-shoulders icon in the top right of any Starglass page, and a popup menu will show the API key assigned to your user account. It will be a 40-character string of letters and numbers. This API key should be treated as a secret and guarded accordingly.

To invoke an endpoint using the registered definition with curl, run a command of this form:

# replace the text [API_KEY] with your actual 40-character API key:
curl -H 'x-api-key: [API_KEY]' -H 'accept: application/json' \
  https://api.starglass.cfa.harvard.edu/full/health

To see how to invoke DASCH APIs in Python using the requests library, see the apiclient.py module of daschlab. Many of the key APIs are “POST requests” that require you to provide a JSON-formatted request body. This can be done so using curl, but is a lot easier in Python.

For completeness, we note that there is an additional pair of development API servers rooted at https://api.dev.starglass.cfa.harvard.edu/. These have IP address restrictions limiting their usage to DASCH team members, and they offer no special features compared to the generally-accessible APIs. Also, the “registered” API offers one additional endpoint that does not exist in the public API: GET /plates/p/{plate_id}/mosaic/download. For programmatic users, however, this endpoint does not offer any functionality that can’t be obtained with the GET /plates/p/{plate_id}/mosaic endpoint, which is available in both the public and registered definitions.

Additional Resources

  • The Web API Parameter Reference describes the inputs and outputs of each API endpoint formally, and allows you to test endpoints right from your browser. Because it is automatically generated, however, it does not contain much narrative documentation.
  • The Starglass API User Guide provides a guide-level introduction to using the Starglass APIs. It is aimed at non-scientific users and does not describe DASCH-specific endpoints.
  • The daschlab API Documentation documents the daschlab Python package, which can largely be thought of as providing a nice Python client for the web APIs described here.

Endpoints

For request and response schemas and a mechanism for testing each endpoint interactively from the web browser, see each endpoint’s definition in the parameter reference. Additional documentation here is only provided for those endpoints that benefit from cross-referencing with other elements of the DASCH DR7 documentation.

GET /api_key

See this endpoint’s entry in the parameter reference for information — this endpoint does not deal with astrophysical data.

GET /astronomers

See this endpoint’s entry in the parameter reference for information — this endpoint does not deal with astrophysical data.

GET /class

See this endpoint’s entry in the parameter reference for information — this endpoint does not deal (strictly) with astrophysical data.

GET /dasch/dr7/asset/photcal_asdf/{hexid}

This endpoint retrieves a single DASCH photometric calibration metadata file, which is stored in the ASDF format. Each file provides data relating to the photometric calibration of one plate (technically: one mosaic) against one photometric reference catalog. The contents of the file are documented on the Photometric Calibration ASDF File Contents page.

The only input parameter to the API is the {hexid} path parameter. Appropriate values to use here should be obtained from the result_id_apass or result_id_atlas columns of a table returned by the POST /dasch/dr7/queryexps.

When the invocation is successful, this API will return a 307 redirection status code pointing to a presigned AWS S3 URL. This URL can be used to obtain the ASDF metadata file using standard HTTP techniques. The body of the response will also be a tiny JSON document containing the same information:

{
  "location": <the_presigned_URL>
}

Depending on your use case, it may make sense to have your HTTP client layer process the redirection automatically, or to extract the target URL from either the Location HTTP header or the response body. The presigned URL is only valid for about 15 minutes.

POST /dasch/dr7/cutout

This endpoint retrieves a cutout of a full-plate image, returning a small FITS image.

Input parameters are provided as a JSON-format body to the POST request. They are:

{
  "plate_id": <string>,
  "solution_number": <number>,
  "center_ra_deg": <number>,
  "center_dec_deg": <number>
}

The cutout center position is specified as ICRS RA/deg in decimal degrees. Currently, the cutout size and pixel scale are not changeable parameters.

To properly produce a cutout, both a source plate ID and a WCS solution number are needed. This is because some plates were exposed multiple times. The same sky location may therefore appear in multiple places in one plate image! Further complicating matters is the fact that some exposures are known to DASCH by virtue of being logged in historical notebooks, but the pipeline was unable to determine a precise WCS solution matching the exposure. In such cases it is not possible to generate a useful cutout even if the plate was scanned and the exposure is believed to overlap the target position. In other cases, the pipeline obtains multiple WCS solutions even when only one exposure is cataloged. See the Exposure Identity section of the Exposure List Columns page for additional discussion. The solution_number input should match the solnum column of an exposure table, obtained via the POST /dasch/dr7/queryexps endpoint. The plate_id input should come from the series and platenum columns, with the plate number textualization padding the number with zeros so that it is always five characters long.

The response to a successful invocation is a single JSON-encoded string. That string, in turn, is the base64-encoded representation of a gzipped FITS file. Note that many FITS tools, including Astropy and DS9, can handle gzipped FITS data transparently, so you may not need to undo that compression manually. The FITS file contains the source image data, bilinearly interpolated onto a standard gnomonic (TAN) WCS projection centered at the specified coordinates.

All cutouts generated for the same input coordinates will have the same size and use the same WCS projection. At the moment, the generated cutouts will be 835 pixels on a side with a pixel scale of 0.0004 deg/pix, such that the output image is 20 arcminutes across in each dimension. For low-resolution plates (i.e., ones with large plate scales), this may substantially oversample the intrinsic resolution of the DASCH scan. However, there should be no plates where the cutout undersamples the intrinsic resolution of the scan.

Note that due to the large size and very heterogeneous nature of the plates, the DASCH astrometric solutions are not uniformly accurate, especially when the target area is found at the edge of a plate. Certain cutouts may show substantial (hundreds of pixels) astrometric offsets relative to the ideal. These are best understood as errors in the DASCH WCS solution, rather than errors in the plate itself (or the scanning process).

POST /dasch/dr7/lightcurve

This endpoint retrieves a raw lightcurve of a single DASCH catalog source, returning a table of detailed information.

Input parameters are provided as a JSON-format body to the POST request. They are:

{
  "refcat": <string>,
  "ref_number": <number>,
  "gsc_bin_index": <number>
}

These values should come from the table produced by an invocation of POST /dasch/dr7/querycat. The value of refcat should be consistent with whatever value was used in the catalog query (either "apass" or "atlas"), and ref_number and gsc_bin_index should match the corresponding values for the source of interest.

The response to a successful invocation is a single JSON-encoded list of strings. Each string should be treated as if it was one record in a line-oriented CSV file. The columns of the output are documented in the Lightcurve Data Table Columns page, with the important difference that the raw web APIs return columns named in the “camel-case” form (wordsLikeThis) rather than “snake-case” (words_like_this). The first record in the output list will contain the column names.

POST /dasch/dr7/mosaic_package

This endpoint retrieves a presigned AWS S3 URL that can be used to download a full-plate FITS image produced by the DASCH project, as well as relevant metadata needed to correctly interpret the FITS file.

This endpoint, unlike most of the other ones defined by the DASCH web APIs, returns data that require some substantial massaging to get them into the best shape for scientific analysis. The daschlab API function Session.mosaic() performs this work, and it is strongly recommended that you use daschlab rather than invoke this endpoint yourself. We refer to the files created by daschlab as “value-added” FITS mosaics, in contrast to than the “base” mosaics that you can access directly via this endpoint. If you wish to examine the code in daschlab that converts the latter into the former, refer to the daschlab.mosaics Python module.

Input parameters are provided as a JSON-format body to the POST request. They are:

{
  "plate_id": <string>,
  "binning": <number>
}

The plate_id can be any valid plate ID; in typical usage it would be computed from data in a table returned by a POST /dasch/dr7/queryexps invocation, as explained in the documentation for POST /dasch/dr7/cutout.

The binning should be either 1 or 16, and specifies the pixel binning level of the mosaic that you wish to access. A value of 1 selects the full-resolution plate mosaic; these files have an average size of 750 MiB and can be more than a gigabyte in size. A value of 16 selects the 16×16 downsampled mosaic, which is therefore approximately 256 times less data than the full-sized mosaic.

The body of the response is a JSON object as well:

{
  "baseFitsUrl": <string>,
  "baseFitsSize": <number>,
  "metadata": <complex-object>
}

The baseFitsUrl field is a presigned AWS S3 URL that can be used to obtain the base FITS mosaic using standard HTTP techniques. The URL is only valid for 15 minutes. The baseFitsSize field gives the size of that object in bytes.

The metadata field contains a rather complex JSON data structure constructed from the DASCH/Starglass server-side databases. Its internal structure is not documented. Refer to the Value-Added Mosaic FITS File Contents page for details on the structure of the resulting FITS file created by daschlab, which incorporates all of noteworthy elements of the metadata object.

POST /dasch/dr7/platephot

This endpoint is a bit like the combination of POST /dasch/dr7/cutout and POST /dasch/dr7/lightcurve, in that it retrieves a sample of the DASCH photometry for a single plate exposure, centered around a particular position.

Input parameters are provided as a JSON-format body to the POST request. They are:

{
  "plate_id": <string>,
  "solution_number": <number>,
  "refcat": <string>,
  "center_ra_deg": <number>,
  "center_dec_deg": <number>
}

The plate_id and solution_number should come from a table returned by a POST /dasch/dr7/queryexps invocation, as explained in the documentation for POST /dasch/dr7/cutout. The refcat should be either "apass" or "atlas". The query center is specified as an ICRS RA/dec in decimal degrees. The size of the query are is currently fixed (see below).

The response is in an identical format as that to POST /dasch/dr7/lightcurve. Rather than returning measurements of the same source from many plates, however, this API returns measurements of many sources from one plate. The Lightcurve Data Table Columns page correctly documents the columns of the returned data table. Here too, the web APIs return columns named in the “camel-case” form (wordsLikeThis) rather than “snake-case” (words_like_this).

The returned list of sources will approximately cover the same size as a cutout; that is, a radius of 10 arcminutes. Source selection is done using simple bounding RA/dec values and so may behave badly at the poles.

For multiple-exposure plates, the DASCH photometry pipeline attempts to associate each source detected in the plate image with a WCS solution based on catalog cross-matching. This in turn determines the RA/dec coordinates assigned to the source. (Another way to think about multiple-exposure plates: each pixel has multiple RA/dec values associated with it.) If you are looking at cutout of a multiple-exposure plate and comparing it to the results of a platephot query, then, there might be obvious sources in the cutout that seem not to have corresponding entries in the photometry extract. To obtain data for these sources, you may need to repeat your query for other solutions associated with your plate in question, taking care to adjust the center_ra_deg and center_dec_deg values to ensure that the query covers the same physical plate location as your primary query. If you wish to plot all of the detections in one view, you will need to remap the RA/dec coordinates of the additional detections to capture what those coordinates would be if they were interpreted according to the WCS solution associated with your primary query. Phew!

This API is slow, but it is the only way to obtain official DASCH photometry data for sources that didn’t match to anything in the reference catalog(s).

POST /dasch/dr7/querycat

This endpoint performs a cone-search query for sources from one of the DASCH reference catalogs (“refcats”).

Input parameters are provided as a JSON-format body to the POST request. They are:

{
  "refcat": <string>,
  "ra_deg": <number>,
  "dec_deg": <number>,
  "radius_arcsec": <number>
}

The refcat parameter should be either "apass" or "atlas". The search center position is specified as ICRS RA/deg in decimal degrees. The RA must be normalized to be between 0 and 360 degrees. The search radius is specified in arcseconds. The maximum allowed radius is 3600 arcsec (one degree).

The search is actually a “box search” rather than a cone. That is, the returned sources will form an approximate square shape on the sky, with a half-size matching the requested radius.

The response to a successful invocation is a single JSON-encoded list of strings. Each string should be treated as if it was one record in a line-oriented CSV file. The columns of the output are documented in the Catalog Data Table Columns page, with the important difference that the raw web APIs return columns named in the “camel-case” form (wordsLikeThis) rather than “snake-case” (words_like_this).

POST /dasch/dr7/queryexps

This endpoint queries the DASCH database of plates and their exposures, returning a list of all exposures intersecting the specified sky location.

Input parameters are provided as a JSON-format body to the POST request. They are:

{
  "ra_deg": <number>,
  "dec_deg": <number>,
}

The search center position is specified as ICRS RA/deg in decimal degrees. The RA must be normalized to be between 0 and 360 degrees.

The response to a successful invocation is a single JSON-encoded list of strings. Each string should be treated as if it was one record in a line-oriented CSV file. The columns of the output are documented in the Exposure List Data Table Columns, with the important difference that the raw web APIs return columns named in the “camel-case” form (wordsLikeThis) rather than “snake-case” (words_like_this). The first record in the output list will contain the column names.

Keep in mind that some plates have multiple exposures, so it is possible for a single plate to appear in the results multiple times if it has more than one exposure that covers the query location.

The returned result will include plates that have not been scanned, as well as ones that have. This is because historical logbook information gives the exposure centers of some of these plates, and there is enough information to approximately infer where they land on the sky. If such a plate appears to be important to your research, you can contact the HCO Plate Stacks staff to request more information about it. Cutouts can only be obtained for plates that were scanned and where the pipeline was further able to obtain a precise WCS solution for one or more exposures.

GET /health

See this endpoint’s entry in the parameter reference for information — this endpoint does not deal with astrophysical data.

GET /locations

See this endpoint’s entry in the parameter reference for information about its inputs and outputs.

The information returned by this endpoint includes basic latitude, longitude, and elevation information. You should not rely on its values in detail; prefer data from a better-maintained source, such as Astropy’s site list.

GET /notebooks

See this endpoint’s entry in the parameter reference for information — this endpoint does not deal with astrophysical data.

GET /notebooks/{notebook_id}

See this endpoint’s entry in the parameter reference for information — this endpoint does not deal with astrophysical data.

GET /notebooks/{notebook_id}/{page_num}

See this endpoint’s entry in the parameter reference for information — this endpoint does not deal with astrophysical data. It does, however, return URLs that allow you to access to photographs of the entire PHaEDRA notebook collection, which may be valuable for some research projects.

GET /plates

See this endpoint’s entry in the parameter reference for information, as well as the notes here on GET /plates/p/{plate_id}. The data returned by this API may be valuable for some research use cases.

GET /plates/p/{plate_id}

Retrieve detailed information about a specific plate.

The primary input parameter to this endpoint is the plate_id path parameter. This should be a Starglass plate ID, consisting of a lower-case series designator and a plate number padded to five digits with zeros; e.g., a03393. There is also an optional URL query parameter thumbnail_ratio, defaulting to 4. This controls the size of the thumbnail images in the API response. Scientific users are unlikely to need to change this from the default.

The body of the response is a JSON document containing a variety of plate data. The overall structure is:

{
  "plate_id": <string>,
  "class": <string>,
  "plate_comment": <string>,
  "has_markings": <boolean>,
  "markings_cleaned": <boolean>,
  "telescope": <string>,
  "location": <location_record>,
  "catalog_exposures": [<catalog_exposure_records>],
  "exposures": [<exposure_records>],
  "mosaics": [<mosaic_records>],
  "jacket_images": [<photo_records>],
  "jacket_thumbnail": [<photo_records>],
  "plate_images": [<photo_records>],
  "plate_thumbnail": [<photo_records>],
  "comment_astronomers": [<astronomer_names>],
  "mentions": [<mention_records>],
}

The plate_id is the same as the input parameter of the same name.

The class is the plate class assigned to the plate. This information can be informative about the purpose for which the plate was made, and potentially which emulsion it used. However, be aware that the DASCH database of plate class information is highly incomplete, and not always accurate.

The plate_comment is a curator’s comment associated with the plate, as logged in the DASCH database. If present, this may remark on the historical context of the plate, the presence of markings, astronomers believed to have use the plate, and so on.

The has_markings field is true if the plate had handwritten markings on it at some point. This information is derived from metadata logged into the DASCH database, which should be generally but not perfectly accurate.

The markings_cleaned field is true if the plate had handwritten markings that were erased prior to scanning by DASCH. This will be true for the vast majority of plates with markings that were scanned before 2024. This information is derived from metadata logged into the DASCH database, which should be generally but not perfectly accurate.

The telescope field gives a human-friendly name of the telescope behind which this plate was exposed.

The location field is a JSON object describing the location where the plate was exposed. Its structure is:

{
  "name": <string>,
  "lat": <number>,
  "lon": <number>,
  "elevation": <number>
}

The data here are the same as returned by the GET /locations endpoint, and likewise shouldn’t be taken too seriously. Note that some early Harvard telescopes were moved between multiple observatories, so the same telescope may appear at multiple locations.

The catalog_exposures field is a list of JSON objects describing exposures of the plate, as cataloged in historical logbooks. Each record has the following structure:

{
  "exposure_num": <number>,
  "datetime": <string>,
  "ctr_ra": <number>,
  "ctr_dec": <number>,
  "exposure_length": <number>
}

Here, the exposure_num is a sequence number used by the DASCH database, mapping to expnum in the output from POST /dasch/dr7/queryexps. The datetime is the midpoint time of the exposure in ISO 8601 format. The cataloged exposure center is given in ctr_ra and ctr_dec, which are decimal degrees. The exposure duration exposure_length is measured in minutes. Any of these values might be null, if the corresponding logbook information was partial.

The exposures field is a list of JSON objects describing exposures of the plate for which the DASCH pipeline was able to obtain a precise WCS solution. The size of this list can be larger, smaller, or the same as the catalog_exposures list: sometimes the pipeline can find a solution for which there is no documentation; sometimes an exposure is documented but can’t be solved by the pipeline. Each record has the following structure:

{
  "solution_num": <number>,
  "exposure_num": <number>,
  "datetime": <string>,
  "exposure": <number>,
  "ctr_ra": <number>,
  "ctr_dec": <number>,
  "crpix1": <number>,
  "crpix2": <number>,
  "delta_dec_x": <number>,
  "delta_dec_y": <number>,
  "delta_ra_x": <number>,
  "delta_ra_y": <number>,
  "naxis1": <number>,
  "naxis2": <number>
}

Here, solution_num gives the WCS solution number, corresponding to solnum in the output from POST /dasch/dr7/queryexps. If it is a non-negative number, expnum gives the exposure number that the DASCH pipeline associated with this solution. The datetime field is as in catalog_exposures, while exposure is equivalent to exposure_length. However, ctr_ra and ctr_dec have slightly different semantics: they map to the FITS headers CRVAL1 and CRVAL2 in a WCS solution that approximates the position of the plate on the sky, referenced to its full-size mosaic image; this RA/dec may not be close to the plate center. The fields naxis1, naxis2, crpix1, and crpix2 map to corresponding FITS headers. The fields delta_ra_x, delta_ra_y, delta_dec_x, and delta_dec_y map to FITS headers CD1_1, CD1_2, CD2_1, and CD2_2.

Be aware that DASCH plates are so large on the sky that WCS distortion terms are virtually always necessary to obtain a good fit across the field. If you construct WCS solutions from the values returned in these records, they will only be approximately accurate.

The mosaics field is a list of JSON objects describing DASCH images of the plate. In DASCH DR7, mosaics come in pairs: full-size files, and "binned" versions that are downsampled in 16×16 blocks. In principle, there can be multiple full-size mosaics of the same plate, but in DASCH DR7 this does not happen.

Each mosaic record has the following structure:

{
  "plate_id": <string>,
  "mosaic_num": <string>,
  "bin_factor": <string>,
  "flags": <string>,
  "rotation": <string>
}

Due to the invariants mentioned above, none of these fields are actually needed to obtain a plate mosaic file with GET /plates/p/{plate_id}/mosaic. The mosaic_num is a mosaic sequence number, expressed as a string padded to two digits with a zero. The bin_factor is either "01" or "16", indicating a full-size or binned mosaic, respectively. The flags and rotation fields are DASCH-internal identifiers that can distinguish between multiple mosiac variations but can be ignored by external users.

The jacket_images, jacket_thumbnail, plate_images, and plate_thumbnail fields are all lists of JSON objects describing photographs of the plate and/or its paper jacket. Each record has the following structure:

{
  "plate_id": <string>,
  "image_type": <string>,
  "portion": <string>,
  "url": <string>,
  "thumbnail": <boolean>,
  "thumbnail_ratio": <number>
}

The image_type field is either "plate" or "jacket". The portion field describes which portion of the object was photographed, and will take on one of the values: "all" (everything), "t" (top), "b" (bottom), "ll" (lower left), "lr" (lower right), "ul" (upper left), "ur" (upper right). If the portion is (e.g.) "ul", that does not guarantee that the other three corners were also photographed; blank areas were skipped.

The url field is a presigned AWS S3 URL that can be used to obtain the photograph using standard HTTP techniques. The URL is only valid for 15 minutes.

If true, the thumbnail field indicates that this record represents a downsampled thumbnail of an original image file. The thumbnail_ratio field represents the amount of downsampling that occurred; i.e., 4 indicates 4×4 pixel binning.

When the markings on an plate were erased, the DASCH plate photographs represent the only record of their content. Beyond that, the plate photographs should not be used for quantitative work; use only the FITS mosaics.

The comment_astronomers field gives a list of astronomer names mentioned in the plate_comment, as identified by a named-entity-recognition machine learning process. The names here are normalized to the Starglass preferred forms and can be passed to the GET /astronomers endpoint. The output of the ML algorithm is not completely accurate, and so some astronomer names mentioned in plate_comment may not be represented in this field, especially if they were abbreviated or misspelled.

The mentions field gives a list of mentions of the plate in PHaEDRA astronomer notebooks, as identified by citizen-science volunteers. Each mention record has the following structure:

{
  "author": <string>,
  "notebook": <string>,
  "page_num": <number>
}

This identifies the page in the notebook in which the plate was mentioned, as well as the author of the notebook mentioning the plate. Many notebooks have multiple credited authors, in which case there will be one mention record for each author. The author is in Starglass preferred form and can be passed to the GET /astronomers endpoint. The notebook is a PHaEDRA notebook ID (with the form phaedra1234) and can be passed to GET /notebooks/{notebook_id}, or combined with page_num and passed to GET /notebooks/{notebook_id}/{page_num} to retrieve an image of the page in question.

Note that "page number" is a slight misnomer; better would be "image sequence number". The numbers often map to page numbers, but sometimes get out of sync.

GET /plates/p/{plate_id}/download

This endpoint retrieves a plate photograph data asset. Rather than returning any content, this endpoint returns a HTTP redirect to a presigned AWS S3 URL containing the requested photograph. In order to know what to request, you generally need to issue a GET /plates/p/{plate_id} request, and the response to that request already includes a presigned image URL. So, programmatic users are unlikely to need to make use of this endpoint. See its entry in the parameter reference for more information.

GET /plates/p/{plate_id}/mosaic

This endpoint retrieves information about full-plate FITS imagery produced by the DASCH project, including a presigned AWS S3 URL that can be used to retrieve the data.

Scientific users should be aware of the POST /dasch/dr7/mosaic_package endpoint, which returns the same kind of presigned S3 URL but also includes additional metadata that include the best-available platewide astrometric solution. The daschlab Python API Session.mosaic() implements the logic necessary to combine all of these inputs to create a “value-added” whole-plate FITS image that represents the gold standard in terms of complete, accurate, and well-formed metadata.

The primary input parameter to this endpoint is the plate_id path parameter. This should be a Starglass plate ID, consisting of a lower-case series designator and a plate number padded to five digits with zeros; e.g., a03393.

Additional input parameters are specified as URL query parameters (e.g., .../mosaic?bin_factor=01). The only important one is bin_factor, which should be set to 01 or 16 depending on whether you wish to query the full-size or 16×16 binned mosaic. (See the discussion in the mosaics section of GET /plates/p/{plate_id}.) If unspecified, you will get results for the binned mosaic.

It is allowed to specify query parameters mosaic_num, rotation, and flags using values retrieved from a plate query, but given the invariants that hold in DASCH DR7, it should never be necessary or useful to do so.

The body of the response is a JSON object with the following form:

{
  "plate_id": <string>,
  "mosaic_num": <string>,
  "bin_factor": <string>,
  "flags": <string>,
  "rotation": <string>,
  "presigned_link": <string>,
  "object_size": <number>
}

Most fields here are the same as those described in the mosaics section of GET /plates/p/{plate_id}. The presigned_link field gives yet another presigned AWS S3 URL that can be used to download the mosaic data file. Like the others, it is valid for 15 minutes. The object_size field gives the size of the mosaic file in bytes.

The mosaic files are FITS images stored using fpack compression. The unbinned mosaics generally range in size from a few hundred megabytes to a gigabyte or more.

The mosaics returned by this endpoint have headers and metadata that may be inaccurate compared to the best available DR7 reduction. They will not necessarily include full WCS solutions, and the bitmap may need rotation or mirroring to align with the official DR7 astrometry.

GET /plates/p/{plate_id}/mosaic/download

This endpoint has the same structure as GET /plates/p/{plate_id}/mosaic, but redirects its caller to the presigned URL instead of returning JSON. For programmatic users, it should not be necessary to use. Scientific users are once again directed to the POST /dasch/dr7/mosaic_package endpoint.

POST /plates/search

See the description of this endpoint in the parameter reference. While it can be used for complex plate queries that may be of interest to research users, it only returns a list of plate IDs without additional metadata. To obtain the data needed for most research use cases, use POST /dasch/dr7/queryexps.

GET /series

See this endpoint’s entry in the parameter reference for information about its inputs and general usage.

Some of the outputs of this endpoint have are more technical in nature. The response body is a JSON list of results, each of which is a JSON object with the following structure:

{
  "series": <string>,
  "description": <string>,
  "num_plates": <number>,
  "aperture": <number>,
  "fitted_plate_scale": <number>,
  "nominal_plate_scale": <number>,
  "orientation": <string>
}

Here, num_plates is the number of plates in the Starglass database associated with this series. The aperture field is the aperture of the telescope used to make plates in the series, measured in meters. The nominal_plate_scale and fitted_plate_scale fields give the plate scale of plates belonging to the series, measured in arcsec per millimeter. The “fitted” value is derived from the DASCH WCS solutions. In a few series (e.g. misc) the plate scale is not consistent across all plates. The orientation is a identifier giving the typical orientation of the plates in the series with regards to North.