The catalog, one endpoint away

$ curl https://spacecatalog.org/api/v1/objects/sgr-a

{
  "slug": "sgr-a",
  "name": "Sagittarius A*",
  "class": "supermassive_black_hole",
  "category": "black_hole",
  "mass_kg": 8.544197214389525e+36,
  "mass_msun": 4297000,
  "distance_ly": 26996,
  "constellation": "Sagittarius",
  "discovered": "1974",
  "designations": [
    "Sagittarius A*",
    "Sgr A*"
  ],
  "source": "curated",
  "…": "description, properties, ra_deg, dec_deg, updated_at"
}

OPENAPI 3.1 SPEC →

Every list endpoint answers in three shapes. format=json is the full record. format=votable is IVOA VOTable 1.4, which TOPCAT, Aladin and anything else that reads the standard will open with the units and the UCDs intact — the position columns are tagged pos.eq.ra;meta.main and pos.eq.dec;meta.main, so a table lands on the sky without being told which column is which. format=csv is the same columns under the same names, for everything else. Both flat forms drop the parts of a record a table has no room for — an object’s properties, its cross-designations, the source block — and keep the observable quantities. A table of one survey’s rows still says whose rows they are: a CSV of Gaia DR3 sources arrives with x-source-license, x-source-attribution and x-source-commercial-use response headers, and the VOTable carries the same terms as INFO elements. A value that is not plain ASCII, such as GLADE+’s credit to Dálya et al., is sent RFC 8187-encoded. A table of catalog objects mixes upstreams, so each row names its own: a source column holds the id of the catalogue the row came from — the id of the record’s source block in JSON — and the VOTable states each of those catalogues’ terms as the same INFO elements with the id after a colon, sourceLicense:hyg. A table of events does the same for the two kinds it reads rather than computes: close_approaches on a flyby, imo_showers on a meteor shower, and an empty cell on the rest. Every upstream is listed under its id, with its terms, on the about page.

$ curl -o galaxies.vot \
    "https://spacecatalog.org/api/v1/objects?category=galaxy&mag_max=9&limit=200&format=votable"

For the tools that would rather ask than be handed a file, three Simple Cone Search services. Paste a base URL into a cone-search box, give it a position and a radius, and the answer is a layer on the sky. One service per table, because that is what the standard means by one: the catalog, and each of the two surveys underneath it.

RA, DEC and SR in decimal degrees, case-insensitive; VERB=1 for the identifier and the position alone, 3 for every column. A request the service cannot answer comes back as a VOTable saying why, because that is where a cone-search client looks — and where the answer was cut short, an OVERFLOW status follows the table rather than letting a partial result pass for a complete one.

Every catalogued position here is J2000, because that is the epoch its upstreams publish. It is also where the sky was a quarter of a century ago: since then the coordinate grid has turned by more than twenty arcminutes, and the fastest stars have crossed several arcminutes of their own. Add epoch to either object endpoint and each answer carries the propagated position as well as the stored one.

$ curl "https://spacecatalog.org/api/v1/objects/barnard-s-star?epoch=now&frame=date"

epoch takes now, a Julian year J2026.5, or an ISO 8601 date. frame=icrs, the default, applies the object’s own proper motion and nothing else — that is what an epoch is, and it is the position to cross-match against Gaia with. frame=date also turns the grid to the true equator and equinox of that instant — precession plus nutation — which is what a mount expects and is about fifty arcseconds a year larger. The two are different corrections to different things: one moves the object, the other moves the grid under it.

Nothing is overwritten. ra_deg and dec_deg are the catalogued J2000 pair in every response; epoch_ra_deg and epoch_dec_deg arrive beside them, and epoch_moved_arcsec is how far the object itself travelled — proper motion alone, so it reads the same in either frame. The published motions come with it, as pm_ra_mas_yr (that is µα cos δ, an angle on the sky) and pm_dec_mas_yr, so the arithmetic can be redone and checked. An object with no measured motion comes back where the catalog has it rather than at an invented zero, and a body with no fixed position at all is not propagated — a planet, a moon or a comet has an ephemeris rather than a coordinate, which is what /api/v1/visible answers with.

Left out: parallax, the radial-velocity perspective term, aberration and refraction. Each is smaller than an arcminute, which is also about as well as the catalogued positions themselves are known. Every response that propagated anything carries an epoch block spelling that out, because “of date” means at least four different things depending on which terms are in it.

