{"openapi":"3.1.0","info":{"title":"SpaceCatalog API","version":"1.0.0","description":"The open catalog of everything above: 166,000 stars, planets, moons, exoplanets, galaxies, nebulae, clusters, black holes, asteroids and comets.\n\nNo key, no account, no CORS restrictions. 60 requests per minute per client.\n\nData from SpaceCatalog.org. Individual records carry their source and license in `source`; attribution is required for CC-BY and CC-BY-SA rows.","license":{"name":"CC-BY-4.0","url":"https://creativecommons.org/licenses/by/4.0/"},"contact":{"url":"https://spacecatalog.org/api"}},"servers":[{"url":"https://spacecatalog.org"}],"paths":{"/api/v1/objects":{"get":{"operationId":"listObjects","summary":"List objects","description":"The whole catalog, filtered and paged. Filters compose: category, constellation, class, magnitude range and the curated flag can all be combined. Results are brightest first unless you say otherwise, and objects without a recorded magnitude sort last in either direction.","parameters":[{"name":"category","in":"query","required":false,"description":"One of the eleven top-level classes.","schema":{"type":"string","enum":["star","planet","moon","exoplanet","galaxy","nebula","cluster","black_hole","asteroid","comet","other"]},"example":"galaxy"},{"name":"constellation","in":"query","required":false,"description":"IAU constellation. Spacing and case are ignored: 'Ursa Major', 'ursa-major' and 'ursamajor' are the same region.","schema":{"type":"string"},"example":"orion"},{"name":"type","in":"query","required":false,"description":"Exact `object_type` string, as returned in the records themselves — 'Spiral galaxy Sb', 'M2Ib red supergiant'.","schema":{"type":"string"}},{"name":"mag_min","in":"query","required":false,"description":"Faintest bound: only objects at or above this magnitude.","schema":{"type":"number","minimum":-30,"maximum":40}},{"name":"mag_max","in":"query","required":false,"description":"Brightest bound: only objects at or below this magnitude. `mag_max=6` is roughly the naked-eye sky.","schema":{"type":"number","minimum":-30,"maximum":40},"example":"6"},{"name":"featured","in":"query","required":false,"description":"Restrict to the curated entries — the ones with hand-written descriptions.","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Field to order by.","schema":{"type":"string","enum":["name","type","mass","distance","mag","constellation"],"default":"mag"}},{"name":"order","in":"query","required":false,"description":"Sort direction.","schema":{"type":"string","enum":["asc","desc"],"default":"asc"}},{"name":"limit","in":"query","required":false,"description":"Records per page.","schema":{"type":"integer","default":25,"minimum":1,"maximum":200}},{"name":"offset","in":"query","required":false,"description":"Records to skip. Capped at 100,000 — past that you want a bulk export, not a page.","schema":{"type":"integer","default":0,"minimum":0,"maximum":100000}},{"name":"epoch","in":"query","required":false,"description":"Carry every position in the answer forward to a date. `now`, a Julian year (`2026.5`, `J2026.5`), or an ISO 8601 date, anywhere between 1500 and 2500 — a published proper motion is a velocity measured over a few years, and carrying one much further is extrapolation with no measurement under it. The stored `ra_deg` and `dec_deg` stay J2000; the propagated pair arrives beside them as `epoch_ra_deg` and `epoch_dec_deg`, and an `epoch` block on the response says which terms went into them and which did not.","schema":{"type":"string"},"example":"now"},{"name":"frame","in":"query","required":false,"description":"Which frame `epoch` propagates into, and meaningless without it. `icrs` applies the object's own proper motion and nothing else — a position epoch, the sense Gaia uses, and the one to cross-match in. `date` also turns the coordinate grid to the true equator and equinox of that instant — precession plus nutation — which is what a telescope mount expects and is about fifty arcseconds a year larger.","schema":{"type":"string","enum":["icrs","date"],"default":"icrs"},"example":"date"},{"name":"format","in":"query","required":false,"description":"Response shape. `json` is the full record, including the parts a table has no room for. `votable` is IVOA VOTable 1.4 with units and UCDs, which TOPCAT and Aladin open directly; `csv` is the same columns under the same names. Both flat forms drop the nested parts of a record — an object's properties, designations and source block — and keep the observable quantities.","schema":{"type":"string","enum":["json","votable","csv"],"default":"json"},"example":"votable"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObjectList"}},"application/x-votable+xml":{"schema":{"type":"string","description":"The same rows flat, requested with format=votable."}},"text/csv":{"schema":{"type":"string","description":"The same rows flat, requested with format=csv."}}}},"400":{"description":"A parameter was missing or out of range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited — see the retry-after header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/objects/{slug}":{"get":{"operationId":"getObject","summary":"Get one object","description":"Everything known about a single object: the record itself, its source-specific properties, every cross-designation it answers to, and the catalog it came from with that catalog's license. Add `epoch` to be told where it is at a date rather than only where it was measured in 2000 — and, for a variable star, where in its cycle it is at that same instant and when its next maximum or minimum falls.","parameters":[{"name":"slug","in":"path","required":true,"description":"The object's stable identifier, as it appears in its site URL.","schema":{"type":"string"},"example":"sgr-a"},{"name":"epoch","in":"query","required":false,"description":"Carry every position in the answer forward to a date. `now`, a Julian year (`2026.5`, `J2026.5`), or an ISO 8601 date, anywhere between 1500 and 2500 — a published proper motion is a velocity measured over a few years, and carrying one much further is extrapolation with no measurement under it. The stored `ra_deg` and `dec_deg` stay J2000; the propagated pair arrives beside them as `epoch_ra_deg` and `epoch_dec_deg`, and an `epoch` block on the response says which terms went into them and which did not.","schema":{"type":"string"},"example":"now"},{"name":"frame","in":"query","required":false,"description":"Which frame `epoch` propagates into, and meaningless without it. `icrs` applies the object's own proper motion and nothing else — a position epoch, the sense Gaia uses, and the one to cross-match in. `date` also turns the coordinate grid to the true equator and equinox of that instant — precession plus nutation — which is what a telescope mount expects and is about fifty arcseconds a year larger.","schema":{"type":"string","enum":["icrs","date"],"default":"icrs"},"example":"date"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObjectDetail"}}}},"400":{"description":"A parameter was missing or out of range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited — see the retry-after header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/objects/{slug}/spectrum":{"get":{"operationId":"getObjectSpectrum","summary":"Get an object's spectrum","description":"The object's light spread out by wavelength: its own measured spectrum where a survey pointed a fibre at it, and otherwise — for a star — the spectrum of its Morgan-Keenan type from a standard stellar atlas. `kind` says which of the two arrived, and the difference matters: a representative spectrum describes stars like this one, never this one. Flux is normalised to the median of the spectrum and therefore unitless; `identifier` names the original exposure for anyone who needs calibrated flux at full resolution. An object with neither answers 404.","parameters":[{"name":"slug","in":"path","required":true,"description":"The object's stable identifier, as it appears in its site URL.","schema":{"type":"string"},"example":"vega"},{"name":"format","in":"query","required":false,"description":"Response shape. `json` is the full record, including the parts a table has no room for. `votable` is IVOA VOTable 1.4 with units and UCDs, which TOPCAT and Aladin open directly; `csv` is the same columns under the same names. Both flat forms drop the nested parts of a record — an object's properties, designations and source block — and keep the observable quantities.","schema":{"type":"string","enum":["json","votable","csv"],"default":"json"},"example":"votable"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObjectSpectrum"}},"application/x-votable+xml":{"schema":{"type":"string","description":"The same rows flat, requested with format=votable."}},"text/csv":{"schema":{"type":"string","description":"The same rows flat, requested with format=csv."}}}},"400":{"description":"A parameter was missing or out of range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited — see the retry-after header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/search":{"get":{"operationId":"searchObjects","summary":"Search","description":"Full-text over names and designations, with trigram similarity as the fallback for near misses. A typed designation wins over everything else, so 'NGC 224' resolves to the Andromeda Galaxy rather than to a page of its own. Each result carries the designation that matched.","parameters":[{"name":"q","in":"query","required":true,"description":"What to look for: a name, a designation, or something close to one.","schema":{"type":"string"},"example":"andromeda"},{"name":"category","in":"query","required":false,"description":"Restrict results to one class.","schema":{"type":"string","enum":["star","planet","moon","exoplanet","galaxy","nebula","cluster","black_hole","asteroid","comet","other"]}},{"name":"limit","in":"query","required":false,"description":"Maximum results.","schema":{"type":"integer","default":20,"minimum":1,"maximum":100}},{"name":"format","in":"query","required":false,"description":"Response shape. `json` is the full record, including the parts a table has no room for. `votable` is IVOA VOTable 1.4 with units and UCDs, which TOPCAT and Aladin open directly; `csv` is the same columns under the same names. Both flat forms drop the nested parts of a record — an object's properties, designations and source block — and keep the observable quantities.","schema":{"type":"string","enum":["json","votable","csv"],"default":"json"},"example":"votable"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResults"}},"application/x-votable+xml":{"schema":{"type":"string","description":"The same rows flat, requested with format=votable."}},"text/csv":{"schema":{"type":"string","description":"The same rows flat, requested with format=csv."}}}},"400":{"description":"A parameter was missing or out of range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited — see the retry-after header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/visible":{"get":{"operationId":"visibleNow","summary":"What is up right now","description":"Objects above the horizon from a given position, brightest first as seen from the ground rather than above the atmosphere — `mag_at_altitude` carries the extinction of the air in the way and is what the list is ordered on, so an object low in the sky sorts below an equally bright one overhead. With altitude, azimuth and a compass bearing. Objects with a fixed position come from the catalog, carried forward by their own proper motion and precessed from J2000 to the equator of the requested instant; the Sun, Moon and planets are computed from an ephemeris, so they carry their real current magnitude and distance. Every position in the list is therefore of date, in one frame. The response also reports the Sun's altitude and what that makes of the sky — an object at 40° in daylight is up but not visible.","parameters":[{"name":"lat","in":"query","required":true,"description":"Observer latitude in degrees, north positive.","schema":{"type":"number","minimum":-90,"maximum":90},"example":"19.82"},{"name":"lon","in":"query","required":true,"description":"Observer longitude in degrees, east positive.","schema":{"type":"number","minimum":-180,"maximum":180},"example":"-155.47"},{"name":"time","in":"query","required":false,"description":"ISO 8601 instant. Defaults to now, and is rounded to five minutes.","schema":{"type":"string"}},{"name":"min_alt","in":"query","required":false,"description":"Altitude floor in degrees. The default of 15 skips the haze and obstructions near the horizon.","schema":{"type":"number","default":15,"minimum":-90,"maximum":90}},{"name":"elevation_m","in":"query","required":false,"description":"Observer height above sea level, in metres.","schema":{"type":"number","default":0,"minimum":-500,"maximum":9000}},{"name":"limit","in":"query","required":false,"description":"Maximum objects returned.","schema":{"type":"integer","default":25,"minimum":1,"maximum":100}},{"name":"format","in":"query","required":false,"description":"Response shape. `json` is the full record, including the parts a table has no room for. `votable` is IVOA VOTable 1.4 with units and UCDs, which TOPCAT and Aladin open directly; `csv` is the same columns under the same names. Both flat forms drop the nested parts of a record — an object's properties, designations and source block — and keep the observable quantities.","schema":{"type":"string","enum":["json","votable","csv"],"default":"json"},"example":"votable"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VisibleList"}},"application/x-votable+xml":{"schema":{"type":"string","description":"The same rows flat, requested with format=votable."}},"text/csv":{"schema":{"type":"string","description":"The same rows flat, requested with format=csv."}}}},"400":{"description":"A parameter was missing or out of range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited — see the retry-after header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/events":{"get":{"operationId":"skyEvents","summary":"The dated sky","description":"Everything that happens on a date rather than at a place: eclipses, meteor showers, the Moon's quarters, close pairings of the bright planets, oppositions and greatest elongations, the equinoxes and solstices, and near-Earth asteroid flybys. Every instant here is the same fact everywhere on Earth — a full moon is full for all of us at once — which is what separates this endpoint from `/api/v1/visible`, where the answer depends entirely on where you are standing. Seven of the eight kinds are solved from an ephemeris when you ask, so there is no stored list to go stale; the eighth cannot be, because a newly discovered asteroid has no orbit until somebody measures one, and the response says in `meta.close_approaches` which window that part covers and when it was last refreshed. Positions are geocentric ICRS/J2000: the body at the instant, or a shower's radiant. The `circumstances` block carries whatever numbers the kind has — a separation, an obscuration, a rate, a miss distance — and omits what it does not.","parameters":[{"name":"from","in":"query","required":false,"description":"ISO 8601 instant to start at. Defaults to now.","schema":{"type":"string"},"example":"2026-01-01"},{"name":"to","in":"query","required":false,"description":"ISO 8601 instant to stop at, at most two years after `from`. Defaults to eighteen months out, which is the horizon the calendar page draws.","schema":{"type":"string"},"example":"2026-12-31"},{"name":"kind","in":"query","required":false,"description":"Restrict to one kind of event. Repeatable — `kind=eclipse&kind=flyby` asks for both.","schema":{"type":"string","enum":["moon","season","opposition","elongation","conjunction","eclipse","shower","flyby"]}},{"name":"limit","in":"query","required":false,"description":"Maximum events returned.","schema":{"type":"integer","default":500,"minimum":1,"maximum":500}},{"name":"format","in":"query","required":false,"description":"Response shape. `json` is the full record, including the parts a table has no room for. `votable` is IVOA VOTable 1.4 with units and UCDs, which TOPCAT and Aladin open directly; `csv` is the same columns under the same names. Both flat forms drop the nested parts of a record — an object's properties, designations and source block — and keep the observable quantities.","schema":{"type":"string","enum":["json","votable","csv"],"default":"json"},"example":"votable"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventList"}},"application/x-votable+xml":{"schema":{"type":"string","description":"The same rows flat, requested with format=votable."}},"text/csv":{"schema":{"type":"string","description":"The same rows flat, requested with format=csv."}}}},"400":{"description":"A parameter was missing or out of range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited — see the retry-after header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/ephemeris":{"get":{"operationId":"observeTarget","summary":"One target, one night","description":"Rise, transit and set for a single object from a single place, with the altitude and air-mass curve of the whole night beside them and the Moon on every row of it. `/api/v1/visible` answers what is above the horizon at an instant; this answers the question an observing run is planned from, which is whether *this* object is worth the drive on *this* night — how many hours it is both high enough and dark enough, when in those hours it is highest, and how close the Moon will be while they pass. The target is any identifier this catalog resolves, or a bare position for something no catalogue holds yet. Rise and set are the almanac definition, the upper limb crossing a horizon lifted by 34 arcminutes of refraction scaled to the density of the air at the observer's elevation; every other altitude in the answer, including the curve and the thresholds cut out of it, is the geometric altitude of the body's centre. Those two differ by about half a degree and the response reports the horizon it used rather than leaving the reader to discover the difference. The observable hours are solved for, not counted off the samples, so they do not change when `step_min` does.","parameters":[{"name":"object","in":"query","required":false,"description":"What to observe: a slug, a designation, or a survey identifier — 'm31', 'Barnard’s Star', 'NGC 224', 'Gaia DR3 66526127137440128'. Mutually exclusive with `ra` and `dec`. An asteroid or a comet is refused rather than guessed at: this catalog stores no orbital elements for them, and only the Sun, the Moon and the eight planets have an ephemeris behind them.","schema":{"type":"string"},"example":"m31"},{"name":"ra","in":"query","required":false,"description":"Target right ascension in ICRS degrees, for something the catalog does not hold — a transient, a field centre, a target of opportunity. Requires `dec`.","schema":{"type":"number","minimum":0,"maximum":360}},{"name":"dec","in":"query","required":false,"description":"Target declination in ICRS degrees. Requires `ra`.","schema":{"type":"number","minimum":-90,"maximum":90}},{"name":"lat","in":"query","required":true,"description":"Observer latitude in degrees, north positive.","schema":{"type":"number","minimum":-90,"maximum":90},"example":"19.82"},{"name":"lon","in":"query","required":true,"description":"Observer longitude in degrees, east positive.","schema":{"type":"number","minimum":-180,"maximum":180},"example":"-155.47"},{"name":"elevation_m","in":"query","required":false,"description":"Observer height above sea level, in metres. It is not cosmetic: thinner air refracts less, so the same star rises four minutes later from the top of Mauna Kea than the sea-level figure says.","schema":{"type":"number","default":0,"minimum":-500,"maximum":9000}},{"name":"date","in":"query","required":false,"description":"Which night. A calendar date is the night that *begins* on it where the observer is, worked out from their longitude rather than from a timezone table; a full ISO 8601 instant is taken as given, and the night answered is the one whose solar midnight comes next. Defaults to tonight.","schema":{"type":"string"},"example":"2026-08-22"},{"name":"min_alt","in":"query","required":false,"description":"The altitude an observation counts from, in degrees. The default of 20 is the floor the site's own observing list is built at, so the two agree about what is up.","schema":{"type":"number","default":20,"minimum":-20,"maximum":89}},{"name":"window","in":"query","required":false,"description":"What the night is: `night` is sunset to sunrise, `24h` is a whole turn of the Earth centred on solar midnight. `24h` is forced where there is no sunset to bound the other one — a polar summer, a polar winter, or the Sun itself as the target.","schema":{"type":"string","enum":["night","24h"],"default":"night"}},{"name":"step_min","in":"query","required":false,"description":"Minutes between samples of the curve. Ten resolves an air-mass plot; one resolves a grazing occultation. The event times and the observable hours are solved for and do not depend on it.","schema":{"type":"integer","default":10,"minimum":1,"maximum":120}},{"name":"format","in":"query","required":false,"description":"Response shape. `json` is the full record, including the parts a table has no room for. `votable` is IVOA VOTable 1.4 with units and UCDs, which TOPCAT and Aladin open directly; `csv` is the same columns under the same names. Both flat forms drop the nested parts of a record — an object's properties, designations and source block — and keep the observable quantities.","schema":{"type":"string","enum":["json","votable","csv"],"default":"json"},"example":"votable"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ephemeris"}},"application/x-votable+xml":{"schema":{"type":"string","description":"The same rows flat, requested with format=votable."}},"text/csv":{"schema":{"type":"string","description":"The same rows flat, requested with format=csv."}}}},"400":{"description":"A parameter was missing or out of range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited — see the retry-after header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/resolve":{"get":{"operationId":"resolveIdentifier","summary":"Resolve any identifier","description":"What is this identifier? Answers across both tiers at once: a catalogued object where there is one, a survey source otherwise. `tier` says which — 'catalogued' carries a full object record under `object`, 'survey' carries a source record under `source`. Catalogued objects win any tie, because a named object with prose and cross-designations is the better answer than the survey row it was merged from. Every spelling resolves: 'M31', 'm 31', 'NGC 224', 'HD 48915', 'Gaia DR3 66526127137440128' and 'GLADE+ 1' are all identifiers this catalog can place.","parameters":[{"name":"id","in":"query","required":true,"description":"A designation, a slug, or a survey identifier. 120 characters or fewer.","schema":{"type":"string"},"example":"Gaia DR3 66526127137440128"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Resolution"}}}},"400":{"description":"A parameter was missing or out of range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited — see the retry-after header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/sources":{"get":{"operationId":"listSources","summary":"Survey sources by position","description":"Every survey source within a cone, nearest first. This is the tier the catalog stores and serves but does not index: rows of Gaia DR3 and GLADE+ as those surveys published them, with no article and no page in any search engine — so position and brightness are the only questions they can be asked, and the only ones this endpoint takes. One catalog per request: Gaia magnitudes are in G and GLADE+ magnitudes are in B, and mixing them would put two bands in one column ordered against each other. The radius is capped at one degree, which is not about query cost but about the answer: a degree of the galactic plane holds tens of thousands of Gaia sources brighter than G = 15. `truncated` says when the scan hit its own cap, which it takes brightest-first. The positions are each survey's own: GLADE+ publishes ICRS positions of galaxies, which do not move perceptibly, and Gaia DR3 publishes at epoch J2016.0 — so a cone centre taken from a J2000 catalogue is sixteen years of proper motion away from where Gaia sees the same star, which is a tenth of an arcsecond for most of them and minutes of arc for the fastest.","parameters":[{"name":"ra","in":"query","required":true,"description":"Cone centre, ICRS right ascension in degrees.","schema":{"type":"number","minimum":0,"maximum":360},"example":"266.4"},{"name":"dec","in":"query","required":true,"description":"Cone centre, ICRS declination in degrees.","schema":{"type":"number","minimum":-90,"maximum":90},"example":"-29"},{"name":"radius","in":"query","required":false,"description":"Cone radius in degrees.","schema":{"type":"number","default":0.1,"minimum":0.0001,"maximum":1}},{"name":"catalog","in":"query","required":false,"description":"Which survey to search: 'gaia-dr3' (stars, magnitudes in Gaia G) or 'glade' (galaxies and quasars, magnitudes in B).","schema":{"type":"string","default":"gaia-dr3"},"example":"glade"},{"name":"mag_max","in":"query","required":false,"description":"Faintest magnitude to return, in whichever band the chosen catalog publishes — Gaia G, a broad white-light band that is not V, or GLADE+'s photographic B. `meta.sort_band` says which was applied.","schema":{"type":"number","minimum":-30,"maximum":25}},{"name":"limit","in":"query","required":false,"description":"Maximum sources returned.","schema":{"type":"integer","default":50,"minimum":1,"maximum":500}},{"name":"format","in":"query","required":false,"description":"Response shape. `json` is the full record, including the parts a table has no room for. `votable` is IVOA VOTable 1.4 with units and UCDs, which TOPCAT and Aladin open directly; `csv` is the same columns under the same names. Both flat forms drop the nested parts of a record — an object's properties, designations and source block — and keep the observable quantities.","schema":{"type":"string","enum":["json","votable","csv"],"default":"json"},"example":"votable"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceList"}},"application/x-votable+xml":{"schema":{"type":"string","description":"The same rows flat, requested with format=votable."}},"text/csv":{"schema":{"type":"string","description":"The same rows flat, requested with format=csv."}}}},"400":{"description":"A parameter was missing or out of range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited — see the retry-after header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/sources/{id}":{"get":{"operationId":"getSource","summary":"Get one survey source","description":"One row of a sky survey, by its own identifier. Every spelling is accepted — 'gaia-dr3-66526127137440128', 'Gaia DR3 66526127137440128', 'Gaia+DR3+66526127137440128', 'glade-1', 'GLADE+ 1' — because a caller quoting the survey's printed form is quoting it correctly. `kind` says which record shape came back, star or galaxy, before any field is read. `in_catalog` says whether this row is also held as a catalogued object, in which case that object's page is the better answer.","parameters":[{"name":"id","in":"path","required":true,"description":"The survey identifier, in any spelling.","schema":{"type":"string"},"example":"gaia-dr3-66526127137440128"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceRecord"}}}},"400":{"description":"A parameter was missing or out of range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited — see the retry-after header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/scs/{table}":{"get":{"operationId":"coneSearch","summary":"Simple Cone Search (IVOA)","description":"The standard cone search, so the catalog can be opened in the tools astronomers already have: paste the base URL into TOPCAT or Aladin and the answer arrives as a layer on the sky. One service per table, which is what the standard means by one — 'objects' is the catalogued tier, 'gaia-dr3' and 'glade' are the surveys beneath it — because a cone search resource answers for a single table with a single set of columns. The response is always a VOTable, with the identifier, right ascension and declination carrying the UCDs a client is promised. Parameter names are matched without regard to case, and an invalid request comes back as HTTP 200 carrying a VOTable whose QUERY_STATUS is ERROR, which is where a conforming client looks for the reason. Where the scan reached its own cap before the cone was exhausted, an OVERFLOW status follows the table. The catalogued table's positions are J2000; the survey tables carry each survey's own epoch, and Gaia DR3's is J2016.0.","parameters":[{"name":"table","in":"path","required":true,"description":"Which table to search: 'objects' (the catalog, cones up to 10°), 'gaia-dr3' or 'glade' (the survey tier, cones up to 1°).","schema":{"type":"string"},"example":"objects"},{"name":"RA","in":"query","required":true,"description":"Cone centre, ICRS right ascension in decimal degrees.","schema":{"type":"number","minimum":0,"maximum":360},"example":"10.68"},{"name":"DEC","in":"query","required":true,"description":"Cone centre, ICRS declination in decimal degrees.","schema":{"type":"number","minimum":-90,"maximum":90},"example":"41.27"},{"name":"SR","in":"query","required":true,"description":"Search radius in decimal degrees. The ceiling is the table's: 10 for the catalog, 1 for a survey.","schema":{"type":"number","minimum":0,"maximum":10},"example":"0.5"},{"name":"VERB","in":"query","required":false,"description":"How many columns to return: 1 the identifier, the position and the separation; 2 the set worth having; 3 every column the table holds. An unrecognised value is treated as 2 rather than refused.","schema":{"type":"integer","default":2,"minimum":1,"maximum":3}},{"name":"MAXREC","in":"query","required":false,"description":"Maximum rows. Defaults to 1,000 for the catalog and 500 for a survey; an answer cut short says so with an OVERFLOW status after the table.","schema":{"type":"integer","minimum":1,"maximum":10000}}],"responses":{"200":{"description":"Success","content":{"application/x-votable+xml":{"schema":{"type":"string","description":"IVOA VOTable 1.4."}}}},"400":{"description":"A parameter was missing or out of range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited — see the retry-after header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/xmatch":{"post":{"operationId":"crossMatch","summary":"Cross-match a target list","description":"Send a list of positions and get back the nearest row to each of them, in the order they were sent. This is the question a cone search cannot be asked: an observing run produces a file of positions, and asking about them one at a time is a request per line. Every answer says how contested it was — how many rows fell inside the tolerance, how far the runner-up was, and how many unrelated rows the sky right there would be expected to put inside it anyway — because the nearest row within a few arcseconds is an identification only where the field is empty enough for it to be one. Targets that matched nothing keep their place in the list, so the answer still lines up with the file it came from. The body is JSON or a table; positions are decimal degrees, or sexagesimal, in which case the right ascension is in hours.","parameters":[{"name":"table","in":"query","required":false,"description":"Which table to match against: 'objects' (the catalog, tolerances up to 300″), 'gaia-dr3' or 'glade' (the survey tier, up to 60″).","schema":{"type":"string","default":"objects"},"example":"gaia-dr3"},{"name":"radius_arcsec","in":"query","required":false,"description":"Match tolerance in arcseconds. The default of 5 is the usual choice for optical positions; widen it for a list from a low-resolution instrument, and read `matches_within_radius` when you do.","schema":{"type":"number","default":5,"minimum":0.01,"maximum":300},"example":"3"},{"name":"epoch","in":"query","required":false,"description":"Carry the catalogue's positions to the epoch the target list is on before comparing, rather than after. A target list from a modern instrument is on that instrument's epoch and every catalogued position here is J2000, so a fast star can sit arcseconds from its own counterpart for no other reason. Takes `now`, a Julian year (`J2016.0` is Gaia's) or an ISO 8601 date. Only the catalogued tier can be propagated: the survey tables hold positions and no proper motions, and their rows are matched on the epoch they were published at.","schema":{"type":"string"},"example":"now"},{"name":"frame","in":"query","required":false,"description":"Which frame `epoch` propagates into, and meaningless without it. `icrs` applies the object's own proper motion and nothing else — a position epoch, the sense Gaia uses, and the one to cross-match in. `date` also turns the coordinate grid to the true equator and equinox of that instant — precession plus nutation — which is what a telescope mount expects and is about fifty arcseconds a year larger.","schema":{"type":"string","enum":["icrs","date"],"default":"icrs"},"example":"date"},{"name":"format","in":"query","required":false,"description":"Response shape. `json` is the full record, including the parts a table has no room for. `votable` is IVOA VOTable 1.4 with units and UCDs, which TOPCAT and Aladin open directly; `csv` is the same columns under the same names. Both flat forms drop the nested parts of a record — an object's properties, designations and source block — and keep the observable quantities.","schema":{"type":"string","enum":["json","votable","csv"],"default":"json"},"example":"votable"}],"requestBody":{"required":true,"description":"The target list, as JSON — `{\"targets\": [{\"id\": \"a\", \"ra\": 10.6847, \"dec\": 41.2687}]}`, or a bare array of those — or as a table with one target per line. A table may be comma, tab, semicolon or whitespace separated; a first line naming its columns is read for `ra`, `dec` and an identifier, and without one a row is `ra,dec` or `id,ra,dec`. Lines beginning with `#` are comments. A row that cannot be read is an error naming the row rather than a row quietly dropped, because a list of answers only lines up with the list of questions if nothing went missing between them. 500 targets per request.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"targets":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","description":"The caller's own label for the row."},"ra":{"type":["number","string"],"description":"Right ascension. A number is degrees; text may be sexagesimal — '00 42 44.3', '00:42:44.3' — in which case it is hours."},"dec":{"type":["number","string"],"description":"Declination, degrees or sexagesimal."}},"required":["ra","dec"]},{"type":"array","description":"[ra, dec] or [id, ra, dec].","items":{"type":["number","string"]}},{"type":"string","description":"A position as one line: '10.6847 41.2687'."}]}}},"required":["targets"]},{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","description":"The caller's own label for the row."},"ra":{"type":["number","string"],"description":"Right ascension. A number is degrees; text may be sexagesimal — '00 42 44.3', '00:42:44.3' — in which case it is hours."},"dec":{"type":["number","string"],"description":"Declination, degrees or sexagesimal."}},"required":["ra","dec"]},{"type":"array","description":"[ra, dec] or [id, ra, dec].","items":{"type":["number","string"]}},{"type":"string","description":"A position as one line: '10.6847 41.2687'."}]}}]},"example":{"targets":[{"id":"field-1","ra":10.6847,"dec":41.2687},{"id":"field-2","ra":83.8221,"dec":-5.3911},{"id":"field-3","ra":201.365,"dec":-43.019}]}},"text/csv":{"schema":{"type":"string"}},"text/plain":{"schema":{"type":"string"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrossMatch"}},"application/x-votable+xml":{"schema":{"type":"string","description":"The same rows flat, requested with format=votable."}},"text/csv":{"schema":{"type":"string","description":"The same rows flat, requested with format=csv."}}}},"400":{"description":"A parameter was missing or out of range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited — see the retry-after header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"ObjectSummary":{"type":"object","properties":{"slug":{"type":"string","description":"Stable identifier, also the site URL segment."},"name":{"type":"string"},"class":{"type":"string","description":"Machine-readable class: the object's own type where one is recorded, its category otherwise. 'Supermassive black hole' becomes supermassive_black_hole."},"category":{"type":"string","enum":["star","planet","moon","exoplanet","galaxy","nebula","cluster","black_hole","asteroid","comet","other"]},"object_type":{"type":["string","null"],"description":"Free-text class as the source catalog records it."},"mag":{"type":["number","null"],"description":"Apparent magnitude of this object — lower is brighter. Null where the object has none: an exoplanet is not visible, and a small body's brightness depends on where it is."},"mag_band":{"type":["string","null"],"description":"Passband mag was measured in: 'V' (Johnson visual) or 'B' (photographic blue). The two differ by more than a magnitude on a red object, so they are not comparable without this."},"abs_mag":{"type":["number","null"],"description":"Absolute magnitude of this object. See abs_mag_band for which definition."},"abs_mag_band":{"type":["string","null"],"description":"'V' for a star's absolute visual magnitude, 'H' for a small body's absolute magnitude, which is defined at one AU from both Sun and Earth. The two are not comparable."},"distance_ly":{"type":["number","null"],"description":"Distance from Earth."},"ra_deg":{"type":["number","null"],"description":"ICRS/J2000 right ascension in degrees. Null for a body with no fixed place — a planet, a moon, an asteroid or a comet is somewhere different tonight, and /api/v1/visible computes where."},"dec_deg":{"type":["number","null"],"description":"ICRS/J2000 declination in degrees."},"pm_ra_mas_yr":{"type":["number","null"],"description":"Proper motion in right ascension, milliarcseconds a year, as μα cos δ — an angle on the sky, not a rate of change of right ascension. The two differ by 1/cos δ, a factor of ten ten degrees from the pole. Null where the upstream published none, which is not the same as a motion of zero."},"pm_dec_mas_yr":{"type":["number","null"],"description":"Proper motion in declination, milliarcseconds a year."},"epoch_ra_deg":{"type":["number","null"],"description":"Right ascension at the epoch asked for, in the frame the response's epoch block names. Present only on a request that sent `epoch`."},"epoch_dec_deg":{"type":["number","null"],"description":"Declination at that epoch, in that frame."},"epoch_moved_arcsec":{"type":["number","null"],"description":"How far the object itself travelled between J2000 and that epoch, in arcseconds — proper motion only, so it is the same number in either frame and precession is not in it. Null where no proper motion is published."},"distance_method":{"type":["string","null"],"description":"Where distance_ly came from, said rather than assumed: 'parallax', 'definition', 'redshift (CMB frame), flat ΛCDM with H0 = 70 km/s/Mpc' — whose ±4% expansion-rate systematic and unmodelled peculiar motion are in properties.uncertainties.distance_ly — 'luminosity distance from a photometric redshift (GLADE+), flat ΛCDM with H0 = 70 km/s/Mpc', which is good to about a fifth of itself and says so in that same error bar, or the upstream column and the paper it names, 'NASA Exoplanet Archive sy_dist (TICv8, 2019AJ....158..138S)'. Every redshift distance here divides by the same H0 whichever upstream supplied the redshift: where a source published distances under a different one, the conversion was re-run rather than the number copied."},"orbits":{"type":["string","null"],"description":"The body this object orbits: 'Sun' for a planet, comet or asteroid, the parent planet for a moon, the host star for an exoplanet."},"semi_major_axis_km":{"type":["number","null"],"description":"Semi-major axis of the orbit about `orbits`, in kilometres. Negative on a hyperbolic orbit, where it is an orbital element and not a distance."},"periapsis_km":{"type":["number","null"],"description":"Closest approach to `orbits`, in kilometres — the only distance an unbound body has."},"mass_kg":{"type":["number","null"]},"mass_msun":{"type":["number","null"],"description":"Derived from mass_kg, six significant digits."},"constellation":{"type":["string","null"]},"discovered":{"type":["string","null"],"description":"A year, or a word like 'Antiquity'."},"featured":{"type":"boolean","description":"Has a hand-written description."},"url":{"type":"string","format":"uri"}},"required":["slug","name","class","category","url"]},"StarSource":{"type":"object","description":"A Gaia DR3 row: a star, with a parallax and a colour index.","properties":{"id":{"type":"string","description":"Canonical identifier, also the site URL segment: gaia-dr3-66526127137440128, glade-1. Computed from the survey's own key and stored nowhere."},"catalog":{"type":"string","description":"The survey: 'Gaia DR3' or 'GLADE+'."},"designation":{"type":"string","description":"As the survey writes it: 'Gaia DR3 66526127137440128', 'GLADE+ 1'."},"source_id":{"type":"string","description":"The survey's primary key, as text. Gaia identifiers run past 2⁵³, where a JSON number silently loses digits; both surveys are given as text so one field has one type."},"ra_deg":{"type":"number","description":"J2000 right ascension in degrees."},"dec_deg":{"type":"number","description":"J2000 declination in degrees."},"mag":{"type":["number","null"],"description":"Apparent magnitude in the band named by mag_band, and null where the survey publishes none."},"distance_ly":{"type":["number","null"],"description":"Distance in light years, or null where the row carries nothing that yields one. Always read distance_method beside it."},"distance_method":{"type":["string","null"],"description":"The arithmetic behind distance_ly, stated rather than assumed — an inverted parallax with no error term, or which of GLADE+'s three kinds of redshift or published distance the row carries. Where a GLADE+ redshift was converted, this catalogue did the converting and the string names what it divided by; a GLADE+ distance that was measured rather than converted names no cosmology, because there is none in it."},"in_catalog":{"type":"boolean","description":"True where this row is also held as a catalogued object, in which case that object's page carries far more."},"url":{"type":"string","format":"uri"},"kind":{"type":"string","enum":["star"]},"mag_band":{"type":"string","enum":["Gaia G"],"description":"'Gaia G' — a broad white-light band covering most of the visible spectrum. It is not V and does not convert to it."},"color_bp_rp":{"type":["number","null"],"description":"Gaia BP−RP colour index. Null where one of the two bands has no photometry. Not B−V."},"parallax_mas":{"type":["number","null"],"description":"Parallax in milliarcseconds, as published. May be negative: that is a real measurement of a distant star, not an error."}},"required":["id","catalog","kind","source_id","ra_deg","dec_deg","url"]},"GalaxySource":{"type":"object","description":"A GLADE+ row: a galaxy or a quasar, with a redshift, a luminosity distance and — often — somebody else's name for it.","properties":{"id":{"type":"string","description":"Canonical identifier, also the site URL segment: gaia-dr3-66526127137440128, glade-1. Computed from the survey's own key and stored nowhere."},"catalog":{"type":"string","description":"The survey: 'Gaia DR3' or 'GLADE+'."},"designation":{"type":"string","description":"As the survey writes it: 'Gaia DR3 66526127137440128', 'GLADE+ 1'."},"source_id":{"type":"string","description":"The survey's primary key, as text. Gaia identifiers run past 2⁵³, where a JSON number silently loses digits; both surveys are given as text so one field has one type."},"ra_deg":{"type":"number","description":"J2000 right ascension in degrees."},"dec_deg":{"type":"number","description":"J2000 declination in degrees."},"mag":{"type":["number","null"],"description":"Apparent magnitude in the band named by mag_band, and null where the survey publishes none."},"distance_ly":{"type":["number","null"],"description":"Distance in light years, or null where the row carries nothing that yields one. Always read distance_method beside it."},"distance_method":{"type":["string","null"],"description":"The arithmetic behind distance_ly, stated rather than assumed — an inverted parallax with no error term, or which of GLADE+'s three kinds of redshift or published distance the row carries. Where a GLADE+ redshift was converted, this catalogue did the converting and the string names what it divided by; a GLADE+ distance that was measured rather than converted names no cosmology, because there is none in it."},"in_catalog":{"type":"boolean","description":"True where this row is also held as a catalogued object, in which case that object's page carries far more."},"url":{"type":"string","format":"uri"},"kind":{"type":"string","enum":["galaxy"]},"mag_band":{"type":["string","null"],"enum":["B","K",null],"description":"Which band mag is in. 'B' where the row has an apparent B magnitude, 'K' where it has only the 2MASS K, null where it has neither. The two are about two magnitudes apart on an ordinary galaxy, so this is never safe to assume."},"object_type":{"type":"string","enum":["galaxy","quasar"],"description":"GLADE+'s own Type flag. 'quasar' means the row came from SDSS-DR16Q; nothing here is inferred from colours or magnitudes."},"mag_b":{"type":["number","null"],"description":"Apparent B, where measured."},"mag_k":{"type":["number","null"],"description":"Apparent K from 2MASS."},"redshift_cmb":{"type":["number","null"],"description":"Redshift in the CMB frame, as GLADE+ publishes it — and, where distance_flag is 1 or 3, the number distance_ly was computed from."},"distance_mpc":{"type":["number","null"],"description":"GLADE+'s own luminosity distance in megaparsecs, exactly as published and therefore under its cosmology rather than this catalogue's: astropy's Planck18, H0 = 67.66 and Ωm = 0.30966, measured against its published redshifts because its ReadMe names none. It is 3.5% larger than distance_ly wherever that was derived from a redshift, because distance_ly divides by H0 = 70 like every other distance this API serves. Here so that a caller who wants GLADE+'s own number has it; use distance_ly to compare a row with anything else in this catalogue."},"distance_flag":{"type":["integer","null"],"enum":[0,1,2,3,null],"description":"Which of GLADE+'s three distances this is, as the number distance_method spells out: 1 a photometric redshift, 2 a luminosity distance somebody else measured, 3 a spectroscopic redshift, 0 neither. Worth filtering on: GLADE+ gives a photometric redshift a standard deviation of 20% of itself and a spectroscopic one 2.9%, so the two classes are not comparable at the precision the numbers are printed to."},"pgc":{"type":["integer","null"],"description":"Principal Galaxies Catalogue number, which HyperLEDA, NED and SIMBAD all resolve. Absent from most of GLADE+."},"hyperleda":{"type":["string","null"],"description":"The HyperLEDA name. Sometimes a real name ('NGC4736'), sometimes a bare number."},"sdss_dr16q":{"type":["string","null"],"description":"The SDSS-DR16Q name, which is what identity a quasar row has."}},"required":["id","catalog","kind","source_id","ra_deg","dec_deg","url"]},"SourceRecord":{"oneOf":[{"$ref":"#/components/schemas/StarSource"},{"$ref":"#/components/schemas/GalaxySource"}],"discriminator":{"propertyName":"kind","mapping":{"star":"#/components/schemas/StarSource","galaxy":"#/components/schemas/GalaxySource"}}},"SourceList":{"type":"object","properties":{"meta":{"type":"object","properties":{"ra_deg":{"type":"number"},"dec_deg":{"type":"number"},"radius_deg":{"type":"number"},"mag_max":{"type":["number","null"]},"limit":{"type":"integer"},"count":{"type":"integer"},"catalog":{"type":"string","enum":["gaia-dr3","glade"]},"catalog_name":{"type":"string"},"sort_band":{"type":"string","description":"The band mag_max was applied in and the list is ordered by. It changes with catalog, so it is stated per request. It is not necessarily the band a given record's mag is in — a GLADE+ row with no B falls back to 2MASS K, and every record names its own band."},"truncated":{"type":"boolean","description":"True where the scan hit its own cap before the cone was exhausted. The cap is taken brightest-first, so a truncated answer is the top of the list rather than a slice of it."},"tier":{"type":"string","enum":["survey"],"description":"Always 'survey'. Nothing in this response has been merged, named or checked against another catalog."}}},"release":{"$ref":"#/components/schemas/Release"},"attribution":{"type":"string"},"sources":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/SourceRecord"},{"type":"object","properties":{"separation_arcsec":{"type":"number","description":"Great-circle distance from the cone centre."}}}]}}}},"Resolution":{"type":"object","properties":{"query":{"type":"string","description":"The identifier as it was given."},"tier":{"type":"string","enum":["catalogued","survey"],"description":"Which tier answered, and therefore which of `object` and `source` is present."},"matched":{"type":["string","null"],"description":"The designation that caused a catalogued hit, when one did. Null for a slug or a survey identifier."},"object":{"description":"Present when tier is 'catalogued'.","$ref":"#/components/schemas/ObjectDetail"},"source":{"description":"Present when tier is 'survey'.","$ref":"#/components/schemas/SourceRecord"},"release":{"$ref":"#/components/schemas/Release"},"attribution":{"type":"string"}},"required":["query","tier"]},"ObjectDetail":{"allOf":[{"$ref":"#/components/schemas/ObjectSummary"},{"type":"object","properties":{"radius_km":{"type":["number","null"]},"radius_kind":{"type":["string","null"],"description":"Which radius radius_km is: 'mean', 'equatorial', or 'effective' (the radius of a sphere with the same projected area). Null where the source does not say."},"description":{"type":["string","null"]},"properties":{"type":"object","additionalProperties":true,"description":"Source-specific extras: spectral type, orbital elements, redshift. Keys vary by catalog."},"designations":{"type":"array","items":{"type":"object","properties":{"catalog":{"type":"string"},"designation":{"type":"string"}}}},"source":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string","format":"uri"},"license":{"type":"string"}}},"updated_at":{"type":["string","null"],"format":"date-time"},"release":{"$ref":"#/components/schemas/Release"},"epoch":{"$ref":"#/components/schemas/Epoch"},"variability":{"$ref":"#/components/schemas/Variability"},"attribution":{"type":"string"}}}]},"ObjectSpectrum":{"type":"object","description":"One spectrum, resampled onto a log-spaced wavelength grid for display.","properties":{"slug":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["observed","representative"],"description":"'observed' is this object's own light. 'representative' is the average spectrum of stars of its type, and is not a measurement of this object."},"of":{"type":"string","description":"What these numbers are, in a sentence."},"template":{"type":["string","null"],"description":"The atlas key a representative spectrum was stored under."},"template_label":{"type":["string","null"],"description":"That key as a spectral type: 'A0 V'."},"approximate":{"type":"boolean","description":"True when the atlas holds no spectrum for this exact type and the nearest one was returned instead."},"source":{"type":"string","description":"Provenance registry id."},"identifier":{"type":"string","description":"The exposure in the archive it came from, or the atlas key."},"data_release":{"type":"string"},"observed_on":{"type":["string","null"],"format":"date","description":"The night of the exposure. Null for an atlas average."},"redshift":{"type":["number","null"],"description":"The survey's own redshift for this target, so a rest-frame line list can be shifted onto the axis."},"separation_arcsec":{"type":["number","null"],"description":"How far the fibre was from the catalog position."},"wavelength_min_angstrom":{"type":"number"},"wavelength_max_angstrom":{"type":"number"},"wavelength_frame":{"type":"string","description":"Air wavelengths, as observed rather than as emitted."},"sample_count":{"type":"integer"},"flux_unit":{"type":"string"},"resolution_note":{"type":"string","description":"The aperture, the resolving power, and what the resampling did."},"samples":{"type":"array","items":{"type":"object","properties":{"wavelength_angstrom":{"type":"number"},"flux":{"type":"number"}}}},"release":{"$ref":"#/components/schemas/Release"},"attribution":{"type":"string"}},"required":["slug","kind","samples"]},"Release":{"type":"object","description":"The frozen, versioned state of the catalog these rows belong to. Quote it alongside any number taken from this response: the site is corrected continuously and a release is not.","properties":{"id":{"type":"string","description":"'DR1', 'DR2'…"},"released_on":{"type":"string","format":"date"},"doi":{"type":["string","null"],"description":"Null until the release bundle has been deposited somewhere that mints one."},"url":{"type":"string","format":"uri","description":"Where the release, its counts and its licences are described."}}},"Epoch":{"type":"object","description":"The epoch these positions were carried to, and what that involved. Quote it with any propagated coordinate: 'of date' means at least four different things depending on which terms are in it.","properties":{"requested":{"type":"string","description":"The `epoch` value as it was sent."},"label":{"type":"string","description":"That epoch as an astronomer writes it: 'J2026.641'."},"julian_year":{"type":"number"},"time":{"type":"string","format":"date-time","description":"The same instant, in UTC."},"years_from_j2000":{"type":"number"},"frame":{"type":"string","enum":["icrs","date"]},"applied":{"type":"string","description":"Which terms went into the propagated position."},"excluded":{"type":"string","description":"Which did not, and what each would be worth."}}},"Variability":{"type":"object","description":"The star's variability elements, from the General Catalogue of Variable Stars, and — on a request that sent `epoch` — where in its cycle it is at that instant. Present only for stars that catalog lists.","properties":{"type":{"type":["string","null"],"description":"The catalog's type code, compound and verbatim: 'EA/SD' is an Algol-type eclipsing binary that is also semi-detached, and a trailing colon means the classification is uncertain."},"class":{"type":["string","null"],"description":"The leading term of that code in English. The rest stays in `type`."},"period_days":{"type":["number","null"],"description":"Length of one cycle. For an eruptive, irregular or semiregular variable this is a mean cycle time rather than an ephemeris, and no phase is computed from it."},"epoch_hjd":{"type":["number","null"],"description":"Heliocentric Julian date of an observed event — referred to the centre of the Sun rather than to where the Earth was that night, a difference of up to 8.3 minutes."},"epoch_marks":{"type":"string","enum":["minimum","maximum"],"description":"Which event epoch_hjd is, and therefore what phase 0 means: minimum light for eclipsing and ellipsoidal variables and for the RV Tauri and RS Canum Venaticorum types, maximum for every other class."},"mag_brightest":{"type":["number","null"],"description":"Magnitude at the bright end of the range, as sampled by Hipparcos and converted to the visual scale. Approximate: for a star that spends most of its cycle out of eclipse, the satellite may never have measured the bottom of the dip."},"mag_faintest":{"type":["number","null"],"description":"The other end of that range."},"phase":{"$ref":"#/components/schemas/Phase"}}},"Phase":{"type":"object","description":"Where in its cycle the star is at the instant `epoch` named, and when the next events fall. A phase belongs to a moment, so it is computed for the moment the caller asked about rather than for whenever the response was generated.","properties":{"at":{"type":"string","format":"date-time","description":"The instant it is for."},"at_hjd":{"type":"number","description":"The same instant as a heliocentric Julian date, which is the epoch's own scale."},"event":{"type":"string","enum":["minimum","maximum"]},"value":{"type":["number","null"],"description":"0 at that event, 0.5 half a cycle later. Null when `unavailable` says why not."},"uncertainty":{"type":["number","null"],"description":"Half-width of the phase, in cycles: the published precision of the period carried through every cycle since the epoch, against that of the epoch itself. Past a quarter of a cycle the phase is withheld rather than printed."},"uncertainty_days":{"type":["number","null"],"description":"The same figure as a time."},"cycles_since_epoch":{"type":["number","null"]},"next":{"type":"array","items":{"type":"string","format":"date-time"},"description":"The coming events, soonest first — up to three, and no further ahead than a week after the first."},"unavailable":{"type":["string","null"],"description":"Why there is no phase: no period, no epoch, a class whose period is a mean cycle time, or elements whose last digit has compounded past a quarter of a cycle. Null where there is one."},"applied":{"type":"string","description":"What went into the phase."},"excluded":{"type":"string","description":"What did not, and what it would be worth."}}},"ObjectList":{"type":"object","properties":{"meta":{"type":"object","properties":{"total":{"type":"integer","description":"Objects matching the filters."},"count":{"type":"integer","description":"Objects in this page."},"limit":{"type":"integer"},"offset":{"type":"integer"},"sort":{"type":"string"},"order":{"type":"string"},"next":{"type":["string","null"],"format":"uri","description":"The next page, or null."}}},"release":{"$ref":"#/components/schemas/Release"},"epoch":{"$ref":"#/components/schemas/Epoch"},"attribution":{"type":"string"},"objects":{"type":"array","items":{"$ref":"#/components/schemas/ObjectSummary"}}}},"SearchResults":{"type":"object","properties":{"meta":{"type":"object","properties":{"query":{"type":"string"},"count":{"type":"integer","description":"Catalogued results only."},"limit":{"type":"integer"},"searched":{"type":"array","items":{"type":"string","enum":["catalogued","survey"]},"description":"Which tiers this query reached. The survey tier is searched only when the query is a survey identifier — a row named after its own coordinates has no name to match and no prose to rank."}}},"release":{"$ref":"#/components/schemas/Release"},"attribution":{"type":"string"},"results":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/ObjectSummary"},{"type":"object","properties":{"tier":{"type":"string","enum":["catalogued"]},"matched":{"type":["string","null"],"description":"The designation that caused the hit, when one did."}}}]}},"sources":{"type":"array","description":"Survey-tier hits, empty unless the query was a survey identifier. A separate array rather than a mixed list, because the two records have different shapes.","items":{"$ref":"#/components/schemas/SourceRecord"}}}},"EventList":{"type":"object","properties":{"release":{"$ref":"#/components/schemas/Release"},"meta":{"type":"object","properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"count":{"type":"integer"},"limit":{"type":"integer"},"kinds":{"type":"array","items":{"type":"string"},"description":"The kinds this answer was restricted to, or all of them."},"close_approaches":{"type":"object","description":"What the flyby part of the answer is, and is not. The other seven kinds are computed and need no such note.","properties":{"source":{"type":"string"},"fetched":{"type":"string","format":"date"},"covers_through":{"type":"string","format":"date","description":"No flyby after this date is in the answer, whether or not one happens."},"max_distance_ld":{"type":"number","description":"Passes further away than this are not listed."}}}}},"attribution":{"type":"string"},"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier: kind, subject and the day it falls on."},"kind":{"type":"string","enum":["moon","season","opposition","elongation","conjunction","eclipse","shower","flyby"]},"time":{"type":"string","format":"date-time","description":"The instant it happens, UTC — the peak of an eclipse, the maximum of a shower, the moment of closest approach."},"window":{"type":"object","description":"Where the event is a season rather than a moment. Meteor showers only.","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}}},"title":{"type":"string"},"description":{"type":"string","description":"What it is and why it is worth knowing, in plain language."},"summary":{"type":"string","description":"The same in one clause."},"objects":{"type":"array","items":{"type":"string"},"description":"Catalog slugs of the bodies involved, resolvable at /api/v1/objects/{slug}. Empty for a flyby by a body this catalog does not hold — most of them, since the catalog stops at absolute magnitude 18 and most close passes are fainter."},"position":{"type":"object","description":"Where to look, geocentric ICRS/J2000. Absent where the event has no one place — a new moon is where the Sun is, and the equinox is not anywhere.","properties":{"ra_deg":{"type":"number"},"dec_deg":{"type":"number"}}},"circumstances":{"type":"object","description":"The numbers this kind of event has, and only those. `separation_deg` and `elongation_deg` for a pairing; `obscuration`, `duration_min` and `greatest_at` for an eclipse; `zhr`, `speed_km_s`, `moon_illumination` and `moon_phase_deg` for a shower; `distance_ld`, `speed_km_s`, `magnitude` and `diameter_km` for a flyby. The two lunar figures are on the shower's peak night and are the ones that decide whether the rate beside them means anything: a bright Moon hides all but the brightest meteors, and the phase says which half of the night it is up for.","additionalProperties":true},"url":{"type":"string","format":"uri"}}}}}},"VisibleList":{"type":"object","properties":{"observer":{"type":"object","description":"The position actually used, after rounding.","properties":{"lat":{"type":"number"},"lon":{"type":"number"},"elevation_m":{"type":"number"}}},"time":{"type":"string","format":"date-time","description":"The instant used, after rounding."},"local_sidereal_deg":{"type":"number","description":"Right ascension on the meridian."},"sun":{"type":"object","properties":{"altitude_deg":{"type":"number"},"condition":{"type":"string","enum":["daylight","civil twilight","nautical twilight","astronomical twilight","night"]}}},"meta":{"type":"object","properties":{"min_altitude_deg":{"type":"number"},"count":{"type":"integer"},"above_horizon":{"type":"integer","description":"Matches before the limit was applied."},"limit":{"type":"integer"},"precision":{"type":"string"}}},"release":{"$ref":"#/components/schemas/Release"},"attribution":{"type":"string"},"objects":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/ObjectSummary"},{"type":"object","properties":{"ra_deg":{"type":"number","description":"Right ascension of date, in degrees — not J2000. Catalogued positions are carried forward by their proper motion and then precessed to the requested instant, so that they and the ephemeris bodies share one frame."},"dec_deg":{"type":"number","description":"Declination of date, in degrees."},"altitude_deg":{"type":"number","description":"Geometric altitude above the horizon; no refraction term."},"azimuth_deg":{"type":"number","description":"From north, through east."},"direction":{"type":"string","description":"Sixteen-point compass bearing."},"airmass":{"type":"number","description":"Thicknesses of atmosphere in the line of sight, 1 being straight overhead (Kasten & Young 1989)."},"mag_at_altitude":{"type":"number","description":"The magnitude this would be seen at from the ground: `mag` plus 0.2 magnitudes per air mass of extinction, counted relative to the zenith. Null where the object has no magnitude. This is the field the list is sorted on."},"ephemeris":{"type":"boolean","description":"True when the position was computed for this instant rather than catalogued."},"distance_au":{"type":"number","description":"Solar-system objects only."},"proper_motion_arcsec":{"type":"number","description":"How far this star has moved from its catalogued J2000 position by the requested instant, in arcseconds. Absent where no proper motion is recorded, or where it comes to less than a tenth of an arcsecond."},"size_arcmin":{"type":"number","description":"Major axis on the sky in arcminutes, for extended objects that have a measured one — what an eyepiece field of view has to cover."}}}]}}}},"Ephemeris":{"type":"object","properties":{"release":{"$ref":"#/components/schemas/Release"},"target":{"type":"object","description":"What was observed, and where its position came from.","properties":{"kind":{"type":"string","enum":["catalogued","ephemeris","survey","position"],"description":"'catalogued' is a stored J2000 position, 'ephemeris' one of the nine bodies computed for the instant, 'survey' a Gaia or GLADE+ row, 'position' the coordinates you sent."},"slug":{"type":["string","null"]},"name":{"type":"string"},"category":{"type":["string","null"]},"object_type":{"type":["string","null"]},"mag":{"type":["number","null"]},"mag_band":{"type":["string","null"]},"ra_deg":{"type":["number","null"],"description":"The stored position, unchanged. Null for an ephemeris body, which has no stored one."},"dec_deg":{"type":["number","null"]},"position_epoch":{"type":["string","null"],"description":"The epoch the stored position is on: J2000.0 for the catalogue, J2016.0 for a Gaia row."},"pm_ra_mas_yr":{"type":["number","null"]},"pm_dec_mas_yr":{"type":["number","null"]},"epoch_ra_deg":{"type":"number","description":"Where the object's own proper motion puts it on the night computed — which is the position everything below was worked out from. Absent where none is published."},"epoch_dec_deg":{"type":"number"},"epoch_moved_arcsec":{"type":"number","description":"How far it has travelled from the stored position, in arcseconds."}}},"observer":{"type":"object","description":"The position used, exactly as sent — nothing is rounded here.","properties":{"lat":{"type":"number"},"lon":{"type":"number"},"elevation_m":{"type":"number"}}},"night":{"type":"object","description":"What the Sun does around the solar midnight the night is centred on.","properties":{"solar_midnight":{"type":"string","format":"date-time"},"sunset":{"type":["string","null"],"format":"date-time"},"sunrise":{"type":["string","null"],"format":"date-time"},"dark_start":{"type":["string","null"],"format":"date-time","description":"The Sun descending through 18° below the horizon."},"dark_end":{"type":["string","null"],"format":"date-time"},"never_dark":{"type":"boolean","description":"The Sun never gets 18° down: twilight from dusk to dawn."},"always_dark":{"type":"boolean","description":"The Sun stays 18° down for the whole day: polar night."},"never_sets":{"type":"boolean","description":"Polar day. No night at all."},"never_rises":{"type":"boolean","description":"Polar night. The opposite fact to never_sets, and not the same as it — both come back from the search as a missing sunset, and which one it is has to be read off the Sun's altitude."},"dark_hours":{"type":"number","description":"Hours of astronomical darkness inside the window."}}},"window":{"type":"object","description":"The interval everything below is computed over.","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"},"hours":{"type":"number"},"span":{"type":"string","enum":["night","24h"]},"note":{"type":"string","description":"Why the window is the one it is."}}},"events":{"type":"object","properties":{"rise":{"type":["string","null"],"format":"date-time","description":"Null where the target does not rise inside the window — which happens both when it was already up and when it never comes up. circumpolar, never_rises and up_at_window_start say which."},"set":{"type":["string","null"],"format":"date-time"},"transit":{"type":["string","null"],"format":"date-time","description":"The first upper culmination at or after the window opens."},"transit_altitude_deg":{"type":["number","null"]},"transit_airmass":{"type":["number","null"],"description":"Null where the culmination is below the horizon."},"circumpolar":{"type":"boolean","description":"Never sets from this latitude."},"never_rises":{"type":"boolean"},"up_at_window_start":{"type":"boolean"},"horizon_altitude_deg":{"type":"number","description":"The geometric altitude a rise and a set were measured at: the horizon lifted by 34 arcminutes of refraction, scaled by the density of the air at the observer's elevation. About -0.567° at sea level and -0.37° on a high mountain."}}},"observability":{"type":"object","properties":{"min_altitude_deg":{"type":"number"},"hours_above_min_alt":{"type":"number","description":"Above the floor at any point in the window, dark or not."},"hours_observable":{"type":"number","description":"Above the floor and the Sun more than 18° down. This is the number an observing plan is made on. Solved for rather than counted off the samples, so step_min does not change it."},"windows":{"type":"array","description":"The intervals those hours are made of.","items":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"},"hours":{"type":"number"}}}},"best":{"type":["object","null"],"description":"The highest the target gets while it is both dark and above the floor — not simply the transit, which may fall in daylight. Null where there is no such moment.","properties":{"time":{"type":"string","format":"date-time"},"altitude_deg":{"type":"number"},"airmass":{"type":"number"},"mag_at_altitude":{"type":["number","null"]},"moon_separation_deg":{"type":["number","null"]}}}}},"moon":{"type":"object","description":"The one thing most likely to make the rest of this wrong: a full Moon fifty degrees up puts several magnitudes of sky glow behind every faint target on the list.","properties":{"phase_deg":{"type":"number","description":"0 new, 90 first quarter, 180 full."},"phase_name":{"type":"string"},"illumination":{"type":"number","description":"Fraction of the disc lit at solar midnight, 0 to 1."},"altitude_deg":{"type":"number","description":"At solar midnight."},"up":{"type":"boolean"},"up_hours":{"type":"number","description":"Hours above the horizon inside the window."},"separation_deg":{"type":["number","null"],"description":"Angle from the target at solar midnight. Null where the target is the Moon."},"separation_min_deg":{"type":["number","null"]},"separation_max_deg":{"type":["number","null"]}}},"meta":{"type":"object","properties":{"step_minutes":{"type":"integer"},"samples":{"type":"integer"},"conventions":{"type":"string","description":"Which altitude is refracted and which is geometric, spelled out — the two differ by half a degree at the horizon and every wrong answer in this endpoint would look like a right one."},"extinction":{"type":"string"}}},"attribution":{"type":"string"},"track":{"type":"array","description":"The curve: one row per instant across the window. This is what the CSV and VOTable forms of the endpoint return, because an air-mass curve is a table before it is a picture.","items":{"type":"object","properties":{"time":{"type":"string","format":"date-time"},"altitude_deg":{"type":"number","description":"Geometric altitude of the target's centre; no refraction in it."},"azimuth_deg":{"type":"number"},"direction":{"type":"string"},"airmass":{"type":["number","null"],"description":"Null below the horizon, where the quantity has no value."},"mag_at_altitude":{"type":["number","null"]},"sun_altitude_deg":{"type":"number"},"sky":{"type":"string","enum":["daylight","civil twilight","nautical twilight","astronomical twilight","night"]},"moon_altitude_deg":{"type":"number"},"moon_separation_deg":{"type":["number","null"]}}}}}},"CrossMatch":{"type":"object","properties":{"release":{"$ref":"#/components/schemas/Release"},"epoch":{"$ref":"#/components/schemas/Epoch"},"meta":{"type":"object","properties":{"table":{"type":"string","description":"Which table was matched against."},"table_name":{"type":"string"},"position_epoch":{"type":"string","description":"The epoch the matched table's positions are on. J2000.0 for the catalog; Gaia DR3 publishes at J2016.0 and is served as published, so a J2000 target list is being compared across sixteen years of proper motion."},"radius_arcsec":{"type":"number","description":"The tolerance that was applied."},"background_arcsec":{"type":"number","description":"Outer radius of the annulus the local surface density behind each match was counted in."},"targets":{"type":"integer"},"matched":{"type":"integer"},"unmatched":{"type":"integer"},"ambiguous":{"type":"integer","description":"Targets with more than one row inside the tolerance. The nearest is reported, and nothing about being nearest makes it right."},"truncated":{"type":"boolean","description":"True where at least one target sits in a field so crowded the scan reached its own cap before reading the sky around it; that target's count of rivals is a floor rather than a total."}}},"attribution":{"type":"string"},"matches":{"type":"array","description":"One entry per target, in the order the targets were sent.","items":{"type":"object","properties":{"target":{"type":"object","description":"The target as it was read, which is what to check a surprise against.","properties":{"row":{"type":"integer","description":"Position in the list as sent, counting from one."},"id":{"type":["string","null"]},"ra_deg":{"type":"number"},"dec_deg":{"type":"number"}}},"separation_arcsec":{"type":["number","null"],"description":"Great-circle distance to the matched row. Null where nothing matched."},"matches_within_radius":{"type":"integer","description":"Rows inside the tolerance, the reported one included."},"next_separation_arcsec":{"type":["number","null"],"description":"Distance to the second-nearest row inside the tolerance, which is what says whether the first one is safe."},"chance_alignments":{"type":["number","null"],"description":"Unrelated rows expected inside the tolerance from the surface density measured around this target. A Poisson mean rather than a verdict: 0.3 means a third of the targets in a field like this one would have an unrelated row inside the tolerance."},"object":{"description":"The catalogued row, on a match against the catalog. Null where none was inside the tolerance.","oneOf":[{"$ref":"#/components/schemas/ObjectSummary"},{"type":"null"}]},"source":{"description":"The survey row, on a match against a survey table.","oneOf":[{"$ref":"#/components/schemas/SourceRecord"},{"type":"null"}]}}}}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["bad_request","not_found","rate_limited","internal_error"]},"message":{"type":"string"}},"required":["code","message"]}}}}}}