SpaceTAP: an Elixir client for the IVOA Table Access Protocol

SpaceTAP

SpaceTAP is an Elixir client for the IVOA Table Access Protocol (TAP), the HTTP protocol astronomical archives use to expose their tables. You send a query written in ADQL, a dialect of SQL with functions for positions on the sky, and get the table back as Elixir data.

It is not related to the Test Anything Protocol, which shares the acronym.

Coming from Python? The parity livebook runs the same queries through PyVO and SpaceTAP side by side.

Installation

Add space_tap to the dependencies in mix.exs:

def deps do
  [
    {:space_tap, "~> 0.2.0"}
  ]
end

In Livebook or a script:

Mix.install([{:space_tap, "~> 0.2.0"}])

Usage

SpaceTAP.query/3 takes the service URL of a TAP service and an ADQL query. This one asks the GAVO Data Center, the German Virtual Observatory's archive, for the five brightest stars within one degree of the centre of the Pleiades, from its copy of Gaia DR3:

adql = """
SELECT TOP 5 source_id, ra, dec, parallax, phot_g_mean_mag
FROM gaia.dr3lite
WHERE CONTAINS(POINT('ICRS', ra, dec), CIRCLE('ICRS', 56.75, 24.12, 1.0)) = 1
  AND parallax IS NOT NULL AND phot_g_mean_mag IS NOT NULL
ORDER BY phot_g_mean_mag
"""

{:ok, result} = SpaceTAP.query("https://dc.g-vo.org/tap", adql)

result.columns
#=> ["source_id", "ra", "dec", "parallax", "phot_g_mean_mag"]

hd(result.rows)
#=> ["66526127137440128", "57.29068893293528", "24.053211829998986",
#=>  "8.118448", "3.6157947"]

The Gaia archive at ESA, where Gaia's data comes from, answers the same query on gaiadr3.gaia_source at https://gea.esac.esa.int/tap-server/tap. There parallax is a double, a 64-bit number, so it has more digits: "8.118448445799721" rather than "8.118448".

The service URL is the base URL of the service, what TAP calls its access URL. SpaceTAP sends the query to its /sync endpoint, so pass the base URL even if you know the endpoint.

Use the https:// URL when the service has one. Gaia, for example, redirects http:// to https:// with a 302. Req, like curl and PyVO, follows a 301 or 302 with a GET, as RFC 9110 allows (§15.4.2, §15.4.3), and the GET carries no query. The request then fails, with an error that depends on the service: Gaia answers with its list of async jobs, which SpaceTAP returns as a :decode_error.

The result is a SpaceTAP.Result: columns holds the column names in order, and each row is a list with one value per column, in the same order. To work with maps instead:

Enum.map(result.rows, fn row -> Map.new(Enum.zip(result.columns, row)) end)

Options

Errors

A failed query returns {:error, %SpaceTAP.Error{}}, whose :type says what went wrong:

Type When
:service_error The service rejected the query, for example because of invalid ADQL or an unknown table. :message is the service's own message.
:http_error An HTTP error status without an error document from the service, such as a proxy's 502 page.
:transport_error No response arrived: the connection failed or timed out.
:decode_error A successful response that can't be read as a result, such as malformed CSV.

Later versions may add types, so when you match on :type, keep a clause for the rest.

:status holds the HTTP status, and Exception.message/1 starts with it:

{:error, error} =
  SpaceTAP.query(service_url, "SELECT TOP 3 source_id FROM gaia.no_such_table")

error.type
#=> :service_error

Exception.message(error)
#=> "(HTTP 500) Field query: Could not locate table 'gaia.no_such_table'"

CSV or VOTable

SpaceTAP asks the service for CSV by default, as it did in 0.1. CSV is simple, but it carries less than VOTable, the IVOA format for tables:

With format: :votable, SpaceTAP asks for VOTable instead:

{:ok, result} = SpaceTAP.query("https://dc.g-vo.org/tap", adql, format: :votable)

hd(result.rows)
#=> [66526127137440128, 57.29068893293528, 24.053211829998986,
#=>  8.118448257446289, 3.6157946586608887]

result.overflow
#=> false

parallax and phot_g_mean_mag are floats, 32-bit numbers, and SpaceTAP gives the exact value of their 32 bits as an Elixir float: 3.6157946586608887, where the CSV says 3.6157947. Both are the same number, and PyVO reads the same value.

The service picks how the rows travel inside the VOTable, and SpaceTAP reads the three serializations TAP services send: TABLEDATA, BINARY and BINARY2. A VOTable that comes when CSV was asked for, as MAST sends, is a :decode_error that says to pass format: :votable, so the value types don't depend on the service.

