Note: This is a project development document. The software and services available here are prototypes. They are being built in order to evaluate tools and methods and are subject to frequent and unannounced revisions. The NVO project encourages wide use and experimentation of these prototypes, but they may not work with all browsers or user environments. Software and services intended for general use will be clearly identified. We appreciate feedback from the user community.


NVO compliance

Simple Cone Search

A first guide for data Curators

This page describes how a curator of an astronomical source catalog can publish that catalog to the National Virtual Observatory in such a way that a simple cone search can be done. The data remains in the control of the curator, served through a web server to the world, but the query profile and response profile are carefully controlled, as described below. We hope that setting up this web service is simple enough that curators will not have to spend too much time on it -- we know that their NVO funding is small -- but we hope to use the data they serve as a basis for more sophisticated tools.

The NVO is not interested in how services are impemented, how data is stored or manipulated. The NVO is interested in how data is exposed to the world through well-defined requests and responses.

We are assuming that the curator has already selected a catalog of astronomical sources. Perhaps for the moment we can keep things simple by asking for at most one catalog to be published per person. The publication will be easier if a catalog is chosen with few columns.

  1. Compliance REQUIRES that a web service be maintained with the following characteristics:

    The curator has thus made a web service where the meaning of the query is a cone-search on the sky. There may be other keywords in the query, but this document does not specify their meaning or usage.

    Optional keywords are:

  2. The service will respond with an XML document in the VOTable format, that represents a table of astronomical sources whose positions are within the cone. There may also be other sources outside the cone -- the service implementor may decide on the exact search criterion.

    The MIME type of the response should be text/xml. The VOTable format is described here.

    The VOTable MUST comply with these conditions:

    There may be other FIELDS in the table, preferably each with description, datatype, unit, UCD and so on.

  3. The service will respond with a stub version of the VOTable in the case of error. This could happen if the three parameters (RA, DEC, SR) are not all present, or if they cannot be parsed to floating-point numbers, or if the numbers are bad (DEC=91.0 for example). The service may also make an error return if the Search Radius is larger than the MaxSR parameter of the Resource Profile (see below).

    In the case of error, the service MUST respond with a VOTable that contains a single parameter called Error, where the corresponding value should contain some explanation of the nature of the error.

    Other conditions may NOT be considered erroneous, for example if a query cone is in the Southern hemisphere and the catalog coverage is in the Northern hemisphere. This type of query is different from an error return; it should return a VOTable as described above, with metadata, but no data records. In particular, a zero value of Search Radius should not return an error condition. This is because an application may be more interested in the metadata than the data, and send a fixed query (for example RA=0&DEC=90&SR=0) simply to discover the fields delivered by the service.

  4. The service MUST be described with a Resource Profile that includes the following information. Several of these fields are hierarchical in nature, and may be expressed as strings separated by dots, with the root domain first.

    This Profile will be expressed as a colelction of keyword-value pairs, initially by inputting it into a centralized database, later by encoding it in XML and storing it on the same server(s) that1G have the corresponding catalog. Each of the string-based values in the Profile should be less than 2048 bytes.

    These are the keywords and descriptions required for publication:

  5. Publishing the service will consist of filling in a web-based form with the Profile information of section (4), TOGETHER with maintaining the web service that is described by that Profile.