Suggested CGI Protocol for Services Queryq
The following describes the keywords and values for a suggested CGI page that returns a listing of available resources. The output of this page is a formatted XML document describing matching resources at the site hosting this page. Both GET and POST methods should be supported by the CGI page.
All parameters are optional.
Query Parameters
The query parameters will generally be encoded in some fashion in the URL.
- position
- A string containing two real numbers separated by either whitespace or a comma giving the J2000 position of interest. Only a single position field is supported.
- searchradius
- A single positive real number giving the search radius in degrees. If a position is specified this gives the search radius to be used for the query. Some appropriate default value will be chosen if the searchradius field is not specified.
- time
- A string containing two times giving an interval of interest. The second time shall be later than the first. The formats shall use the ISO time format
yyyy-mm-ddThh-mm-ss.sss
where the T and following fields are optional. The two times shall be separated by whitespace or a comma. If only a single date is given then the second date is assumed to be exactly one day later. E.g., ‘1999-12-13’ is equivalent to ‘1999-12-13T00:00:00 1999-12-14T00:00:00’
- exposure
- A single non-negative number giving the minimum exposure requested in seconds.
- bibcode
- A BibCode formatted string.
- author
- A string which gives the last name of the author or observer. The string may include whitespace.
- obsid
- A string describing a particular mission/observation. The structure of the obsid should be rigorously defined.
Resource restrictions
The following parameters are generally expected to limit the URLs returned, but not to affect the actual URL string. The distinction between query parameters and resource restrictions is, however, intended only as a guide.
- observatory
- A string specifying the observatory/mission for which data is desired. This should ideally use some controlled vocabulary of observatory/mission names.
- regime
- One of the following strings specifying the information on a particular regime is requested.
This field may be repeated if multiple regimes are desired.
- all
- Data from all regimes (this is the default)
- optical
- Include data from optical observations
- radio
- Include data from radio/microwave observations
- ir
- Include data from IR observations
- uv
- Include data from UV observations
- gammaray
- Include data from gamma-ray observation
The host site may wish to apply this criterion fairly liberally. E.g., Near UV and IR data will likely be included within optical.
- type
- This field describes the kind of URL which is being returned. This field may be repeated.
- all
- Get all kinds of links (this is the default)
- catalog
- Return links to catalog queries and query services
- bibliography
- Return links to bibliography search services
- article
- Return links to services which link to articles
- cutout
- Return links to image cut-out services
- data
- Return links to archival data services
- misc
- Return links to miscellaneous services
- spatialres
- This field is a single real number giving the minimum spatial resolution in arcseconds for services to be returned.
- timeres
- This field is a single real number giving the minimum temporal resolution in seconds for which services are desired.
- keywords
- This is a free text field which may be used to specify a search for services that match a particular list of keywords. The action of this keyword will differ depending upon the data provider.
Query control parameters
- maxlink
- The maximum number of links to return. If a link ‘rating’ has been implemented, then only the highest rated links should be returned.
- useallinfo
- This parameter has the values ‘yes’ or ‘no’. If set, the service is requested to return only links which can effectively use all of the specified query parameters. E.g., if both a time and a position are given, then only services which can simultaneously be searched by time and position will be returned.
- portals
- This yes/no valued parameter controls whether the service should return portal URLs, i.e., links that require no query parameters to build. Portals can be of various types, e.g., the ADS query page may be thought of as a bibliography portal, while the SkyView advanced interface is a cutout portal. The default is no.
- checkhits
- This yes/no parameter is used to request the service to check the number of hits available at a service before including the link and to only include links for which there are hits. Note that the query service may not perform this check even when requested, however a field returned in the output will indicate if the check has been made. The default is no.
- ratelinks
- This yes/no parameter is used to request that the service provide a link rating. The service need not be responsive, but a link rating field with a null value should be returned if no rating is supplied.