Async queries, for long-running and large results, are planned for a later version.

Compatibility

SpaceTAP follows TAP 1.1 and works with TAP 1.0 services. It has been checked against these services, last on 16 November 2026, except four that didn't answer that day: Gaia was last checked on 13 November, IRSA on 10 November, and VizieR and SIMBAD, both run by CDS, on 27 October, with CSV only.

Service Service URL Formats Checked by Notes
Gaia archive (ESA) https://gea.esac.esa.int/tap-server/tap CSV, VOTable Services and parity tests, fixtures, livebook Redirects http:// to https://, which loses the query: use https://.
GAVO Data Center https://dc.g-vo.org/tap CSV, VOTable Integration, services and parity tests, fixtures, livebooks Runs DaCHS. Holds a copy of Gaia DR3 in gaia.dr3lite. Sends error documents with HTTP 500. Sends one row more than :maxrec asks for, and one row with maxrec: 0, marked as overflow.
NASA Exoplanet Archive https://exoplanetarchive.ipac.caltech.edu/TAP CSV, VOTable Services and parity tests, fixtures, livebooks Labels CSV text/plain. Applies TOP before ORDER BY, so use :maxrec to get the first rows of a sorted result.
IRSA (IPAC) https://irsa.ipac.caltech.edu/TAP CSV, VOTable Services and parity tests, fixtures, livebook
NED (IPAC) https://ned.ipac.caltech.edu/tap CSV, VOTable Services and parity tests, fixtures, livebook
KOA (Keck) https://koa.ipac.caltech.edu/TAP CSV, VOTable Services and parity tests, fixtures, livebook Labels CSV text/plain. Sends query errors as plain text with HTTP 400, which SpaceTAP returns as a :service_error. Applies TOP before ORDER BY, so use :maxrec to get the first rows of a sorted result.
VizieR (CDS) https://tapvizier.cds.unistra.fr/TAPVizieR/tap CSV; VOTable not checked yet Services and parity tests, fixtures, livebook
SIMBAD (CDS) https://simbad.cds.unistra.fr/simbad/sim-tap CSV; VOTable not checked yet Services and parity tests, fixtures, livebook
ESO https://archive.eso.org/tap_obs CSV, VOTable Services and parity tests, fixtures, livebook
CADC https://ws.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/argus CSV, VOTable Services and parity tests, fixtures, livebook Redirects each query to its result with a 303 (TAP 1.1 §2.1), which SpaceTAP follows. Sends query errors as plain text with HTTP 400, which SpaceTAP returns as a :service_error.
MAST https://mast.stsci.edu/vo-tap/api/v0.1/caom VOTable only Services and parity tests, fixtures, livebook Sends VOTable even when CSV is requested, so pass format: :votable.

Integration, services and parity tests query the live service (see Development), and fixtures are its responses, captured for the unit tests. The tour of TAP services livebook queries all of them. Services change, so one that worked here may behave differently today.

Development

Run the unit tests, which don't need network access:

mix test

Integration tests run queries against GAVO, on its copy of Gaia DR3, and are excluded by default:

mix test --include integration

Parity tests run the same queries through SpaceTAP and through PyVO, an Astropy-affiliated Python client for IVOA services, and compare the results: the columns, the overflow and the value of every cell. They need uv. Those for GAVO run with:

mix test --only pyvo

Parity tests on the fixtures have SpaceTAP and PyVO read each VOTable fixture, with no network, and CI runs them on every pull request:

mix test --only pyvo_fixtures

mix test.release runs the unit, integration and parity tests above. Run it before a release.

Services tests send the queries of the fixtures to every service in Compatibility, check that they still answer the same way, and run their parity tests. They are slow, and a failure is a reason to look into that service, not to hold a release, so mix test.release leaves them out:

mix test.services

The livebooks folder has Livebook notebooks that run SpaceTAP against Gaia DR3 at GAVO, the NASA Exoplanet Archive and other services, with tables and charts, and one that runs the parity tests' queries through SpaceTAP and PyVO side by side. They install SpaceTAP from Hex, and each one has a "Run in Livebook" button on HexDocs.

About

SpaceTAP started as an exploration of the astronomy software ecosystem from Elixir: how libraries such as Python's PyVO and Astroquery work, and what Elixir can bring to it. It is written with AI coding tools; I review, test and answer for every change.

Contributing

Contributions made with AI tools are welcome, but a person must open, supervise and answer for every issue and pull request. See AGENTS.md.

License

MIT. See LICENSE.