{"id":35546683,"url":"https://github.com/behrouzz/gaiadr3","last_synced_at":"2026-01-04T06:04:19.946Z","repository":{"id":45141348,"uuid":"513356692","full_name":"behrouzz/gaiadr3","owner":"behrouzz","description":"Retrieve data and analysis package for Gaia Data Release 3","archived":false,"fork":false,"pushed_at":"2023-01-10T12:56:51.000Z","size":18,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-08T21:22:02.868Z","etag":null,"topics":["astronomy","astrophysics","gaia","gaiadr3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/behrouzz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-07-13T02:37:56.000Z","updated_at":"2025-01-10T08:59:52.000Z","dependencies_parsed_at":"2023-02-08T18:45:16.357Z","dependency_job_id":null,"html_url":"https://github.com/behrouzz/gaiadr3","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/behrouzz/gaiadr3","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/behrouzz%2Fgaiadr3","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/behrouzz%2Fgaiadr3/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/behrouzz%2Fgaiadr3/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/behrouzz%2Fgaiadr3/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/behrouzz","download_url":"https://codeload.github.com/behrouzz/gaiadr3/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/behrouzz%2Fgaiadr3/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28198688,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2026-01-04T02:00:06.065Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["astronomy","astrophysics","gaia","gaiadr3"],"created_at":"2026-01-04T06:02:29.716Z","updated_at":"2026-01-04T06:04:15.450Z","avatar_url":"https://github.com/behrouzz.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"**Author:** [Behrouz Safari](https://behrouzz.github.io/)\u003cbr/\u003e\n**Website:** [AstroDataScience.Net](http://astrodatascience.net/)\u003cbr/\u003e\n\n# gaiadr3\n*Retrieve data and analysis package for Gaia Data Release 3*\n\n\n## Installation\n\nInstall the latest version of *gaiadr3* from [PyPI](https://pypi.org/project/gaiadr3/):\n\n    pip install gaiadr3\n\nThe only requirement is *pandas*.\n\n\n## Background\n\nGaia Data Release 3 presents two main types of data: *tabular* and *ancillary*.\nThe tabular data can be retrieved using ADQL Tap queries and are described in the [Data Model](https://gea.esac.esa.int/archive/documentation/GDR3/Gaia_archive/chap_datamodel/)\nThe ancillary data are those that can not be accessed via ADQL Tap queries. Epoch photomerty and spectroscopic data are of this type.\nYou need to use DataLink to retrieve this type of data. \n\n\n## Tap queries\n\nThe standard way to retrieve tabular data is by using tap queries. Pass your script to the *sql2df* function. It will return two pandas dataframes: data and meta.\n\n```python\n\u003e\u003e\u003e from gaiadr3 import sql2df\n\u003e\u003e\u003e data, meta = sql2df('SELECT TOP 5 source_id, ra, dec FROM gaiadr3.gaia_source')\n\u003e\u003e\u003e print(meta)\n                                                 description  unit\nname                                                              \nsource_id  Unique source identifier (unique within a part...  None\nra                                           Right ascension   deg\ndec                                              Declination   deg\n\u003e\u003e\u003e print(data)\n             source_id          ra        dec\n0  4116903625596296576  266.323047 -22.651077\n1  4116903625596299136  266.321568 -22.651833\n2  4116903625596302976  266.320308 -22.652672\n3  4116903625596305408  266.321332 -22.651379\n4  4116903625596305536  266.321399 -22.651430\n```\n\nFor ease of use, I have created some shortcut keywords which begin with '@'. Currently, they are:\n\n* @MT : Main Table (gaiadr3.gaia_source)\n* @LT : Lite Table (gaiadr3.gaia_source_lite)\n* @COLS : A selection of the most important columns\n\n```python\n\u003e\u003e\u003e data, meta = sql2df('SELECT TOP 3 @COLS FROM @MT')\n\u003e\u003e\u003e data\n             source_id          ra  ...  has_mcmc_gspphot  has_mcmc_msc\n0  4116903625596296576  266.323047  ...             False         False\n1  4116903625596299136  266.321568  ...             False         False\n2  4116903625596302976  266.320308  ...             False         False\n\n[3 rows x 24 columns]\n```\n\n\n## Get single source\n\nThe simplest way to get data for a single source, is using *GaiaObject* class. You can create an instance of this class by passing a *source_id*:\n\n```python\n\u003e\u003e\u003e from gaiadr3 import GaiaObject\n\u003e\u003e\u003e source_id = 30343944744320\n\u003e\u003e\u003e obj = GaiaObject(source_id=source_id)\n```\n\nNow you can use the *download* method to retrieve both tabular and ancillary. This method accepts two boolean arguments: *key_param* and *ancillary*.\nBoth are True by default. After using this method, some important key parameter will be downloaded as a python dictionary in the *key_param* attribute.\n\n```python\n\u003e\u003e\u003e obj.download()\n\u003e\u003e\u003e print(obj.key_param['data'])\n{'solution_id': 1636148068921376768,\n 'ra': 45.09499151004629,\n 'dec': 0.4768361311353548,\n 'parallax': 1.120139133994462,\n 'distance_gspphot': 913.4706,\n 'pm': 19.76517,\n 'pmra': 19.35330019571839,\n 'pmdec': 4.013937591116442,\n 'radial_velocity': 40.224552,\n 'teff_gspphot': 12291.837,\n 'logg_gspphot': 4.0962,\n 'phot_g_mean_mag': 9.899,\n 'phot_bp_mean_mag': 9.873377,\n 'phot_rp_mean_mag': 9.918395,\n 'phot_g_mean_flux': 2067028.6966188122,\n 'phot_bp_mean_flux': 1534850.5584509764,\n 'phot_rp_mean_flux': 854673.6713712276,\n 'has_epoch_photometry': True,\n 'has_epoch_rv': False,\n 'has_rvs': True,\n 'has_xp_continuous': True,\n 'has_xp_sampled': True,\n 'has_mcmc_gspphot': True,\n 'has_mcmc_msc': True}\n```\n\nIf you don't know what are these parameters, look at *obj.key_param['meta']*. \u003cbr/\u003e\n\nThe ancillary data will be downloaded as csv files in the 'data' folder in the working directory. These data, if exist, can be accessed as attributes:\u003cbr/\u003e\n\n```python\n\u003e\u003e\u003e print(obj.xp_samp)\n     wavelength          flux    flux_error\n0         336.0  7.519030e-15  8.592673e-16\n1         338.0  6.699424e-15  7.309379e-16\n2         340.0  5.937778e-15  6.685453e-16\n3         342.0  5.614390e-15  6.325656e-16\n4         344.0  5.726218e-15  6.402061e-16\n..          ...           ...           ...\n338      1012.0  5.449369e-16  6.181877e-17\n339      1014.0  5.333555e-16  6.771072e-17\n340      1016.0  5.501445e-16  7.086527e-17\n341      1018.0  5.647527e-16  6.731273e-17\n342      1020.0  6.096352e-16  6.407823e-17\n\n[343 rows x 3 columns]\n```\n\nAttributes corresponding to the ancillary data are: *ep_phot*, *rvs*, *xp_samp*, *xp_cont*. Use the *has* attribute to see which of these are available.\n\n```python\n\u003e\u003e\u003e print(obj.has)\n{'EPOCH_PHOTOMETRY': True,\n 'RVS': True,\n 'XP_CONTINUOUS': True,\n 'XP_SAMPLED': True,\n 'MCMC_GSPPHOT': True,\n 'MCMC_MSC': True}\n```\n\n## Get multiple sources\n\nIf you want to get ancillary data for multiple sources you should use DataLink class. \n\n```python\n\u003e\u003e\u003e from gaiadr3 import DataLink\n\u003e\u003e\u003e sources = [30343944744320, 6196457933368101888]\n\u003e\u003e\u003e dl = DataLink(source_id=sources, retrieval_type='ALL')\n\u003e\u003e\u003e dl.download()\n```\n\nBy default, the data will be downloaded in 'data' folder in the working directory. For each object a folder will be created.\nUsing the *get_objects* method, you can access each source as a GaiaObject as explained above.\nLet's get the epoch photometry for green, blue and red bands for the first source:\n\n```python\n\u003e\u003e\u003e objects = dl.get_objects()\n\u003e\u003e\u003e g, b, r = objects[0].ep_phot\n\u003e\u003e\u003e print(g)\n                                 mag          flux   flux_error\nTCB                                                            \n2014-09-06 08:55:04.077123  9.910611  2.045042e+06  3983.560844\n2014-09-06 10:41:40.701409  9.909272  2.047565e+06  3652.792295\n2014-12-27 00:49:44.365184  9.890911  2.082487e+06  3175.264209\n2014-12-27 02:36:15.656166  9.874771  2.113675e+06  4644.732420\n2015-01-16 06:49:25.778803  9.883712  2.096341e+06  1828.438678\n2015-01-16 08:35:59.407773  9.888541  2.087037e+06  2039.618901\n2015-02-15 00:23:35.148389  9.864696  2.133381e+06  2924.895816\n2015-07-07 19:46:09.417232  9.886747  2.090489e+06  2817.581457\n2015-08-01 03:31:05.147557  9.922456  2.022854e+06  3171.964369\n2015-08-30 03:21:11.667936  9.880055  2.103414e+06   977.945250\n2016-01-05 13:57:07.739350  9.880296  2.102947e+06  1754.446362\n2016-01-05 15:43:39.101625  9.878165  2.107079e+06  1487.112158\n2016-01-31 01:44:44.422883  9.919168  2.028988e+06  1516.905039\n2016-02-25 03:16:43.072088  9.923205  2.021458e+06  2363.931131\n2016-07-17 08:55:16.873392  9.905461  2.054766e+06  3400.421158\n2016-07-17 10:41:51.854195  9.909443  2.047244e+06  1766.953020\n2016-08-15 14:44:12.432337  9.904904  2.055821e+06  1543.565592\n2016-09-08 14:45:34.479689  9.897831  2.069257e+06  2292.732039\n2016-09-08 16:32:08.406143  9.886640  2.090695e+06  4654.839112\n2017-01-14 21:05:28.352674  9.926262  2.015774e+06  1613.007848\n2017-01-14 22:52:01.924915  9.909325  2.047467e+06  3051.287780\n2017-02-13 10:01:27.449079  9.920222  2.027019e+06  1790.127633\n2017-02-13 11:48:01.024177  9.926633  2.015085e+06  3115.379630\n2017-03-05 21:57:47.804485  9.886628  2.090718e+06  1692.944591\n2017-03-05 23:44:23.399045  9.877953  2.107490e+06  4360.998681\n```\n\nSee more at [astrodatascience.net](https://astrodatascience.net/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbehrouzz%2Fgaiadr3","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbehrouzz%2Fgaiadr3","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbehrouzz%2Fgaiadr3/lists"}