An observing run does not produce a position. It produces a file of them, and for every line the same question: what is this, and how far off is it. POST /api/v1/xmatch takes the whole file and answers it once — up to 500 targets, matched against the catalog or against either survey underneath it, with the answers in the order the targets were sent so the result joins straight back onto the file it came from. A target that matched nothing keeps its line rather than disappearing out of the middle of your spreadsheet.

$ curl -X POST "https://spacecatalog.org/api/v1/xmatch?radius_arcsec=3&format=csv" \
    --data-binary @targets.csv

target_row,target_id,target_ra_deg,target_dec_deg,separation_arcsec,…
1,field-1,10.6847,41.2687,1.42,…

The body is JSON — {"targets": [{"id": "a", "ra": 10.6847, "dec": 41.2687}]} — or a table with one target per line, comma, tab, semicolon or whitespace separated. A first line naming its columns is read for a right ascension, a declination and an identifier under the spellings the archives use, and without one a row is ra,dec or id,ra,dec. Positions may be decimal or sexagesimal, and which one decides the unit: 10.6847 is degrees, 00 42 44.3 and 00:42:44.3 are hours. That is the convention every catalog uses and it is also the most expensive thing here to get wrong, so a row that cannot be read comes back as an error naming the row rather than as a row quietly dropped — a list of answers only lines up with the list of questions if nothing went missing in between.

The nearest row is not an identification, and every match says how contested it was. matches_within_radius is how many rows fell inside the tolerance, next_separation_arcsec is how far the runner-up was, and chance_alignments is how many unrelated rows the sky right there would be expected to put inside the tolerance anyway — counted from the surface density measured around that target rather than from the catalog’s average, because a degree of the galactic plane holds two orders of magnitude more Gaia sources than a degree at the pole and a false-match rate quoted for the average is wrong in both places. Against the catalog it is essentially always zero; against Gaia at three arcseconds in a crowded field it is not, and that difference is the whole question.

epoch moves the catalog to the epoch your list is on before the comparison rather than after it, which matters for exactly the stars a cross-match is most likely to get wrong: catalogued positions here are J2000, and a star with a large proper motion can sit several arcseconds from its own counterpart in a list taken last year. The survey tables cannot be propagated — they hold positions and no proper motions — and they are matched on the epoch they were published at, which for Gaia DR3 is J2016.0 and not J2000.

/api/v1/visible answers what is above the horizon at an instant. The question an observing run is planned from is the other one: this object, this night — is it up at all, how many of the dark hours is it high enough to be worth pointing at, when in those hours is it highest, and where is the Moon going to be while they pass. /api/v1/ephemeris answers that for one target: rise, transit and set, the altitude and air-mass curve of the whole night, and the Moon on every row of it.

$ curl "https://spacecatalog.org/api/v1/ephemeris?object=m31&lat=19.82&lon=-155.47&date=2026-10-15"

"events":       { "rise": …, "transit": …, "transit_altitude_deg": 78.2, … }
"observability":{ "hours_observable": 7.4, "best": { "airmass": 1.02, … } }
"moon":         { "phase_name": "waning crescent", "separation_deg": 96.3, … }
"track":        [ { "time": …, "altitude_deg": …, "airmass": …, "sky": … }, … ]

The target is anything this catalog resolves — a slug, a designation, a Gaia or GLADE+ identifier — or a bare ra and dec for the transient that is not in any catalogue yet, which is most of what a telescope actually points at. A star’s own proper motion is applied before the night is computed rather than after, and the propagated position comes back with the answer. format=csv and format=votable return the curve, because an air-mass curve is a table before it is a picture and TOPCAT will plot it from those rows unaided.

Two horizons, and the response says which is which. Rise and set are the almanac definition — the upper limb crossing a horizon lifted by 34 arcminutes of refraction — and that refraction is scaled to the density of the air the observer is actually under, so the same star rises measurably later from the top of a mountain than the sea-level figure claims. Every other altitude here, including the curve and the thresholds cut out of it, is the geometric altitude of the body’s centre with no refraction in it. The two differ by about half a degree, which is why the curve reads slightly below zero at the reported rise time, and events.horizon_altitude_deg is the number that reconciles them.

