# ESA Gaia DR3 Star Catalog Scraper (`parseforge/gaia-star-catalog-scraper`) Actor Tap the ESA Gaia DR3 archive for real stellar measurements by ADQL query or cone search. Each star returns its source ID, position, parallax, proper motion, G band magnitude, radial velocity, and effective temperature. Useful for astronomy research, target lists, and star maps. - **URL**: https://apify.com/parseforge/gaia-star-catalog-scraper.md - **Developed by:** [ParseForge](https://apify.com/parseforge) (community) - **Categories:** Developer tools, Other - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $3.00 / 1,000 results 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 a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.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/platform/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 ![ParseForge Banner](https://github.com/ParseForge/apify-assets/blob/ad35ccc13ddd068b9d6cba33f323962e39aed5b2/banner.jpg?raw=true) ## ๐ŸŒŒ ESA Gaia DR3 Star Catalog Scraper > ๐Ÿš€ **Pull real stellar measurements from the ESA Gaia DR3 archive in one run.** Query by ADQL or a simple cone search and get back source IDs, sky positions, parallax, proper motion, photometry, radial velocity, and effective temperature for every star. > ๐Ÿ•’ **Last updated:** 2026-06-05 ยท **๐Ÿ“Š 11 fields** per record ยท billions of sources in Gaia DR3 ยท full-sky coverage The ESA Gaia mission has measured the positions, distances, and motions of nearly two billion stars. The Gaia Data Release 3 (DR3) catalog is the richest map of the Milky Way ever assembled. This Actor talks to the official Gaia Archive TAP service and turns that catalog into clean, structured records you can drop straight into a notebook, a database, or a dashboard. You can run an exact ADQL query against the `gaiadr3.gaia_source` table, or skip the query language entirely and search a circular patch of sky by right ascension, declination, and radius. Either way you get the same well-typed records back. | ๐ŸŽฏ Target Audience | ๐Ÿ’ก Primary Use Cases | |---|---| | Astronomers and astrophysics researchers | Building target lists for observing runs | | Data scientists and ML practitioners | Training and testing stellar classification models | | Educators and students | Teaching astrometry, parallax, and photometry | | Science communicators and hobbyists | Mapping local stellar neighborhoods | ### ๐Ÿ“‹ What the Gaia DR3 Star Catalog Scraper does This Actor queries the ESA Gaia DR3 archive and returns one record per stellar source. For each source it collects the unique Gaia source identifier, right ascension and declination, trigonometric parallax, proper motion in RA and Dec, mean magnitudes in the G, BP, and RP photometric bands, radial velocity, and the GSP-Phot effective temperature. You control the selection with either a full ADQL query or a cone search. ### ๐ŸŽฌ Full Demo (_๐Ÿšง Coming soon_) ### โš™๏ธ Input | Field | Type | Required | Description | |---|---|---|---| | `adqlQuery` | string | No | A full ADQL query against `gaiadr3.gaia_source`. Overrides the cone search when set. | | `ra` | integer | No | Cone center right ascension in degrees (0 to 360). | | `dec` | integer | No | Cone center declination in degrees (-90 to 90). | | `radius` | string | No | Cone radius in degrees, for example 0.1. | | `maxItems` | integer | No | Maximum records to return. Free plan is capped at 10. | **Example 1 โ€” cone search around a patch of sky** ```json { "ra": 45, "dec": 0, "radius": "0.1", "maxItems": 50 } ```` **Example 2 โ€” custom ADQL query** ```json { "adqlQuery": "SELECT TOP 20 source_id, ra, dec, parallax, pmra, pmdec, phot_g_mean_mag, phot_bp_mean_mag, phot_rp_mean_mag, radial_velocity, teff_gspphot FROM gaiadr3.gaia_source WHERE parallax IS NOT NULL", "maxItems": 20 } ``` > โš ๏ธ **Good to Know:** the Gaia Archive synchronous service caps each query at roughly 2000 rows, so keep cone radii small and use `TOP` in custom queries. Radial velocity and effective temperature are only measured for a subset of brighter, well-characterized stars, so those two fields are often null for faint sources. That is expected, not a bug. ### ๐Ÿ“Š Output | Field | Type | Description | |---|---|---| | ๐Ÿ†” `sourceId` | string | Unique Gaia DR3 source identifier (kept as a string to preserve full 64-bit precision). | | ๐Ÿ“ `ra` | number | Right ascension in degrees. | | ๐Ÿ“ `dec` | number | Declination in degrees. | | ๐Ÿ“ `parallax` | number | Trigonometric parallax in milliarcseconds. | | โžก๏ธ `pmra` | number | Proper motion in right ascension (mas/yr). | | โฌ†๏ธ `pmdec` | number | Proper motion in declination (mas/yr). | | โœจ `photGMeanMag` | number | Mean magnitude in the Gaia G band. | | ๐Ÿ”ต `photBpMeanMag` | number | Integrated BP mean magnitude. | | ๐Ÿ”ด `photRpMeanMag` | number | Integrated RP mean magnitude. | | ๐ŸŒ€ `radialVelocity` | number | Radial velocity in km/s (null when not measured). | | ๐ŸŒก `teff` | number | GSP-Phot effective temperature in Kelvin (null when not measured). | | ๐Ÿ•’ `scrapedAt` | string | ISO timestamp of when the record was collected. | | โŒ `error` | string | Error message, null on successful records. | **Real sample records** ```json { "sourceId": "5188146087831728384", "ra": 44.96061355952784, "dec": -0.06385449994739745, "parallax": 0.5875496627769571, "pmra": 7.72780001640072, "pmdec": -2.850661973997159, "photGMeanMag": 15.877191, "photBpMeanMag": 16.23885, "photRpMeanMag": 15.346017, "radialVelocity": null, "teff": 5591.2266, "scrapedAt": "2026-06-05T16:12:16.388Z", "error": null } ``` ```json { "sourceId": "5188146117896344448", "ra": 44.965924658616835, "dec": -0.05586715308853149, "parallax": 0.06527682229940536, "pmra": 13.307380697609029, "pmdec": 5.73381569742609, "photGMeanMag": 20.262077, "photBpMeanMag": 21.602179, "photRpMeanMag": 18.898542, "radialVelocity": null, "teff": null, "scrapedAt": "2026-06-05T16:12:16.447Z", "error": null } ``` ```json { "sourceId": "5188146568868064768", "ra": 44.961407043733274, "dec": -0.03320965054177338, "parallax": 0.43504893366604697, "pmra": 7.574971584312527, "pmdec": -13.324429895509663, "photGMeanMag": 17.123215, "photBpMeanMag": 17.582111, "photRpMeanMag": 16.49985, "radialVelocity": null, "teff": 4810.333, "scrapedAt": "2026-06-05T16:12:16.469Z", "error": null } ``` ### โœจ Why choose this Actor - Talks directly to the official ESA Gaia Archive TAP service, so the data is authoritative and current with DR3. - Accepts both ADQL power queries and plain cone searches, so beginners and experts are both covered. - Preserves the full 64-bit `source_id` as a string, so identifiers never get mangled by numeric rounding. - Returns clean, consistently typed fields ready for analysis. - No API key required. ### ๐Ÿ“ˆ How it compares to alternatives | Approach | This Actor | Manual TAP queries | Bulk catalog downloads | |---|---|---|---| | Setup | None, just fill the form | Write ADQL and parse VOTable yourself | Download and process huge files | | ADQL support | Yes | Yes | No | | Cone search helper | Yes | Build it yourself | No | | Structured records | Yes | Manual parsing | Manual parsing | | ID precision safe | Yes | Depends on parser | Depends on parser | ### ๐Ÿš€ How to use 1. Sign up for a free Apify account using [this link](https://console.apify.com/sign-up?fpr=vmoqkp). 2. Open the Gaia DR3 Star Catalog Scraper. 3. Either enter a cone search (RA, Dec, radius) or paste a full ADQL query. 4. Set how many records you want and start the run. 5. Collect your structured stellar records when the run finishes. ### ๐Ÿ’ผ Business use cases #### Research data pipelines | Need | How this helps | |---|---| | Reproducible queries | Save query inputs and rerun anytime | | Clean inputs for analysis | Receive typed records instead of raw VOTable | #### Education and outreach | Need | How this helps | |---|---| | Classroom datasets | Pull a small patch of sky for exercises | | Live demonstrations | Show parallax and proper motion on real stars | #### Machine learning | Need | How this helps | |---|---| | Training data | Build labeled stellar samples by region | | Feature engineering | Combine photometry, motion, and temperature | #### Planetarium and visualization | Need | How this helps | |---|---| | Star map building | Fetch positions and magnitudes for a sky region | | Color rendering | Use BP and RP magnitudes for star colors | ### ๐Ÿ”Œ Automating Gaia DR3 Star Catalog Scraper Connect runs to Make, Zapier, Slack, Airbyte, GitHub, or Google Drive through Apify integrations and webhooks. Trigger a query on a schedule, then route the structured records into your warehouse, a spreadsheet, or a notification channel automatically. ### ๐ŸŒŸ Beyond business use cases - **Research:** assemble custom stellar samples for a paper or thesis. - **Personal:** explore the stars in your favorite constellation. - **Non-profit:** power free planetarium and outreach tools. - **Experimentation:** prototype astrometry and photometry ideas quickly. ### ๐Ÿค– Ask an AI assistant Paste your records into [ChatGPT](https://chat.openai.com), [Claude](https://claude.ai), [Perplexity](https://www.perplexity.ai), or [Microsoft Copilot](https://copilot.microsoft.com) and ask it to summarize the stellar population, estimate distances from parallax, or sort sources by temperature. ### โ“ Frequently Asked Questions **Q: Do I need a Gaia or ESA account or API key?** No. The Gaia Archive TAP service used here is open and keyless. **Q: Which catalog does this query?** Gaia Data Release 3, table `gaiadr3.gaia_source`. **Q: Can I write my own query?** Yes. Provide a full ADQL query and it runs as written. The cone search is only used when no query is given. **Q: Why are radial velocity and temperature sometimes null?** Those measurements only exist for a subset of brighter, well-characterized stars in DR3. Faint sources legitimately have no value. **Q: Why is the source ID a string and not a number?** Gaia source IDs are 64-bit integers that exceed the safe range of standard numbers, so they are kept as strings to avoid rounding. **Q: How many records can I get per run?** The synchronous archive service caps each query near 2000 rows. Use a small radius or a `TOP` clause. **Q: How do I convert parallax to distance?** Distance in parsecs is roughly 1000 divided by the parallax in milliarcseconds, for sources with reliable parallax. **Q: What units are used?** Degrees for coordinates, milliarcseconds for parallax, mas/yr for proper motion, magnitudes for photometry, km/s for radial velocity, and Kelvin for temperature. **Q: Can I search a named star or region?** Use the cone search with the RA and Dec of the region, or an ADQL query with your own constraints. **Q: Is the data live?** Each run queries the archive directly, so results reflect the current DR3 catalog. ### ๐Ÿ”Œ Integrate with any app Apify connects to thousands of tools through its API, webhooks, and the integrations above, so your stellar records can flow into whatever system you already use. ### ๐Ÿ”— Recommended Actors - [ParseForge collection](https://apify.com/parseforge) for more open-data and catalog scrapers. > ๐Ÿ’ก **Pro Tip:** browse the complete [ParseForge collection](https://apify.com/parseforge). **๐Ÿ†˜ Need Help?** [Open our contact form](https://tally.so/r/BzdKgA) > **โš ๏ธ Disclaimer:** independent tool, not affiliated with ESA or the Gaia mission. Only publicly available archive data is collected. # Actor input Schema ## `adqlQuery` (type: `string`): Optional. A full ADQL query to run against the Gaia DR3 archive (table gaiadr3.gaia\_source). When provided, this overrides the cone search fields below. Leave empty to use a cone search instead. ## `ra` (type: `integer`): Right ascension of the cone search center in degrees (0 to 360). Used only when no ADQL query is provided above. ## `dec` (type: `integer`): Declination of the cone search center in degrees (-90 to 90). Used only when no ADQL query is provided above. ## `radius` (type: `string`): Search radius in degrees around the cone center (for example 0.1). Keep small to stay within archive limits. Used only when no ADQL query is provided. ## `maxItems` (type: `integer`): Free users: Limited to 10 items (preview). Paid users: Optional, max 1,000,000 ## Actor input object example ```json { "adqlQuery": "SELECT TOP 20 source_id, ra, dec, parallax, pmra, pmdec, phot_g_mean_mag, phot_bp_mean_mag, phot_rp_mean_mag, radial_velocity, teff_gspphot FROM gaiadr3.gaia_source WHERE parallax IS NOT NULL", "radius": "0.1", "maxItems": 10 } ``` # 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 = { "adqlQuery": "SELECT TOP 20 source_id, ra, dec, parallax, pmra, pmdec, phot_g_mean_mag, phot_bp_mean_mag, phot_rp_mean_mag, radial_velocity, teff_gspphot FROM gaiadr3.gaia_source WHERE parallax IS NOT NULL", "radius": "0.1", "maxItems": 10 }; // Run the Actor and wait for it to finish const run = await client.actor("parseforge/gaia-star-catalog-scraper").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 = { "adqlQuery": "SELECT TOP 20 source_id, ra, dec, parallax, pmra, pmdec, phot_g_mean_mag, phot_bp_mean_mag, phot_rp_mean_mag, radial_velocity, teff_gspphot FROM gaiadr3.gaia_source WHERE parallax IS NOT NULL", "radius": "0.1", "maxItems": 10, } # Run the Actor and wait for it to finish run = client.actor("parseforge/gaia-star-catalog-scraper").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 '{ "adqlQuery": "SELECT TOP 20 source_id, ra, dec, parallax, pmra, pmdec, phot_g_mean_mag, phot_bp_mean_mag, phot_rp_mean_mag, radial_velocity, teff_gspphot FROM gaiadr3.gaia_source WHERE parallax IS NOT NULL", "radius": "0.1", "maxItems": 10 }' | apify call parseforge/gaia-star-catalog-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=parseforge/gaia-star-catalog-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "ESA Gaia DR3 Star Catalog Scraper", "description": "Tap the ESA Gaia DR3 archive for real stellar measurements by ADQL query or cone search. Each star returns its source ID, position, parallax, proper motion, G band magnitude, radial velocity, and effective temperature. Useful for astronomy research, target lists, and star maps.", "version": "0.1", "x-build-id": "WT4g6cMbghOPB3qY9" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/parseforge~gaia-star-catalog-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-parseforge-gaia-star-catalog-scraper", "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/parseforge~gaia-star-catalog-scraper/runs": { "post": { "operationId": "runs-sync-parseforge-gaia-star-catalog-scraper", "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/parseforge~gaia-star-catalog-scraper/run-sync": { "post": { "operationId": "run-sync-parseforge-gaia-star-catalog-scraper", "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", "properties": { "adqlQuery": { "title": "ADQL Query", "type": "string", "description": "Optional. A full ADQL query to run against the Gaia DR3 archive (table gaiadr3.gaia_source). When provided, this overrides the cone search fields below. Leave empty to use a cone search instead." }, "ra": { "title": "Cone Center RA (degrees)", "minimum": 0, "maximum": 360, "type": "integer", "description": "Right ascension of the cone search center in degrees (0 to 360). Used only when no ADQL query is provided above." }, "dec": { "title": "Cone Center Dec (degrees)", "minimum": -90, "maximum": 90, "type": "integer", "description": "Declination of the cone search center in degrees (-90 to 90). Used only when no ADQL query is provided above." }, "radius": { "title": "Cone Radius (degrees)", "type": "string", "description": "Search radius in degrees around the cone center (for example 0.1). Keep small to stay within archive limits. Used only when no ADQL query is provided." }, "maxItems": { "title": "Max Items", "minimum": 1, "maximum": 1000000, "type": "integer", "description": "Free users: Limited to 10 items (preview). Paid users: Optional, max 1,000,000" } } }, "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 } } } } } } } } } } ```