Astronomical Server URL

(Version 1.0, 19-Sept-1996)

http://vizier.cds.unistra.fr/doc/asu.html

M. Albrecht (ESO / Garching, Germany)
M. Barylak (ESA / IUE, Villafranca, Spain)
D. Durand (CADC / DAO, Canada)
P. Fernique (CDS / Strasbourg, France)
A. Micol (ST-ECF / Garching, Germany)
F. Ochsenbein (CDS / Strasbourg, France)
F. Pasian (OAT / Trieste, Italy)
B. Pirenne (ST-ECF / Garching, Germany)
D. Ponz (ESA / IUE, Villafranca, Spain)
M. Wenger (CDS / Strasbourg, France)


A few extensions are used at CDS, mainly for managing lists, and for meta queries; a summary of ASU conventions at CDS is also available.


This document is a proposal, for discussion, on a possible syntax for information exchange among remote astronomical services, like catalogues and archives, with the HTTP protocol, thus allowing embedded hyperlinks of the general form

http://host_name/cgi_path/source?field1=value&field2=value...

or

http://host_name/cgi_path?-source=source&field1=value&field2=value...

where host_name represents the server's Internet node, cgi_path a server program normally started by the http daemon, source a catalogue or data source. The arguments can be used, either to specify constraints, or to specify options (options are preceded by a - (dash), to differentiate options from actual field or parameter names).

Please let us know your comments to cds-question@unistra.fr

Specification of data source

The source naming can be specified either in the PATH_INFO part of the URL, or as the value of the -source= argument (the first form above is maintained for historical reasons). In the case of astronomical catalogues, it is recommended to use the CDS (e.g. V/50, or J/A+AS/111/123) or ADC (e.g. 5050) nomenclature, or a well-known abbreviation (e.g. BSC), to define a catalogue.

In the case when cgi_path supports several catalogues, the -source= syntax is required, and the individual catalogues are separated by a comma. An additional -corr= option can be used to specify how the designated catalogues are combined to generate the appropriate answer; the default, without the -corr= option, is to apply successively the cgi_path program to each catalogue of the list (union query)


Specification of parameters

The meaning of the parameters (the field1=value parts of the URL) is server dependent (defined actually in the cgi_path server). In the case where value represents a constraint, the recommended syntax for numeric and string qualification is presented in the annex.

For servers which accept standard SQL queries, the way of supplying the query string is via a -sql option, e.g.

http://host_name/cgi_path?-sql=select%20distinct%20name%20from%20table


Special case: Query by position

The aim is to get result based upon the vicinity to a target position on the sky; this target position can be specified, either as a pair of actual coordinates, or by the name of the central object which is converted into an actual position by means of a name resolver (see the Specification of the resolver below).

There are two possible equivalent syntaxes ...

[-c=]{RA{+|-}Dec|object_name}[,eq=equinox][,ep=epoch][,rm=[min/]max]|[,bm=x[/y]]

or

