SIMBAD: How to query SIMBAD by URLs ?


Simbad Help   ⋅   Top   ⋅   Previous   ⋅   Next

© Université de Strasbourg/CNRS

    • Contact

The query pages of Simbad can be used directly in any application, or using standard tools like curl or wget. The result can be provided in HTML, ASCII or VOTable.

This documentation will describe how to write the URLs for querying Simbad and detail the required parameters. Be careful, some characters are not allowed in URLs. http://www.w3schools.com/tags/ref_urlencode.asp

1  The available URLs

The following urls can be used to query Simbad (each one is shown as a valid example):

The following URLs do specialized queries and require parameters to specify the data to output.

2  Script queries

They are processed by the url

http://simbad.u-strasbg.fr/simbad/sim-script?script=...}

The script parameter consist of script commands separated by a newline char. All the script commands described in this help page can be used in an URL.

Main commands to consider for a URL query are:

3  Specialized queries

URLs for specialized queries are:

Each of them have their own set of parameters, but share also a set of output definition parameters which are described later.
All the parameters are case sensitive.

4  Identifier queries

Url example : http://simbad.u-strasbg.fr/simbad/sim-id?Ident=m31

The parameters are:

name  values  description
Ident=  Identifier, wildcard expression
or catalogue name Identifier or acronym to query NbIdent= [1|around|wildcard|cat]
1  query one identifier (default)
around  query around the identifier 
                (see also the Radius and Radius.unit parameters)
wildcard The identifier (parameter 'Ident=') is a wildcard expression cat The parameter 'Ident=') is a catalogue name and the whole catalogue will be queried

Radius= & a decimal radius value & Radius for 'around' query. See also Radius.unit parameter
Radius.unit= & [arcsec|arcmin|deg] &
arcsec  arc seconds
arcmin  arc minutes (default) 
deg  degrees

See below for the output definition parameters

5  Coordinate queries

Url example : http://simbad.u-strasbg.fr/simbad/sim-coo?Coord=10h30+%2B12d20&Radius=15&Radius.unit=arcmin

The parameters are:

