# IVOA Simple Image Access Extractor (`datamule/ivoa-sia-image-access-extractor`) Actor Point at ANY IVOA Simple Image Access (SIA) service — IRSA, SkyView, GAVO, HEASARC, ESO, CADC and thousands of observatory image archives — and list every astronomical image over a sky region: give RA, Dec and a size, get one row per image with its access URL. One actor for the Virtual Observatory. - **URL**: https://apify.com/datamule/ivoa-sia-image-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 image 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 Image Access Extractor **Point at ANY IVOA Simple Image Access (SIA) service and list every astronomical image over a patch of sky — one row per image, with its access URL.** Give a sky position (RA, Dec) and a region size, and this actor returns the metadata for every image whose footprint overlaps that region, from any compliant Virtual Observatory image archive. One actor speaks to the entire Virtual Observatory. There is no per-archive scraper and no host list to maintain: **IRSA / IPAC, NASA SkyView, GAVO, HEASARC, ESO, CADC, NOIRLab, STScI** and thousands of national and observatory image archives all expose the identical [IVOA Simple Image Access](https://www.ivoa.net/documents/SIA/) query. ### What it does The Simple Image Access protocol is one HTTP GET: ```` GET ?POS=,\&SIZE= ```` and the reply is a [VOTable](https://www.ivoa.net/documents/VOTable/) listing every image covering that region. This actor: - runs that query against one or many SIA services at once; - parses the VOTable — **TABLEDATA, BINARY and BINARY2** serializations (GAVO / DaCHS services default to BINARY2, which many naive parsers silently drop) — into flat rows; - surfaces the **image access URL** as a stable `_accessUrl` field on every row, no matter what the archive calls its own column (IRSA calls it `download`, SkyView `URL`, GAVO `accref` …), by locating it via the VOTable UCD `VOX:Image_AccessReference`; - keeps the archive's own native columns (WCS, bounding box, pixel scale, band, exposure, date …) alongside a lossless `_raw` copy. **This is a metadata runner.** It returns one row per image *with the URL to fetch it* — it does **not** download the FITS / JPEG pixels. Point your own downloader at the `_accessUrl` values when you want the actual images. 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 images returns zero rows. ### Input | Field | Required | Description | |-------|----------|-------------| | `service` | one of `service`/`services` | Base URL of a single SIA service. Keep any archive-selecting query parameter (e.g. SkyView's `?SURVEY=DSS`) — the actor adds `POS`/`SIZE` itself. | | `services` | one of `service`/`services` | List of SIA 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 | Region size in degrees. A single number is a square (`0.1` = 6 arcmin square); `width,height` gives a rectangle. | | `format` | no | SIA `FORMAT` filter, e.g. `image/fits`, `image/jpeg`, `GRAPHIC`, `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": [ "https://skyview.gsfc.nasa.gov/cgi-bin/vo/sia.pl?SURVEY=DSS", "https://irsa.ipac.caltech.edu/cgi-bin/2MASS/IM/nph-im_sia" ], "ra": "10.6847", "dec": "41.269", "size": "0.1", "maxRecords": 1000 } ```` ### Output One record per image. Each record contains the archive's own columns plus these stable fields: | Field | Description | |-------|-------------| | `_accessUrl` | The image access URL (the FIELD with UCD `VOX:Image_AccessReference`). | | `_format` | The image MIME type (UCD `VOX:Image_Format`), e.g. `image/fits`. | | `_service` | The SIA service the row came from. | | `_mode` | Always `sia`. | | `_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 image. | ```json { "_accessUrl": "https://irsa.ipac.caltech.edu/cgi-bin/2MASS/IM/nph-im_sia?...", "_format": "image/fits", "_service": "https://irsa.ipac.caltech.edu/cgi-bin/2MASS/IM/nph-im_sia", "_mode": "sia", "_ra": 10.6847, "_dec": 41.269, "_size": "0.1", "_rowIndex": 12, "_raw": { "...": "archive's native columns" } } ``` ### Pricing Pay-per-event: you are charged **per image record** returned. No subscription, no rental — you pay only for the rows you receive. ### Notes - The `size=0` convention (images covering the exact point) and rectangle sizes (`width,height`) follow the SIA spec. - 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 Image Access (SIA / SIAP) service. ONE actor speaks to all of them — IRSA / IPAC (https://irsa.ipac.caltech.edu/cgi-bin/2MASS/IM/nph-im\_sia), SkyView / NASA-GSFC (https://skyview.gsfc.nasa.gov/cgi-bin/vo/sia.pl?SURVEY=DSS), GAVO (https://dc.zah.uni-heidelberg.de//siap.xml), HEASARC, ESO, CADC, NOIRLab, STScI and thousands more. Keep any archive-selecting query parameter the service needs (e.g. SkyView's ?SURVEY=DSS) on the URL — the actor adds POS / SIZE itself. Required unless you use "Services" below. ## `services` (type: `array`): Optional: run the SAME region query (POS / SIZE) across multiple SIA services at once (several archives, or the same survey 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 Andromeda Galaxy (M31) is RA 10.6847. This is the SIA 'POS' longitude and is byte-identical across every SIA service. ## `dec` (type: `string`): The centre of the region of interest: declination in decimal degrees, J2000 (-90 to +90). Example: M31 is Dec 41.269. This is the SIA 'POS' latitude. ## `size` (type: `string`): The angular size of the search region in decimal degrees (the SIA 'SIZE' parameter). A single number is a square region (e.g. 0.1 = 6 arcmin on a side); two comma-separated numbers 'width,height' give a rectangle. Every image whose footprint overlaps this region is returned. SIZE=0 means the service returns images covering the exact point. Large sizes on rich archives can return many images (and cost more). ## `format` (type: `string`): Optional SIA 'FORMAT' filter for the kind of image the service should return: e.g. 'image/fits', 'image/jpeg', 'image/png', 'GRAPHIC' (any browser image), '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 image 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 image 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). Image 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 SIA 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": "https://skyview.gsfc.nasa.gov/cgi-bin/vo/sia.pl?SURVEY=DSS", "ra": "10.6847", "dec": "41.269", "size": "0.1", "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": "https://skyview.gsfc.nasa.gov/cgi-bin/vo/sia.pl?SURVEY=DSS", "ra": "10.6847", "dec": "41.269", "size": "0.1", "maxRecords": 1000 }; // Run the Actor and wait for it to finish const run = await client.actor("datamule/ivoa-sia-image-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": "https://skyview.gsfc.nasa.gov/cgi-bin/vo/sia.pl?SURVEY=DSS", "ra": "10.6847", "dec": "41.269", "size": "0.1", "maxRecords": 1000, } # Run the Actor and wait for it to finish run = client.actor("datamule/ivoa-sia-image-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": "https://skyview.gsfc.nasa.gov/cgi-bin/vo/sia.pl?SURVEY=DSS", "ra": "10.6847", "dec": "41.269", "size": "0.1", "maxRecords": 1000 }' | apify call datamule/ivoa-sia-image-access-extractor --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=datamule/ivoa-sia-image-access-extractor", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "IVOA Simple Image Access Extractor", "description": "Point at ANY IVOA Simple Image Access (SIA) service — IRSA, SkyView, GAVO, HEASARC, ESO, CADC and thousands of observatory image archives — and list every astronomical image over a sky region: give RA, Dec and a size, get one row per image with its access URL. One actor for the Virtual Observatory.", "version": "0.1", "x-build-id": "q8Si3ahww0lDDsc7d" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/datamule~ivoa-sia-image-access-extractor/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-datamule-ivoa-sia-image-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-sia-image-access-extractor/runs": { "post": { "operationId": "runs-sync-datamule-ivoa-sia-image-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-sia-image-access-extractor/run-sync": { "post": { "operationId": "run-sync-datamule-ivoa-sia-image-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": "SIA service endpoint URL", "type": "string", "description": "The base URL of ANY IVOA Simple Image Access (SIA / SIAP) service. ONE actor speaks to all of them — IRSA / IPAC (https://irsa.ipac.caltech.edu/cgi-bin/2MASS/IM/nph-im_sia), SkyView / NASA-GSFC (https://skyview.gsfc.nasa.gov/cgi-bin/vo/sia.pl?SURVEY=DSS), GAVO (https://dc.zah.uni-heidelberg.de//siap.xml), HEASARC, ESO, CADC, NOIRLab, STScI and thousands more. Keep any archive-selecting query parameter the service needs (e.g. SkyView's ?SURVEY=DSS) on the URL — the actor adds 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 SIA services at once (several archives, or the same survey 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 Andromeda Galaxy (M31) is RA 10.6847. This is the SIA 'POS' longitude and is byte-identical across every SIA 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: M31 is Dec 41.269. This is the SIA 'POS' latitude." }, "size": { "title": "SIZE — region size (degrees)", "type": "string", "description": "The angular size of the search region in decimal degrees (the SIA 'SIZE' parameter). A single number is a square region (e.g. 0.1 = 6 arcmin on a side); two comma-separated numbers 'width,height' give a rectangle. Every image whose footprint overlaps this region is returned. SIZE=0 means the service returns images covering the exact point. Large sizes on rich archives can return many images (and cost more)." }, "format": { "title": "Image format filter", "type": "string", "description": "Optional SIA 'FORMAT' filter for the kind of image the service should return: e.g. 'image/fits', 'image/jpeg', 'image/png', 'GRAPHIC' (any browser image), '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 image 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 image 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). Image 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 SIA 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 } } } } } } } } } } ```