==================== Simple Cone Search ==================== Official bibliographic entry for published version :cite:p:`2008ivoa.specQ0222P`. :Status: ConeSearch 1.1 WD 2023-08-29 .. _`ConeSearch:acknowledgments`: Acknowledgments =============== This document was originally published as a document of the US National Virtual Observatory (NVO) [1]_ and then transcribed into an IVOA standards document format to become an IVOA Recommendation. The changes made in this transcription and in the process of producing the first recommendation are reported in Appendix :ref:`ConeSearch:appendix:nvochanges`. The Simple Cone Search version 1.03 document has been developed with support from the National Science Foundation’s Information Technology Research Program under Cooperative Agreement AST0122449 with The Johns Hopkins University. The ConeSearch-1.1 revision has been initially supported under the ASTERICS and ESCAPE projects (funded by the European Commission Framework Programme Horizon 2020 Research and Innovation Action, grant agreements n. 653477 and n. 824064 respectively). Work done within the two projects has been reported in :ref:`ConeSearch:appendix:first11changes`. .. _`ConeSearch:introduction`: 1 Introduction ============== This specification describes how a provider of an astronomical source catalog can publish that catalog to the Virtual Observatory in such a way that a simple cone search can be done. The data remains in the control of the data provider, served through a web server to the world, but the query profile and response profile are carefully controlled, as described below. It is intended that setting up this web service be simple enough that data providers will not have to spend too much time on it (their funding to support such services is typically small). At the same time, the service implementation and the data it provides can serve as a basis for more sophisticated tools. This specification does not specify how Cone Search services are implemented, or how the data are stored or manipulated. The concern of this specification is how the data are exposed to the world through well-defined requests and responses. This specification assumes that the data provider has already selected a catalog of astronomical sources. This catalog can be presented as a single table; it is expected that the table contains several columns. .. _`ConeSearch:role-within-the-vo-architecture`: 1.1 Role within the VO Architecture ----------------------------------- .. container:: float :name: ConeSearch:fig:archdiag .. raw:: latex \centering |image1| Fig. :ref:`ConeSearch:fig:archdiag` shows the role this document plays within the IVOA architecture :cite:p:`2021ivoa.spec.1101D`. .. _`ConeSearch:sec:2`: 2 Service Interface Requirements ================================ A service implementation that is compliant with this standard must meet the requirements described in the following 3 subsections (:ref:`ConeSearch:subsec:baseurl`, :ref:`ConeSearch:subsec:response`, and :ref:`ConeSearch:subsec:error`). .. _`ConeSearch:subsec:baseurl`: 2.1 Query resource ------------------ | The service must respond to a HTTP (or HTTPS) GET request represented by a URL having two parts: - | A base URL of the form | `http[s]:///?[&[...]] /?[&[...]]>`__ | where and are URI-compliant components indicating the domain address and local location path where the service is deployed. The may end with one or more locally supported URL arguments, ; these arguments are not recognized parts of the Cone Search protocol and thus are treated opaquely by clients of the service as part of the base URL. | Note that when it contains extra GET arguments, the base URL ends in an ampersand, &; if there are no extra arguments, then it ends in a question mark, ?. .. raw:: latex \begin{bigdescription} \item[Examples] \url{https://mycone.org/cgi-bin/VOsearch?}\\ \url{http://adil.ncsa.uiuc.edu/vocone?resolv&issurvey=T&} \end{bigdescription} Every query to a given cone search service uses the same base URL. - Constraints expressed as a list of ampersand-delimited GET arguments of the form: = where is a parameter name specified by this specification and is its value. The constraints represent the query parameters which can vary for each successive query. The order of the name-parameter pairs is not significant. - The baseURL and constraint list are concatenated to form the query. - The set of query constraints MUST include the following parameters, which are interpreted by the service with the stated meaning: **RA** a right-ascension in the ICRS coordinate system for the positon of the center of the cone to search, given in decimal degrees. **DEC** a declination in the ICRS coordinate system for the positon of the center of the cone to search, given in decimal degrees. **SR** the radius of the cone to search, given in decimal degrees. If set to zero (SR=0) it should not return an error condition because the request might describe an interest in retrieving only the metadata structure of the service’s response (i.e. discovery of the FIELDs delivered by the service). This is similar to setting MAXREC=0, i.e. a service metadata request as prescribed by DALI [2]_:doc:`ref <../DALI/DALI>`. .. raw:: latex \begin{bigdescription} \item[Example] \url{https://mycone.org/cgi-bin/search?RA=180.567&DEC=-30.45&SR=0.0125} \end{bigdescription} - As defined by DALI a service SHOULD also understand the following parameters: **MAXREC** to let the client limit the number of records returned or require a service metadata response. That means that a request including any of MAXREC or SR set with a value of 0 should require a metadata response. **RESPONSEFORMAT** to allow alternative optional response formats other than the mandatory VOTable one. Indeed, a Simple Cone Search service MUST provide responses in VOTable format :doc:`ref <../VOTable/VOTable>`, compliant with respect to what will be detailed in the next subsection (Sec. :ref:`ConeSearch:subsec:response`), but should also support the DALI RESPONSEFORMAT parameter. - The query MAY contain the optional parameter, **VERB**, whose value is an integer–either 1, 2, or 3–indicating verbosity which determines how many columns are to be returned in the resulting table. Support for this parameter by a Cone Search service implementation is optional. If the service supports the parameter, then when the value is 1, the response should include the bare minimum of columns that the provider considers useful in describing the returned objects (while still remaining compliant with this standard; see section :ref:`ConeSearch:subsec:response` below). When the value is 3, the service should return all of the columns that are available for describing the objects. A value of 2 is intended for requesting a medium number of columns between the minimum and maximum (inclusive) that are considered by the provider to most typically useful to the user. When the VERB parameter is not provided, the server should respond as if VERB=2. If the VERB parameter is not supported by the service, the service should ignore the parameter and should always return the same columns for every request. - There may be other parameters in the query, but this document does not specify their meaning or usage. If a query includes an optional parameter, either one specified by this document or not, that is not supported by the service implementation, the service can ignore it. In this case it is encouraged to add an INFO element in the response to include the parsing report for the ignored parameter. A query following this syntax represents a request for information on sources located within the specified cone on the sky. .. _`ConeSearch:subsec:response`: 2.2 Succesful response ---------------------- A successful response from a Cone Search service **must** be a table containing the astronomical sources whose positions are within the cone described by the query parameter values described in Sec. :ref:`ConeSearch:subsec:baseurl`. The service implementor may decide on the exact search criterion used to select the sources, including also other sources outside the cone. The response table **must** contain, alongside all possible columns available in the served source catalog: - one string column representing an ID for that record of the table. This identifier may not be repeated in the table, and it could be used to retrieve that same record again from that same table; - one numerical column representing the main value for the right-ascension of the source in the ICRS coordinate system; - one numerical column representing the main value for the declination of the source in the ICRS coordinate system. Right-ascension and declination of the output columns **MUST** be in decimal degrees. By default, the service **must** respond with an XML document in the VOTable:doc:`ref <../VOTable/VOTable>` format. However, if RESPONSEFORMAT is set (see Sec. :ref:`ConeSearch:subsec:baseurl`) the response table **should** match the requested format; if this format is unsupported the request **should** fail. When the response is in the default VOTable format (see Appendix :ref:`ConeSearch:appendix:a` for an example), the MIME-type of the HTTP response **should** be set to ``application/x-votable+xml``. The form ``text/xml`` can optionally be used, while the form ``text/xml;votable`` shall be considered legal only for backward compatibility reasons [3]_ and is strongly discouraged as it is not compliant with the MIME-type standard :cite:p:`std:MIME`. Simple Cone Search services **MUST** return VOTable version 1 documents. The response in VOTable format **MUST** follow the prescriptions on VOTable usage in result contained (currently) in Sec. 4.4 of the DALI 1.1 specification. Moreover it **MUST** comply with these conditions: - There must be a single RESOURCE with ``type=”results”`` in the VOTable, and that RESOURCE must contain a single TABLE. Additional RESOURCE(s) are allowed to enable, e.g., DataLink service descriptors. - The TABLE must have FIELDs where the following UCD values have been set. There must only be one FIELD with each of these UCDs: - Exactly one FIELD must have ucd="meta.id;meta.main", with an array character type (fixed or variable length), representing an ID string for that record of the table. This identifier may not be repeated in the table, and it could be used to retrieve that same record again from that same table. - Exactly one FIELD must have ucd="pos.eq.ra;meta.main", representing the right-ascension of the source in the ICRS coordinate system. - Exactly one FIELD must have ucd="pos.eq.dec;meta.main", representing the declination of the source in the ICRS coordinate system. - The above right-ascension and declination FIELD(s) must have the datatype attribute set to float or double, following the VOTable standard :doc:`ref <../VOTable/VOTable>`. - The VOTable may include an expression of the uncertainty of the positions given in the above mentioned fields to be interpreted either as a positional error of the source positions, or an angular size if the sources are resolved. If this uncertainty is not provided, it should be taken to be zero; otherwise, it may be set for all table entries with a PARAM in the RESOURCE which has a UCD that is set to phys.angSize;obs and has a value which is the angle in decimal degrees. Alternatively, a different value for each row in the table can be given via a FIELD in the table having a UCD set to phys.angSize;obs. - There may be other FIELDs in the table. Their specification should include a description, data-type, and UCD. .. _`ConeSearch:subsec:error`: 2.3 Error response ------------------ If the service detects an exceptional condition, it **should** return an error document with an appropriate status code, as specified by DALI, with, possibly, a Content-Type header to tell the client the format of the document. In the case the error is expressed in VOTable format, recommendation expressed in Section 4.4 of DALI **should** be followed. Errors **must** be reported in any of the following cases: - any of the three required paramaters (RA, DEC, SR) is missing; - their values cannot be parsed to floating point numbers; - the value numbers are out of range (DEC=91.0, for example). The service may also return an error if the search radius (given by the SR parameter) is larger than the one set by the maxSR element of the capability of the service described as a VO resource (see Sec. :ref:`ConeSearch:sec:3`). Queries targeting no records **should not** generate an error response but an empty metadata one (if applicable by format). .. _`ConeSearch:sec:3`: 3 The Resource Profile ====================== To describe a Cone Search service as a VOResource record the service provider **must** follow the SimpleDALRegExt :cite:p:`2022ivoa.spec.0222D` Recommendation (version 1.2 at the time of writing). More in detail, Section 2 (common requirements for Simple DAL Services) and Section 3.1 (for the specific extension definition for Simple Cone Search) must be followed. ConeSearch services, described as above, should be discoverable by means of queries to a Registry RegTAP :doc:`ref <../RegTAP/RegTAP>` interface, like: .. code:: sql SELECT ivoid, res_title, access_url, std_version FROM rr.resource NATURAL JOIN rr.capability NATURAL JOIN rr.interface WHERE standard_id LIKE 'ivo://ivoa.net/std/conesearch%' AND intf_role='std' The ``std_version`` attribute (i.e the version of the interface’s capability) could help, if present on the registered resource, to inform the client application about the ConeSearch version the service is following. Appendices ========== .. _`ConeSearch:appendix:a`: A Sample VOTable Response ========================= This is a sample of a legal response to a Cone Search query. .. code:: xml HEASARC Browse data service Please send inquiries to mailto:request@athena.gsfc.nasa.gov Faint Images of the Radio Sky at Twenty cm Source Catalog (FIRST) Integer key FIRST Source Designation Right Ascension Declination Peak 1.4GHz Flux Density (mJy) Estimated rms in at Source (mJy) Integrated 1.4GHz Flux Density (mJy)
384559 FIRST J120002.6+595708 180.0110042 59.9523889 1.11 0.139 1.14
385094 FIRST J120025.3+600103 180.1057250 60.0175556 2.89 0.142 2.56
384928 FIRST J120018.1+600236 180.0755500 60.0434750 19.38 0.145 19.23
384490 FIRST J115959.4+600403 179.9978875 60.0677083 1.01 0.147 1.20
.. _`ConeSearch:changes-from-previous-versions`: B Changes from Previous Versions ================================ .. _`ConeSearch:changes-from-wd-1.1-20200828`: B.1 Changes from WD-1.1-20200828 -------------------------------- - replaced resource description with SimpleDALRegExt references - clarified response behaviour when dealing with optional parameters - exemplified/explicited HTTPS being allowed - included OVERFLOW indicator (updating MAXREC usage) - updated all UCD(s) to conform to the UCD1+ specification - explicitly stated that RA and Dec responses must be in units of decimal degrees - re-instated changes done in the previous WD-1.1-20200828 - embedded errata 1, 2 and 3 for ConeSearch-1.03 - Complete revert of changes to restore clean 1.03 contents, in view of specific minor updates (listed here above) .. _`ConeSearch:appendix:first11changes`: B.2 Changes from REC-1.03 ------------------------- - moving base URL to a plain http://server/path? format - changed error response to comply with DALI - changed resource metadata importing directly from SimpleDALRegExt - relaxed RA and Dec FIELDs in response to allow float or double datatype - no more exactly one RESOURCE in response, now stating exactly one of type="results" - removed fixed version (1.0 or 1.1) for VOTable default response - Added DALI MAXREC and RESPONSEFORMAT - Added POST as optional HTTP query method - Addition of authors/editors. - Plain porting of the HTML document into ivoatex template, including change history, then modified it and reshaped. .. _`ConeSearch:changes-from-pr-1.02`: B.3 Changes from PR-1.02 ------------------------ - converted to Recommendation .. _`ConeSearch:changes-from-pr-1.01`: B.4 Changes from PR-1.01 ------------------------ - eliminated the choice of encoding an ERROR response in a PARAM that is a direct child of VOTABLE as this is not legal in the VOTable schema. - Allowed the use of the INFO element for error messages. - In examples, made sure PARAM elements have datatype attributes - Corrected wording to be definitive that positions are given in the ICRS coordinate system. - Other typos. .. _`ConeSearch:changes-from-pr-1.00`: B.5 Changes from PR-1.00 ------------------------ - Various typos. - Clarified description of VERB parameter: - Clarified what is meant by optional for client and server. - Clarified the meaning of the values. - Explicitly mention the 3 legal locations for ERROR messages. - Refer to string types as character arrays, as per the VOTable std. - Prefers text/xml;content=x-votable over text/xml;votable. - Added examples of error message, legal response in appendix. .. _`ConeSearch:appendix:nvochanges`: B.6 Changes from the original NVO Specification Document -------------------------------------------------------- - References to the original HTML document have been replaced with references to this IVOA specification. - Replaced references to "curator" with "data provider" or similar wording. - Replaced references to the NVO with references either to the IVOA or this specification, as appropriate. - Ambiguous language like "perhaps" has been replaced with more definitive wording where appropriate. Use of the word "will" is replaced with "must" and "can" with "may", in accordance with the definitions set in the preface. - Grammatical and spelling corrections have been made. - The content is organized into sections typical of an IVOA spec. - Description of the URL syntax is sharper, borrowing language from the SIA specification [SIA]. This includes: - More explicitly specifying the form of the URL. - Sharpening the definition of the input parameters. - Indicating that parameter order is not significant. - Stating explicitly that unsupported optional arguments should be ignored. - Adding examples. - Re-ordering information for improved flow. - The version of VOTable supported is explicitly stated. - Whereas the NVO version describes the parameter with ucd="OBS_ANG-SIZE" as "an expression of the opening angle of the cones", this version describes it specifically as "an expression of the uncertainty of the positions". - A note has been added to recognize the ambiguity in the location of the ERROR parameter. - The general description of the resource profile has been altered to allow rendering of the metadata to change according to the standards and conventions of the IVOA. - An editor’s note has been added that makes reference to the RM document [RM]. - A requirement that **MaxSR** be given in decimal degrees has been added. - For the **BaseURL** resource profile metadatum, the example has been replaced with a reference to the BaseURL syntax description. - An appendix has been added to describe the current practice for registering Cone Search services. .. [1] The NVO document: "Conesearch definition" (Roy Williams, Bob Hanish, Alex Szalay; April 2002) is currently available at this link: https://wiki.ivoa.net/internal/IVOA/ConeSearch/NVO_conesearch_April2002.html. .. [2] SR=0 is kept in this version of this specification for back compatibility. It is suggested to prefer the usage of MAXREC to enable metadata discovery .. [3] The original NVO specification allowed a MIME-type of text/xml;votable, this is why for backward compatibility this is still allowed but discouraged. .. |image1| image:: role_diagram.pdf :width: 90.0%