SpaceTAP (SpaceTAP v0.1.0)

Copy Markdown View Source

Elixir client for the IVOA Table Access Protocol (TAP), the HTTP protocol astronomical archives use to expose tabular data.

query/3 sends a query written in ADQL to a TAP service and returns its result as a SpaceTAP.Result, or a SpaceTAP.Error when it fails.

SpaceTAP follows TAP 1.1 and works with TAP 1.0 services.

Summary

Types

option()

An option for query/3.

Functions

query(service_url, adql, opts \\ [])

Runs a sync query: sends adql to the TAP service at service_url and returns its result.

Types

option()

@type option() :: {:maxrec, non_neg_integer()} | {:req_options, keyword()}

An option for query/3.

Functions

query(service_url, adql, opts \\ [])

@spec query(String.t(), String.t(), [option()]) ::
  {:ok, SpaceTAP.Result.t()} | {:error, SpaceTAP.Error.t()}

Runs a sync query: sends adql to the TAP service at service_url and returns its result.

service_url is the base URL of the service, such as "https://gea.esac.esa.int/tap-server/tap" for the Gaia archive. The query goes to its /sync endpoint (TAP 1.1 §2.4), appended after trimming any trailing /, so pass the base URL even if you know the endpoint.

Use the https:// URL when the service has one. Req follows a 301 or 302 redirect with a GET that drops the query (RFC 9110 §15.4.2, §15.4.3), so a service that redirects http:// to https:// gets no query, and the request fails.

SpaceTAP.query(
  "https://gea.esac.esa.int/tap-server/tap",
  "SELECT TOP 3 source_id, ra, dec FROM gaiadr3.gaia_source"
)
#=> {:ok, %SpaceTAP.Result{columns: ["source_id", "ra", "dec"], rows: [...]}}

The result comes as CSV, so every value is a string and an empty cell is nil (see SpaceTAP.Result). Errors come as {:error, %SpaceTAP.Error{}}, whose :type says what went wrong.

Options

  • :maxrec - the maximum number of rows to return, a non-negative integer. The service may apply a lower limit of its own, and 0 returns the columns with no rows (DALI 1.1 §3.4.4).
  • :req_options - a keyword list of options for Req.new/1, such as :receive_timeout to wait longer than Req's default 15 seconds. SpaceTAP sets :method, :url, :form, :user_agent, :decode_body, :http_errors and :into itself, and ignores them here. Other options go to Req as given, and some change the request: a user-agent in :headers replaces SpaceTAP's, and :params adds parameters to the URL.

An unknown option, or a :maxrec or :req_options that isn't what the list above says, raises ArgumentError.