Search API

The Search functionality of the starglass API is made available to POST requests against the “/plates/search” endpoint. The POST request expects a JSON SearchInput object to be present in the body of the request and returns a JSON array listing all plate IDs matching the filter described by the search object.

The SearchInput object

Note that this documentation is not updated automatically. A best effort will be made to keep this document updated, but the automatically generated developer documentation is the place to see the up to date description of all elements of the search API. However, the general operating principles here will remain true. For the most up to date information, see the automatically generated documentation.

The SearchObject is a JSON object with multiple sub-objects representing different plate search conditions. When multiple search conditions are provided, they are combined in via a logical AND. Currently the only method to execute a logical OR with the search API is to execute two requests and perform a set union of the results. Some conditions (currently just the astronomical object and location search) cannot be combined in a single query and therefore the API returns an error when they are both present.

Conditions

Right Ascension and Declination Coordinates

  • JSON Field Name: coordinates

  • Description: A sub-object containing a set of RA/Dec coordinates and additional fields describing how to search for them. Used to find all plates containing the specified coordinates. Algorithm used to search depends on the value of the precision field

  • Sub Fields:

    • ra: Right ascension of search location in degrees (J2000 Epoch), range accepted is 0-360 degrees

    • dec: Declination of search location in degrees (J2000 Epoch), range accepted is -90-90 degrees

    • precision: Algorithm to use to determine if a plate contains the specified location. Currently accepted values are low, medium, and catalog. The algorithms will be described further below

    • radius: Search radius in arcseconds around the specified location, only used with the catalog search algorithm, otherwise the value is ignored. The default value here is 600 arcseconds

Precision Algorithms

  • low: We have broken the sky up into bins that are approximately 1 degree of declination x 1 degree of declination in size. When plates are scanned, we record all of the bins that they overlap with so that we can quickly identify all plates that may contain a point. The low precision search places the query coordinates in a bin and returns all plates that overlap with that bin. This is a quick look up operation as all these values are indexed; however, there will be false positives returned for plates where the bin overlap occurs on the plate edge and the query coordinates are over that edge. Note that also since the indexing requires plate scanning, unscanned plates will not be returned by this method.

  • medium: This algorithm is the same as the low precision method; however after identifying the plates within the Bin, we then perform an additional filtering step using the CRPIX1, CRPIX2, CRVAL1, CRVAL2, NAXIS1, NAXIS2, CD1_1, CD1_2, CD2_1, and CD1_2 FITS header keywords to create a WCS and determine if the query location is within the bounds of the plate. We use the wcss2p function from wcslib to determine the pixels that the coordinates map to and then check that against the bounds of the image. This does not account for lens distortion so there is still the chance of false positives or false negatives, but for most plates, we’d expect results to meet user needs. There is a performance trade off here as results will take multiple seconds rather than sub second times to be returned

  • catalog: This algorithm is fundamentally different from the other two. Instead of looking for plates that contain a point, it instead looks for plates whose recorded center is within a certain angular distance (specified by the radius field in arcseconds) of the query location. This enables us to search through both scanned and unscanned plates. We use inbuilt functionality within the underlying database to enable these searches so these queries are fairly performant. The angular distance algorithms used in the database are based on GIS coordinates rather than astronomical coordinates. In testing we observed the DB overestimating the distance between points. To account for this, we add a buffer to the user specified radius to slightly increase the search area.

Astronomical Object

  • JSON Field Name: object

  • Description: A sub-object describing how to search for an astronomical object with a fixed location in the SIMBAD database. In practice, the identifier field is used to look up the RA and Dec of the object from SIMBAD. Those RA and DEC values are then used to perform a coordinate search based on the precision and radius fields. See the RA/DEC Coordinate search filter for more information on how exactly the search is performed.

  • Sub Fields:

    • identifier: SIMBAD identifier of an astronomical object to search for. This value is directly passed to the SIMBAD API to look up the RA and Dec coordinates of the object.

    • precision: Algorithm to use to determine if a plate contains the specified location. Currently accepted values are low, medium, and catalog. The algorithms are described above in the RA/DEC section.

    • radius: Search radius in arcseconds around the specified location, only used with the catalog search algorithm, otherwise the value is ignored. The default value here is 600 arcseconds

    Series

    • JSON Field Name: series

    • Description: A string indicating what series to limit searches too, currently only a single series is supported. Leaving out the field leads the search to be performed across all series. See the Series Page or the series endpoint for more information on the series available.

