# IVOA Simple Spectral Access Extractor (`datamule/ivoa-ssa-spectral-access-extractor`) Actor Point at ANY IVOA Simple Spectral Access (SSA) service — ESO, GAVO and observatory spectral archives — and list every astronomical spectrum over a sky region: give RA, Dec and a size, get one row per spectrum with its access URL. One actor for the Virtual Observatory. - **URL**: https://apify.com/datamule/ivoa-ssa-spectral-access-extractor.md - **Developed by:** [Datamule](https://apify.com/datamule) (community) - **Categories:** Developer tools, Business - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $0.35 / 1,000 records This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## 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](https://www.ivoa.net/documents/SSA/) 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 ?REQUEST=queryData\&POS=,\&SIZE= ```` and the reply is a [VOTable](https://www.ivoa.net/documents/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 ```json { "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. | ```json { "_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. # Actor input Schema ## `service` (type: `string`): The base URL of ANY IVOA Simple Spectral Access (SSA / SSAP) service. ONE actor speaks to all of them — ESO (http://archive.eso.org/ssap), GAVO / Heidelberg (https://dc.zah.uni-heidelberg.de/feros/q/ssa/ssap.xml, .../theossa/q/ssa/ssap.xml), and the spectral archives across the Virtual Observatory. For a DaCHS / GAVO service, use the full renderer path ending in '/ssap.xml'. Keep any archive-selecting query parameter the service needs on the URL — the actor adds REQUEST / POS / SIZE itself. Required unless you use "Services" below. ## `services` (type: `array`): Optional: run the SAME region query (POS / SIZE) across multiple SSA services at once (several archives, or the same collection at mirror sites). Each output row is tagged with its \_service. Use this OR the single "Service" above (at least one is required). A service that is unreachable, auth-gated, or returns a non-VOTable body is skipped with a warning and the batch continues. ## `ra` (type: `string`): The centre of the region of interest: right ascension in decimal degrees, J2000 (0–360). Example: the Orion Nebula (M42) is RA 83.82. This is the SSA 'POS' longitude and is byte-identical across every SSA service. ## `dec` (type: `string`): The centre of the region of interest: declination in decimal degrees, J2000 (-90 to +90). Example: M42 is Dec -5.39. This is the SSA 'POS' latitude. ## `size` (type: `string`): The angular diameter of the search cone in decimal degrees (the SSA 'SIZE' parameter). Every spectrum whose footprint overlaps this cone, centred on (RA, Dec), is returned. A single positive number (e.g. 0.5 = a 30-arcmin-wide cone). Large sizes on rich archives can return many spectra (and cost more). ## `format` (type: `string`): Optional SSA 'FORMAT' filter for the kind of dataset the service should return: e.g. 'application/fits', 'application/x-votable+xml', 'native', 'ALL' (every format), or 'METADATA' (describe the service's columns without querying). Leave empty to use the service's own default. Not all services honour every value. ## `maxRecords` (type: `integer`): A GLOBAL cap on the number of spectrum rows emitted across ALL services (each row is one billable event). Reached mid-service, the run stops deterministically. It is also sent to the server as MAXREC where supported. Leave empty to emit every spectrum in the region. ## `userAgent` (type: `string`): Optional override for the request User-Agent. A descriptive User-Agent is sent by default — some data centres throttle or reject a blank / generic UA. Only override if a specific service asks you to identify differently. ## `timeoutSecs` (type: `integer`): How long to wait for the service to answer (default 120). Spectral queries over large archives can be slow; services also enforce their own server-side timeouts, so a very large region may still be cut off by the server. ## `bearer` (type: `string`): Optional bearer token for an auth-gated SSA deployment (sent as Authorization: Bearer \*\*\*). NOT required for public services. Never logged. ## `extraHeaders` (type: `object`): Optional extra HTTP headers as a JSON object, e.g. {"X-Api-Key": "..."} for a gateway-fronted service. Not required for public services. Header values are never logged. ## Actor input object example ```json { "service": "http://archive.eso.org/ssap", "ra": "83.8", "dec": "-5.4", "size": "0.5", "maxRecords": 1000 } ``` # Actor output Schema ## `results` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "service": "http://archive.eso.org/ssap", "ra": "83.8", "dec": "-5.4", "size": "0.5", "maxRecords": 1000 }; // Run the Actor and wait for it to finish const run = await client.actor("datamule/ivoa-ssa-spectral-access-extractor").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "service": "http://archive.eso.org/ssap", "ra": "83.8", "dec": "-5.4", "size": "0.5", "maxRecords": 1000, } # Run the Actor and wait for it to finish run = client.actor("datamule/ivoa-ssa-spectral-access-extractor").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "service": "http://archive.eso.org/ssap", "ra": "83.8", "dec": "-5.4", "size": "0.5", "maxRecords": 1000 }' | apify call datamule/ivoa-ssa-spectral-access-extractor --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=datamule/ivoa-ssa-spectral-access-extractor", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "IVOA Simple Spectral Access Extractor", "description": "Point at ANY IVOA Simple Spectral Access (SSA) service — ESO, GAVO and observatory spectral archives — and list every astronomical spectrum over a sky region: give RA, Dec and a size, get one row per spectrum with its access URL. One actor for the Virtual Observatory.", "version": "0.1", "x-build-id": "iILSJed8OuVrae8Cd" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/datamule~ivoa-ssa-spectral-access-extractor/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-datamule-ivoa-ssa-spectral-access-extractor", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/datamule~ivoa-ssa-spectral-access-extractor/runs": { "post": { "operationId": "runs-sync-datamule-ivoa-ssa-spectral-access-extractor", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/datamule~ivoa-ssa-spectral-access-extractor/run-sync": { "post": { "operationId": "run-sync-datamule-ivoa-ssa-spectral-access-extractor", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "ra", "dec", "size" ], "properties": { "service": { "title": "SSA service endpoint URL", "type": "string", "description": "The base URL of ANY IVOA Simple Spectral Access (SSA / SSAP) service. ONE actor speaks to all of them — ESO (http://archive.eso.org/ssap), GAVO / Heidelberg (https://dc.zah.uni-heidelberg.de/feros/q/ssa/ssap.xml, .../theossa/q/ssa/ssap.xml), and the spectral archives across the Virtual Observatory. For a DaCHS / GAVO service, use the full renderer path ending in '/ssap.xml'. Keep any archive-selecting query parameter the service needs on the URL — the actor adds REQUEST / POS / SIZE itself. Required unless you use \"Services\" below." }, "services": { "title": "Services (search several archives at once)", "type": "array", "description": "Optional: run the SAME region query (POS / SIZE) across multiple SSA services at once (several archives, or the same collection at mirror sites). Each output row is tagged with its _service. Use this OR the single \"Service\" above (at least one is required). A service that is unreachable, auth-gated, or returns a non-VOTable body is skipped with a warning and the batch continues.", "items": { "type": "string" } }, "ra": { "title": "RA — right ascension (degrees)", "type": "string", "description": "The centre of the region of interest: right ascension in decimal degrees, J2000 (0–360). Example: the Orion Nebula (M42) is RA 83.82. This is the SSA 'POS' longitude and is byte-identical across every SSA service." }, "dec": { "title": "Dec — declination (degrees)", "type": "string", "description": "The centre of the region of interest: declination in decimal degrees, J2000 (-90 to +90). Example: M42 is Dec -5.39. This is the SSA 'POS' latitude." }, "size": { "title": "SIZE — search diameter (degrees)", "type": "string", "description": "The angular diameter of the search cone in decimal degrees (the SSA 'SIZE' parameter). Every spectrum whose footprint overlaps this cone, centred on (RA, Dec), is returned. A single positive number (e.g. 0.5 = a 30-arcmin-wide cone). Large sizes on rich archives can return many spectra (and cost more)." }, "format": { "title": "Spectrum format filter", "type": "string", "description": "Optional SSA 'FORMAT' filter for the kind of dataset the service should return: e.g. 'application/fits', 'application/x-votable+xml', 'native', 'ALL' (every format), or 'METADATA' (describe the service's columns without querying). Leave empty to use the service's own default. Not all services honour every value." }, "maxRecords": { "title": "Max records (global cap)", "minimum": 1, "type": "integer", "description": "A GLOBAL cap on the number of spectrum rows emitted across ALL services (each row is one billable event). Reached mid-service, the run stops deterministically. It is also sent to the server as MAXREC where supported. Leave empty to emit every spectrum in the region." }, "userAgent": { "title": "User-Agent override", "type": "string", "description": "Optional override for the request User-Agent. A descriptive User-Agent is sent by default — some data centres throttle or reject a blank / generic UA. Only override if a specific service asks you to identify differently." }, "timeoutSecs": { "title": "Read timeout (seconds)", "minimum": 1, "maximum": 900, "type": "integer", "description": "How long to wait for the service to answer (default 120). Spectral queries over large archives can be slow; services also enforce their own server-side timeouts, so a very large region may still be cut off by the server." }, "bearer": { "title": "Bearer token", "type": "string", "description": "Optional bearer token for an auth-gated SSA deployment (sent as Authorization: Bearer ***). NOT required for public services. Never logged." }, "extraHeaders": { "title": "Extra request headers", "type": "object", "description": "Optional extra HTTP headers as a JSON object, e.g. {\"X-Api-Key\": \"...\"} for a gateway-fronted service. Not required for public services. Header values are never logged." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```