{-c.ra=RA&-c.dec=Dec|-c.obj=object_name} [&-c.eq=equinox][&-c.ep=epoch][{{&-c.rm=[min/]max | &-c.bm=x[/y]}]

(the -c.rm can itself be decomposed into -c.rm.min and -c.rm.max; the same structure decomposition can be applied for the -c.bm parameter)

where:

units: the specification of the size of the target is expressed in degrees with rd= or bd= parameters, and in arc seconds with rs= or bs= parameters.

Example: One specific example of this query is the query for resolving a name from SIMBAD or NED. In that case the client sends: ...?-c.obj=M31 and receives the J2000 coordinate for that object.


Specification of the Ouput


The mime types

The result returned by the server to any client request starts with the standard HTTP header:

Content-type: content_type (mandatory line)
Content-length: length_in_bytes (optional line)

followed by an empty line. The format in which the result is coded, the content_type, is one of the possibilities detailed in the first column of the next tables (for images, tables, and starbase). This format can be selected by the -mime= option. The possibilities are:

-mime=[html|fits|tsv|text|gif|jpeg|starbase|ps|pdf...]

(ex: tsv = tab-separated value) The relation between the -mime= argument and the content_type is:

The default output mime type is chosen by the Server, either as one of the acceptable format defined in the client's HTTP_ACCEPT set, or ultimately server dependent.


The output list

The output definitions specifies which fields are to be returned (in the case of table queries) and some other general parameters related to the choices among the possible output choices. The possible choices are:
-out=field1[,field2]...
Choice of displayed fields, ordered according to the list (table context)
-out.all
All fields are displayed on return (table context)
-out.basic
Basic (restricted set of fields) results; this exact definition is server dependent.
-out.exists
Returns just information about the number of existing answers. The answer may be the number of matching items (a positive or null number returned), or a existence flag (value -1)
-out.max=number
The maximal number of returned matching items. The default value depends on the server, but an explcit message signals a truncated result due to this limit. A value of unlimited for number could be used to remove any limitation (to be used with caution !!)
-out.next=expression
Specifies the first item the server has to return; the syntax of expression is server dependent. This parameter is of typical usage for getting the next set of matching items, once previous matching items have been returned.
-out.object
Asks to return only the matching object identification, and the corresponding sky coordinates if applicable. For astronomical objects, the returned result consists of three columns: NAME (the name of the matching object), RA (right ascension), and Dec, (declination) of the matching objects. If not otherwise specified (e.g. in FITS headers, or in the -oc option detailed below), the equinox and epoch of the positions are J2000.

The coordinate output format

-oc={hms|dms|deg}[,eq=equinox][,ep=epoch]

Specifies the format of the coordinates returned by the server. The conventions are similar to the -c= parameter for specifying the Query by position; the same hierarchical option expansion is possible, e.g. -oc.eq= specifies the equinox of the output coordinates.

The default coordinate format is server dependent.


The sort fields

-sort=field[,field]...

List of field names on which the output is (increasingly) sorted. The default result ordering is server dependent.


Specification of the resolver

-resolv={ned|simbad}

Specifies which name resolver (conversion of object name into a position on the sky) to be used by the server. If not present, it is up to the service provider to select.


Specification of meta queries

Meta-queries, like queries to get help, requests for the list of the available services, tables of contents, and other related data, will be addressed in a later version; the -meta word is reserved for this future usage.

For its own requirements, CDS has a small set of meta extensions currently in use.


Examples

http://cadcwww/cadcbin/search/cfht?-c=12:12:12-14:23,eq=B1950,rm=3.&-mime=tsv

Search here is done on cfht, around RA=12:12:12 and Dec=-14:23, equinox is B1950 and the searching radius is 3 arc minutes. Output has to be formatted as an ASCII table with tab separated values.

Other examples (being tested):

A complex example (from ESO): http://archive.eso.org/general-server/bin/general-server-V0.5?-source=hstscience,eso-ntt&-c=10:45-59:41&-c.rm=3&-c.eq=J2000&-oc.eq=J2000&-oc.ra=hms&-oc.dec=dms&-mime=text/html&-out.max=6


Please let us know your comments to asu@vizier.cds.unistra.fr


Annex: Qualification Syntax

The following details the syntax for constraint qualification, already used by major astronomical querying engines, (WDB/STARCAT/VizieR systems). The qualification is made of comparison operators, logical operators, and values. The ways of specifying these different components differ slightly for numeric, character, or other types of data. Don'tforget that the special symbols have to be converted when embedded in URL syntax (e.g. %25 for the % sign, %3C for <, etc.)

Numeric fields (INT, FLOAT, RA, Dec, DATE, TIME)

OperatorMeaningExample
=Strict equality (default)=10
!=Inequality!=10
>=Greater or equal>=10
>Strictly greater>10
<=Smaller or equal<=10
<Strictly smaller<10
..Range of numbers5..10
&AND (logical operator)1..5 & 7..9
|OR (logical operator)1..5 | 7..9
,List of values0,1,2
!NOT (logical operator)! 1..5

Writing Values (INT, FLOAT, RA, Dec, DATE, TIME)

TypeMeaningExample
nullUnspecified (blank)value (<0)|null
now Current date and time (DATE only) < now
RA Sexagesimal hours, minutes, seconds of time 23 56 .. 00 04
Right ascension in decimal degrees 359 .. 001
Dec Sexagesimal degrees, minutes, seconds of arc +41 45 .. +42 30
Declination in decimal degrees +41.75 .. +42.50
DATE/TIME UT Date and time, alphabetic month >= 1-Jan-1996
UT Date and Time, numeric month >= 1996.01.01 00:00:00
Julian Date >=JD2450083.5

Character fields (CHAR, TEXT)

OperatorMeaningExample
~Caseless pattern matching (default) ~ngc*3532*
=Pattern matching=NGC*3532*
=~Caseless equality=~eso
==Strict equality==ESO
!~NOT caseless pattern matching !~[obafgkm]*
!NOT pattern matching ![OBAFGKM]*
!=Strict inequality!=ESO
>=Alphabetically greater or equal>=A
>Alphabetically strictly greater>M 51
<=Alphabetically smaller or equal<=B*
<Alphabetically strictly smaller< NGC

Pattern matching symbols

SymbolMeaningExample
[...] One of the characters defined within the brackets =[OBA]*
The - (dash or minus) indicates a range of characters =[A-Za-z]*
[^...] Any single character NOT contained within the brackets =[^OBAFGMN]*
*Replaces 0 to n characters[OB]*
?Replaces 1 characterA?C*


A few programs which can be useful in the ASU context are also available


Please let us know your comments to asu@vizier.cds.unistra.fr