Astronomer Names

  • JSON Field Name: astronomers

  • Description: An array of strings listing the names of astronomers. The search will return plates that have known connections to those astronomers (either via the plate being mentioned in a phaedra notebook or through a comment from the plate stacks curatorial team). There is assumed to be a logical OR for the astronomer names. In the future we may change this search filter to enable specification of connection logic and to specify relationship type of interest. Formal names can be found by querying the /astronomers endpoint and using values from the name field

Date

  • JSON Field Name: date

  • Description: Subobject representing the date range to search. Dates are accepted in the format YYYY-MM-DD{T}HH:mm so April 8th 1961 at 1:15 PM will be 1961-04-08T13:15. There is no time zone data present in the database so times are assumed to be local to where the plate was photographed. The Date range is fully inclusive of both the start and end values. The end value is optional and defaults to 24 hours after the start value

  • Sub Fields:

    • start: Beginning of the date range to search over. String representing a date with the format YYYY-MM-DD{T}HH:mm so April 8th 1961 at 1:15 PM will be 1961-04-08T13:15.

    • end: End of the date range to search over. String representing a date with the format YYYY-MM-DD{T}HH:mm so April 8th 1961 at 1:15 PM will be 1961-04-08T13:15. Defaults to 24 hours after the start value if excluded.

Scanning Status

  • Json Field Name: scanned

  • Description: string determining whether or not only scanned plates, only unscanned plates, or both be returned. Scanned status is determined by whether or not there is a record of a completed computational scanning pipeline in the DB. Defaults to returning all plates.

  • Accepted Values:

    • scanned: Only return plates that have been scanned

    • unscanned: Only return plates that have not been scanned

    • all: Return all plates

Day of Year

  • JSON Field Name: doy_of_year

  • Description: A Subobject represetning a specific day of the year to search for. The search will return all plates that were taken on the specified day of the year for all years returned by the date query.

  • Sub Fields:

    • month: The month of the year to search for. This value should be an integer between 1 and 12.

    • day: The day of the month to search for. This value should be an integer between 1 and 31.

Number of Exposures

  • JSON Field Name: exposure_count

  • Description: A Subobject representing a range of exposure counts to search for. A minimum and maximum value can be specified. The search will return all plates that have an exposure count within the specified range (inclusive). To search for plates with a specific exposure count, set the minimum and maximum values to the same value.

  • Sub Fields:

    • min_exposures: The minimum number of exposures to search for. This value should be an integer greater than or equal to 0.

    • max_exposures: The maximum number of exposures to search for. This value should be an integer greater than or equal to 0.

Presence of Markings

  • JSON Field Name: markings

  • Description: A subobject representing whther or not there were marking placed on a plate, also whether or not those markings have been cleaned off. The search will return all plates that have the specified marking status.

  • Sub Fields:

    • has_markings: Boolean value indicating whether or not the plate has markings. If true, the search will return plates with markings. If false, the search will return plates without markings. If not present, the search will return plates with or without markings.

    • markings_cleaned: Boolean value indicating whether or not the plate has had its markings cleaned off. If true, the search will return plates whose markings were cleaned off. If false, the search will return plates that did not have markings removed. If not present, the search will return plates with or without cleaned markings.

Search Sorting

By default, the search API returns results in alphabetical order by plate ID. However, alternative sorting can be indicated through the value of the sort field of the search object. Currently supported values are:

  • asc: Sort results in ascending alphanumeric order by plate ID

  • desc: Sort results in descending alphanumeric order by plate ID

  • mentions: Sort results by the number of mentions of the plate in the Phaedra notebooks. Plates with more mentions will be returned first. Note that this sorting method will significantly increase the time it takes to return results as it requires additional queries of the database.

Examples

Location and Series

Search for all plates in the I series that contain the point RA: 15, DEC: 43.6. Use the FITS header to determine if a plate contains the point (excluding distortion terms)

{
	"coordinates": {
		"ra": 15.0,
		"dec": 43.6,
		"precision": "medium"
	},
	"series": "i"
}

Plates Connected to Astronomers

Return all plates determined to have a connection (Curator annotation or mention in a phaedra notebook) to Annie Jump Cannon or Henrietta Swan Leavitt

{
	"astronomers": ["Annie Jump Cannon",
				"Henrietta Swan Leavitt"]
}

Plate Centroid and Date Range

Search for all plates with a recorded center within 20 arc seconds of astronomical object M31 (Andromeda) taken between midnight on January 8th 1950 and midnight on February 3rd 1950

{
	"object": {
		"identifier": "M31",
		"precision": "catalog",
		"radius": 20
	},
	"date": {
		"start": "1950-01-08T00:00",
		"end": "1950-02-03T00:00"
	}
}