name  values  description
Coord=  right ascension declination
longitude latitude Coordinates which van be written in several formats: Radius= a decimal radius value Radius for 'around' query. See also Radius.unit parameter Radius.unit= [arcsec|arcmin|deg]
arcsec  arc seconds
arcmin  arc minutes (default) 
deg  degrees
CooFrame= [ICRS|FK5|FK4|GAL|SGAL|ECL Coordinate frame:
ICRS  ICRS frame. Objects are stored in this frame in SIMBAD
FK5  FK5 frame.
FK4  FK4 frame.
GAL  Galactic frame.
SGAL  Super Galactic frame.
ECL  Ecliptic frame.
CooEpoch= Epoch of the submitted coordinates
(default: 2000) CooEqui= Equinox of the submitted coordinates
(default: 2000)

See below for the output definition parameters

6  Criteria queries

Url example : http://simbad.u-strasbg.fr/simbad/sim-sam?CriteriaField=dec>86 & ra>22 & Bmag<8 & cat='HIP'&OutputMode=LIST&maxObject=100

The parameters are:

name  values  description
Criteria=  a criteria expression 
                  All the possible criteria names and the corresponding
	           operators are described in the 
                   query by criteria page.
OuputMode=  [COUNT|LIST|REF]
                   Defines the expected output:
		    
		    COUNT  Number of objects that would have been returned by the query (default)
		    LIST   Return the list of objects selected by the query
		    REF    Return all the references that belong to the list
		                   of objects that would habe been returned by the query
		    
maxObject= Maximum number of objects
to return (abs. maximum: currently 50000)

See below for the output definition parameters

7  Reference queries

Reference queries can be of two types, distinguished by the submit parameter:

7.1  Reference query by bibcode

Url example : http://simbad.u-strasbg.fr/simbad/sim-ref?submit=submit+bibcode&bibcode=2003AN.324.61M

Such a query can be performed either by giving a complete bibcode (parameter bibcode), or by giving elements of a bibcode. Any part(s) among the year (byear), the journal (bjournal), the volume(bvolume) and/or the page (bpage) can be defined to retrieve the corresponding list of references.

name  values  description
submit=   submit bibcode  written like this
bibcode=  bibcode
                 A bibcode. It can be written shorter than the normalized bibcode
	          (19 chars) as long as a dot ('.') separates each item after the journal
	          abbreviation.
simbo=    on  display the list of objects in the reference. This parameter
                      can be used only with a complete bibcode
byear=    year  a bibcode year (4 digits)
bjournal= journal abbreviation  a journal abbreviation
bvolume=  volume  a volume number
bpage=    page number  a page number

7.2  Reference query by criteria

Url example : http://simbad.u-strasbg.fr/simbad/sim-ref?submit=submit+criteria&fromyear=2005&toyear=2006&words=xmm

These parameters allow to find a list of references in SIMBAD based on criteria on journals (journal), year range (fromyear and toyear), author names (authors) and/or words in the title (words).

name  values  description
submit=   submit criteria  written like this
journal=  list of journal abbreviations  the list 
fromyear=  lower year limit  first year to search for references
toyear=    upper year limit  last year (inclusive) to search for references
authors= author names  list of authors separated by operators '|' (or) or '&' (and)
words=  title words  list of words in the title separated 
                by operators '|' (or) or '&' (and)

8  Output definition parameters

SIMBAD has two kind of outputs:

Output parameters can be global (usable for all kind of output) or relevant of only one particular kind.

The remaining of this section will describe all output parameters grouped by data type. Default value, if any, is written in boldface.

8.1  general parameters

These output definition parameters are common to all kind of outputs:

name  values  description
output.format=  HTML|VOTable|ASCII  
Defines the output format (HTML page, only ASCII or VOTable)

output.max=  max # of objects  Maximum number of objects to display. 
                          This number is in any case limited currently to 50,000

8.2  Object type

The object type is always displayed with an astronomical object.

name  values  description
list.otypesel=  on|off  display or not the main object type in a list
otypedisp=  S|V|3|N  display format for the object type:
S = standard (6 chars max), V = verbose description, 3 = short abbreiviation on 3 chars max (default), N = numeric display (NN.NN.NN.NN)

8.3  Coordinates

Four coordinates can be displayed for an astronomical object.

name  values  description
obj.cooN=  on|off  display for an object the N-th coordinate (N=1..4). See below how to specify the frame
4 coordinates are displayed for an astronomical object list.cooN= on|off display in a list the N-th coordinate (N=1..4). See below how to specify the frame
Only list.coo1 is on by default frameN= ICRS|FK5|FK4|GAL|SGAL|ECL define the frame for the N-th (N=1..4) coordinates epochN= [B|J]year define the epoch for the N-th (N=1..4) coordinates equiN= year define the equinox for the N-th (N=1..4) coordinates coodispN= [s|d][2] define the coordinates format for the N-th (N=1..4) coordinates:
s = sexagesimal, d = decimal, 2 = space insertion between ra and dec

8.4  Proper motions

name  values  description
obj.pmsel=  on|off  display or not the proper motions in an astronomical object
list.pmsel=  on|off  display or not the proper motions in a list

8.5  Parallaxes

name  values  description
obj.plxsel=  on|off  display or not the parallaxes in an astronomical object
list.plxsel=  on|off  display or not the parallaxes in a list

8.6  Radial velocities

name  values  description
obj.rvsel=  on|off  display or not the radial velocities in an object
list.rvsel=  on|off  display or not the radial velocities in a list
rvDisplay=  R|Z|V  define which value will be displayed:
R = the radial velocity or the redshift, as stored in the database, Z = force a redshift display, V = force a radial velocity display

8.7  Spectral type

name  values  description
obj.spsel=  on|off  display or not the spectral type in an astronomical object
list.spsel=  on|off  display or not the spectral type in a list

8.8  Morphological type

name  values  description
obj.mtsel=  on|off  display or not the morphological type in an astronomical object
list.mtsel=  on|off  display or not the morphological type in a list

8.9  Angular size

name  values  description
obj.sizesel=  on|off  display or not the size of an astronomical object (extended objects)
list.sizesel=  on|off  display or not the size in a list

8.10  Fluxes

name  values  description
obj.fluxsel=  on|off  display or not the fluxes of an astronomical object. For an object, all the available fluxes
	are always displayed
list.fluxsel=  on|off  display or not the fluxes in a list. 
	They can be specified by the parameters filtername=on. 
	
filtername=  on|off  display the flux value of the given filters set to 'on'. Please, check the list of available filter names in the corresponding combobox on the Output options web page. 

8.11  Identifiers

In an astronomical object display, the identifiers are always displayed.

name  values  description
list.idsel=  on|off  display or not an identifier in a list. Only one identifier will be displayed in a list. It can be defined
	with the other parameters in this section.
list.idopt=  FIRST|CATLIST  identifier display option: FIRST = first identifier, CATLIST = display the first identifier present
	in the list of acronyms specified in the list.idcat parameter
list.idcat=  list of catalog names  list of comma separataed acronyms. The displayed identifier is the first one found in this list.
	 if none is found, the first identifier will be displayed

8.12  Bibliography

name  values  description
obj.bibsel=  on|off  display or not the bibliographic data of an astronomical object, according to the other parameters
list.bibsel=  on|off  display or not the number of bibliographic references in a list. The number is computed according
	to some other parameters
bibyear1=  year  select references from this given year up (inclusive lower limit)
bibyear2=  year  select references up to the given year (inclusive upper limit)
bibjnls=  list of journals  select only the journals belonging to the comma separated list
	of journal abbreviations
bibdisplay=  display type  For astronomical object full display, choose the kind of reference display.
	All these display take in account the restrictions imposed by bibyearN and bibjnls.
	
	bibnum  number of references (imposed in a list)
	bibnumauthors  number of references grouped by first author
	bibnumyears  number of references grouped by year
	bibnumjournals  number of references grouped by journal
	bibcode  display only the bibcodes
	refsum  display the reference summary (authors, title, ...)
	
bibcom= on|off display or not the comments when the reference summary is displayed bibtabular= on|off if on, the main reference data are displayed in a tabular format

8.13  Measurements

In a list, only the number of measurements for a specified list of catalogs can be displayed. The display in an astronomical object depends on the mesdisp parameter.

name  values  description
obj.messel=  on|off  display or not the measurements of an astronomical object. The display is done according to the 
	 mesdisplay parameter
list.messel=  on|off  display or not the number of measurements in a list. The catalogs for which the number of measurements
	 is displayed are defined in the list.mescat parameter.
mesdisplay=  N|A|M|F  display option: N = number of measurements, A = all measurements, F =
	 first measurement, M = mean value (when it exists)
list.mescat=  list of meas. catalogs  list of measurements catalogs to display.
	in a list, only the number of measurements for these catalogs will be displayed

8.14  Notes

In a list, only the number of notes can be displayed.

name  values  description
obj.notesel=  on|off  display or not the notes of an astronomical object
list.notesel=  on|off  display or not the number of notes in a list
notedisplay=  N|S|A  display option: N = number of notes (imposed in a list),
	 S = only essential (short) notes (default for objects),
	 A = all notes


Simbad Help   ⋅   Top   ⋅   Previous   ⋅   Next

© Université de Strasbourg/CNRS

    • Contact