# IVOA Simple Cone Search Extractor (`datamule/ivoa-cone-search-extractor`) Actor Point at ANY IVOA Simple Cone Search service (VizieR, HEASARC, GAVO, IRSA, NOIRLab and thousands of observatory catalogs) and pull every catalog source within a sky circle: give RA, Dec and a radius, get one row per object. One actor, the whole Virtual Observatory. - **URL**: https://apify.com/datamule/ivoa-cone-search-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 Cone Search Extractor Point at **any** IVOA Simple Cone Search (SCS) service and pull every catalogue source within a circle of sky — give a centre (RA, Dec) and a radius, get back one structured row per astronomical object. One actor speaks to the **entire Virtual Observatory**: VizieR / CDS, HEASARC / NASA-GSFC, GAVO, IRSA / IPAC, NOIRLab, ESA, CADC and thousands of national and observatory data centres all expose the identical positional query, so there is no per-catalogue scraper and no list of hosts to maintain. ### What it does Simple Cone Search is the simplest and most widely deployed IVOA data-access standard. The request is a single HTTP GET: ```` GET ?RA=\&DEC=\&SR=\ ```` and the reply is a **VOTable** listing every catalogue row whose position falls inside the cone. This actor issues that request, parses the VOTable, and pushes one dataset row per source. The output **columns are the catalogue's own columns** (position, magnitudes, identifiers, proper motions, whatever the catalogue publishes) — they are dynamic per service, plus a few `_`-prefixed provenance fields (`_endpoint`, `_ra`, `_dec`, `_sr`, `_rowIndex`). The VOTable parser accepts the **TABLEDATA**, **BINARY** and **BINARY2** serializations, so it works on every compliant service regardless of the wire format it defaults to (GAVO / DaCHS services default to BINARY). The SCS in-band error channel (`QUERY_STATUS=ERROR` returned with HTTP 200) is surfaced as a real error — the actor never fabricates rows. ### Input | Field | Description | |-------|-------------| | `endpoint` | Base URL of a cone-search service (keep any `?table=...` / catalogue selector). | | `endpoints` | Optional list — run the same cone across several services at once. | | `ra` | Cone centre right ascension, decimal degrees J2000 (0–360). | | `dec` | Cone centre declination, decimal degrees J2000 (−90…+90). | | `sr` | Search radius, decimal degrees (0.1 deg = 6 arcmin). | | `verb` | Optional verbosity 1/2/3 (column detail). | | `maxRecords` | Global cap on rows emitted (also sent as MAXREC). | | `timeoutSecs` | Read timeout, default 120. | | `bearer` / `extraHeaders` | Optional auth for gated deployments (never logged). | #### Example ```json { "endpoint": "https://irsa.ipac.caltech.edu/SCS?table=fp_psc", "ra": "10.6847", "dec": "41.269", "sr": "0.05" } ```` returns the 2MASS point sources around the Andromeda Galaxy (M31). Some more endpoints to try (each takes the identical RA / DEC / SR): - `https://heasarc.gsfc.nasa.gov/cgi-bin/vo/cone/coneGet.pl?table=zcat` - `https://vizier.cds.unistra.fr/viz-bin/conesearch/I/239/hip_main` - `https://dc.zah.uni-heidelberg.de/arihip/q/cone/scs.xml` ### Output Each row is one catalogue source. Example (2MASS around M31, abridged): ```json { "ra": 10.688429, "dec": 41.263153, "designation": "00424522+4115473", "j_m": 15.314, "h_m": 14.728, "k_m": 14.522, "_endpoint": "https://irsa.ipac.caltech.edu/SCS?table=fp_psc", "_ra": 10.6847, "_dec": 41.269, "_sr": 0.05, "_rowIndex": 0 } ``` ### Pricing Pay per result: you are charged per catalogue source row returned. A cone that contains no sources returns nothing and costs nothing. ### Notes - Radius matters: on a dense catalogue a large `SR` returns a very large table. Start small. - RA/Dec are **J2000 decimal degrees**. Convert sexagesimal (HH:MM:SS) first. - Services enforce their own maximum radius and row limits; a truncated result is logged as an overflow. # Actor input Schema ## `endpoint` (type: `string`): The base URL of ANY IVOA Simple Cone Search (SCS) service. ONE actor speaks to all of them — VizieR / CDS (https://vizier.cds.unistra.fr/viz-bin/conesearch/), HEASARC / NASA-GSFC (https://heasarc.gsfc.nasa.gov/cgi-bin/vo/cone/coneGet.pl?table=), GAVO (https://dc.zah.uni-heidelberg.de//scs.xml), IRSA / IPAC (https://irsa.ipac.caltech.edu/SCS?table=), NOIRLab, ESA, CADC and thousands more. Keep any catalogue-selecting query parameter the service needs (e.g. ?table=fp\_psc) on the URL — the actor adds RA / DEC / SR itself. Required unless you use "Endpoints" below. ## `endpoints` (type: `array`): Optional: run the SAME cone (RA / DEC / SR) across multiple cone-search services at once (several archives, or the same catalogue at mirror sites). Each output row is tagged with its \_endpoint. Use this OR the single "Endpoint" above (at least one is required). An endpoint 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 search cone: right ascension in decimal degrees, J2000 (0–360). Example: the Andromeda Galaxy (M31) is RA 10.6847. This is the SCS 'RA' parameter and is byte-identical across every cone-search service. ## `dec` (type: `string`): The centre of the search cone: declination in decimal degrees, J2000 (-90 to +90). Example: M31 is Dec 41.269. This is the SCS 'DEC' parameter. ## `sr` (type: `string`): The radius of the search cone in decimal degrees (the SCS 'SR' parameter). Every catalogue source within this angular distance of (RA, Dec) is returned. Keep it small for dense catalogues: 0.1 deg = 6 arcmin. Large radii on big catalogues can return huge tables (and cost more) — services also enforce their own maximum. ## `verb` (type: `string`): Optional SCS 'VERB' level controlling how many columns the service returns: 1 = minimal (id + position), 2 = the service's normal set, 3 = every available column. Leave empty to use the service's own default. Not all services honour it. ## `maxRecords` (type: `integer`): A GLOBAL cap on the number of rows emitted across ALL endpoints (each row is one billable event). Reached mid-endpoint, the run stops deterministically. It is also sent to the server as MAXREC (services that support it limit the result themselves). Leave empty to emit everything within the cone. ## `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). Positional queries over large catalogues can be slow; services also enforce their own server-side timeouts, so a very large cone may still be cut off by the server. ## `bearer` (type: `string`): Optional bearer token for an auth-gated cone-search 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 { "endpoint": "https://irsa.ipac.caltech.edu/SCS?table=fp_psc", "ra": "10.6847", "dec": "41.269", "sr": "0.05", "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 = { "endpoint": "https://irsa.ipac.caltech.edu/SCS?table=fp_psc", "ra": "10.6847", "dec": "41.269", "sr": "0.05", "maxRecords": 1000 }; // Run the Actor and wait for it to finish const run = await client.actor("datamule/ivoa-cone-search-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 = { "endpoint": "https://irsa.ipac.caltech.edu/SCS?table=fp_psc", "ra": "10.6847", "dec": "41.269", "sr": "0.05", "maxRecords": 1000, } # Run the Actor and wait for it to finish run = client.actor("datamule/ivoa-cone-search-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 '{ "endpoint": "https://irsa.ipac.caltech.edu/SCS?table=fp_psc", "ra": "10.6847", "dec": "41.269", "sr": "0.05", "maxRecords": 1000 }' | apify call datamule/ivoa-cone-search-extractor --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=datamule/ivoa-cone-search-extractor", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "IVOA Simple Cone Search Extractor", "description": "Point at ANY IVOA Simple Cone Search service (VizieR, HEASARC, GAVO, IRSA, NOIRLab and thousands of observatory catalogs) and pull every catalog source within a sky circle: give RA, Dec and a radius, get one row per object. One actor, the whole Virtual Observatory.", "version": "0.1", "x-build-id": "NZBex4rmVcXfE1v1u" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/datamule~ivoa-cone-search-extractor/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-datamule-ivoa-cone-search-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-cone-search-extractor/runs": { "post": { "operationId": "runs-sync-datamule-ivoa-cone-search-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-cone-search-extractor/run-sync": { "post": { "operationId": "run-sync-datamule-ivoa-cone-search-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", "sr" ], "properties": { "endpoint": { "title": "Cone Search endpoint URL", "type": "string", "description": "The base URL of ANY IVOA Simple Cone Search (SCS) service. ONE actor speaks to all of them — VizieR / CDS (https://vizier.cds.unistra.fr/viz-bin/conesearch/), HEASARC / NASA-GSFC (https://heasarc.gsfc.nasa.gov/cgi-bin/vo/cone/coneGet.pl?table=), GAVO (https://dc.zah.uni-heidelberg.de//scs.xml), IRSA / IPAC (https://irsa.ipac.caltech.edu/SCS?table=), NOIRLab, ESA, CADC and thousands more. Keep any catalogue-selecting query parameter the service needs (e.g. ?table=fp_psc) on the URL — the actor adds RA / DEC / SR itself. Required unless you use \"Endpoints\" below." }, "endpoints": { "title": "Endpoints (search several at once)", "type": "array", "description": "Optional: run the SAME cone (RA / DEC / SR) across multiple cone-search services at once (several archives, or the same catalogue at mirror sites). Each output row is tagged with its _endpoint. Use this OR the single \"Endpoint\" above (at least one is required). An endpoint 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 search cone: right ascension in decimal degrees, J2000 (0–360). Example: the Andromeda Galaxy (M31) is RA 10.6847. This is the SCS 'RA' parameter and is byte-identical across every cone-search service." }, "dec": { "title": "Dec — declination (degrees)", "type": "string", "description": "The centre of the search cone: declination in decimal degrees, J2000 (-90 to +90). Example: M31 is Dec 41.269. This is the SCS 'DEC' parameter." }, "sr": { "title": "SR — search radius (degrees)", "type": "string", "description": "The radius of the search cone in decimal degrees (the SCS 'SR' parameter). Every catalogue source within this angular distance of (RA, Dec) is returned. Keep it small for dense catalogues: 0.1 deg = 6 arcmin. Large radii on big catalogues can return huge tables (and cost more) — services also enforce their own maximum." }, "verb": { "title": "Verbosity (column detail)", "enum": [ "1", "2", "3" ], "type": "string", "description": "Optional SCS 'VERB' level controlling how many columns the service returns: 1 = minimal (id + position), 2 = the service's normal set, 3 = every available column. Leave empty to use the service's own default. Not all services honour it." }, "maxRecords": { "title": "Max records (global cap)", "minimum": 1, "type": "integer", "description": "A GLOBAL cap on the number of rows emitted across ALL endpoints (each row is one billable event). Reached mid-endpoint, the run stops deterministically. It is also sent to the server as MAXREC (services that support it limit the result themselves). Leave empty to emit everything within the cone." }, "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). Positional queries over large catalogues can be slow; services also enforce their own server-side timeouts, so a very large cone may still be cut off by the server." }, "bearer": { "title": "Bearer token", "type": "string", "description": "Optional bearer token for an auth-gated cone-search 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 } } } } } } } } } } ```