hours_observable is solved for, not counted off the samples: the moments the target crosses the altitude floor and the moments the sky crosses eighteen degrees of twilight are each found to the second and then intersected, so the figure does not move when step_min does. And a night that has no sunset in it is answered rather than refused — the window becomes the whole day, and the response distinguishes a Sun that never sets from one that never rises, which arrive from the same search as the same missing sunset.

Every other endpoint here answers a question about a place — where an object is, what is above your horizon, when it rises for you. /api/v1/events answers the one that has no place in it. A full moon is full for all of us at once; an eclipse peaks at one instant; a meteor shower maximises when the Earth reaches a particular point in its orbit. Eight kinds — eclipses, showers, the Moon’s quarters, close pairings of the bright planets, oppositions, greatest elongations, the equinoxes and solstices, and near-Earth flybys — earliest first, over any window up to two years.

$ curl "https://spacecatalog.org/api/v1/events?from=2026-01-01&to=2026-12-31&kind=eclipse"

"time":          "2026-08-12T17:46:00.000Z"
"title":         "Total solar eclipse"
"position":      { "ra_deg": 145.9, "dec_deg": 14.8 }
"circumstances": { "obscuration": 1, "greatest_at": { "lat_deg": 65.2, … } }

Seven of the eight kinds are solved from an ephemeris at the moment you ask, so there is no stored list to run out and no year that quietly ends. The eighth cannot be: a rock discovered last month has no orbit until somebody measures one, so the close approaches are what JPL published when this was last refreshed. meta.close_approaches carries that date and the date the list runs to, because the end of a window and an empty stretch of sky look identical from the outside and only one of them is true. A flyby’s source carries JPL’s terms and the citations JPL asks for, and a shower’s names the International Meteor Organization’s working list its longitudes and rates are taken from; the computed kinds have none.

circumstances holds whatever numbers the kind has and omits what it does not — a separation for a pairing, an obscuration and the latitude and longitude of greatest eclipse for a solar one, a rate and an entry speed for a shower, a miss distance in lunar distances for a flyby. format=csv and format=votable flatten all of them into columns, one per circumstance, mostly empty per row and filterable in one pass, which is the shape a table wants even where a record would nest. position is geocentric ICRS/J2000 — the body at that instant, or a shower’s radiant — and is absent where an event has no one place in the sky, as an equinox does not.

The same events are also served as a calendar file, which is the format most people actually want them in: /calendar.ics is the next twelve months as timed UTC entries, and it takes the calendar page’s own filters — show= for the kinds, site= or lat=&lon= for a place, and visible=1 to drop what cannot be seen from it. Subscribe to the address rather than importing it once and it keeps itself current. Every entry is an instant in UTC rather than an all-day block, because an all-day block on the wrong side of a date line is how somebody ends up outside on the wrong night.

Nearly six thousand stars here carry a variability classification, and for seventeen hundred of them the catalog publishes both a period and the epoch of an observed maximum or minimum. Those two together are an ephemeris: count the whole cycles between them and now, and the remainder says where in its cycle the star is and when the next event falls. Every object record for such a star carries a variability block with the elements; add epoch and it also carries the phase at that instant.

$ curl "https://spacecatalog.org/api/v1/objects/algol?epoch=now"

The instant is the caller’s rather than the server’s because a phase belongs to a moment: computed at whatever time a response happened to be generated, it would go quietly stale in a cache, and for a binary with a six-hour period it would do so within one. phase.value is 0 at the event epoch_marks names — minimum light for eclipsing and ellipsoidal variables and for the RV Tauri and RS Canum Venaticorum types, maximum for every other class — and phase.next lists the coming events as instants. Both are on the heliocentric scale the epochs are published on, so the correction for where the Earth stands in its orbit is in them: it reaches 8.3 minutes, which for a six-hour binary is a fiftieth of a cycle.

A phase is withheld rather than guessed. A star whose class has no ephemeris — a dwarf nova, an irregular or a semiregular variable, where the published period is a mean cycle time the star has no obligation to keep — gets its elements and an unavailable sentence saying so, as does one with a period and no epoch. So does one whose elements have simply worn out: the last digit of a period compounds once per cycle, and after a hundred thousand cycles a period good to a hundredth of a day is not good to anything. phase.uncertainty is that accumulation, and past a quarter of a cycle the answer is the reason instead of the number.