IVOA Simple Spectral Access Extractor

Point at ANY IVOA Simple Spectral Access (SSA) service and list every astronomical spectrum over a patch of sky — one row per spectrum, with its access URL. Give a sky position (RA, Dec) and a search diameter, and this actor returns the metadata for every spectrum whose footprint overlaps that region, from any compliant Virtual Observatory spectral archive.

One actor speaks to the entire Virtual Observatory spectral estate. There is no per-archive scraper and no host list to maintain: ESO, GAVO / Heidelberg (FEROS, FlashHeros, TheoSSA …) and the national and observatory spectral archives all expose the identical IVOA Simple Spectral Access query.

This is the spectral sibling of the Simple Cone Search (positional) and Simple Image Access (image) runners — the third IVOA Data Access Layer protocol, for spectra.

What it does

The Simple Spectral Access protocol is one HTTP GET:

GET <service>?REQUEST=queryData&POS=<ra>,<dec>&SIZE=<deg>

and the reply is a VOTable listing every spectrum covering that region. This actor:

• runs that query against one or many SSA services at once;
• parses the VOTable — TABLEDATA, BINARY and BINARY2 serializations (some GAVO / DaCHS services default to BINARY2, which many naive parsers silently drop) — into flat rows;
• surfaces the spectrum access URL as a stable _accessUrl field on every row, no matter what the archive calls its own column (ESO calls it access_url, GAVO accref …), by locating it via the VOTable utype ssa:Access.Reference (ucd meta.ref.url);
• keeps the archive's own native columns (target, spectral-axis coverage, band, SNR, exposure, date …) alongside a lossless _raw copy.

This is a metadata runner. It returns one row per spectrum with the URL to fetch it — it does not download the spectral FITS / VOTable bulk. Point your own downloader at the _accessUrl values when you want the actual spectra.

An in-band QUERY_STATUS=ERROR in the VOTable is surfaced as a real error (never a fabricated empty result). A region that genuinely contains no spectra returns zero rows.

Input

Field	Required	Description
service	one of service/services	Base URL of a single SSA service. For a DaCHS / GAVO service use the full renderer path ending in /ssap.xml. The actor adds REQUEST/POS/SIZE itself.
services	one of service/services	List of SSA service URLs to query with the same region at once. Each row is tagged with its _service.
ra	yes	Right ascension of the region centre, decimal degrees J2000 (0–360).
dec	yes	Declination of the region centre, decimal degrees J2000 (−90 to +90).
size	yes	Search-cone diameter in degrees (a single positive number; 0.5 = a 30-arcmin-wide cone).
format	no	SSA FORMAT filter, e.g. application/fits, application/x-votable+xml, native, ALL, METADATA. Default: the service's own.
maxRecords	no	Global cap on rows emitted across all services (each row is one billable event).
timeoutSecs	no	Per-request read timeout (default 120).
userAgent	no	Override the request User-Agent.
bearer	no	Bearer token for an auth-gated deployment (never logged).
extraHeaders	no	Extra HTTP headers as a JSON object (values never logged).

Example

{
  "services": [
    "http://archive.eso.org/ssap",
    "https://dc.zah.uni-heidelberg.de/feros/q/ssa/ssap.xml"
  ],
  "ra": "83.8",
  "dec": "-5.4",
  "size": "0.5",
  "maxRecords": 1000
}

Output

One record per spectrum. Each record contains the archive's own columns plus these stable fields:

Field	Description
_accessUrl	The spectrum access URL (the FIELD with utype ssa:Access.Reference).
_format	The dataset MIME type (utype ssa:Access.Format), e.g. application/fits.
_service	The SSA service the row came from.
_mode	Always ssa.
_ra, _dec, _size	The region you queried.
_rowIndex	Global 0-based index across the run.
_raw	A lossless copy of the archive's native columns for this spectrum.

{
  "_accessUrl": "http://archive.eso.org/dataset/ADP...",
  "_format": "application/x-votable+xml",
  "_service": "http://archive.eso.org/ssap",
  "_mode": "ssa",
  "_ra": 83.8,
  "_dec": -5.4,
  "_size": "0.5",
  "_rowIndex": 12,
  "_raw": { "...": "archive's native columns" }
}

Pricing

Pay-per-event: you are charged per spectrum record returned. No subscription, no rental — you pay only for the rows you receive.

Notes

• SSA's SIZE is a single search-cone diameter in degrees (unlike SIA, which also allows a rectangle).
• Services enforce their own maximum result size and server-side timeouts; a very large region may be truncated by the server (reported as QUERY_STATUS=OVERFLOW).
• Not every service honours the FORMAT filter; leave it empty for the service default.