Usage Guide

This guide provides detailed examples of how to use HAPIClient.jl to access heliophysics data from HAPI servers.

Basic Usage

Listing Available Servers

Start by exploring what HAPI servers are available:

using HAPIClient

# List all available HAPI servers
servers = hapi()

19-element Vector{SubString{String}}:
 "https://cdaweb.gsfc.nasa.gov/hapi"
 "http://hapi-server.org/servers/SSCWeb/hapi"
 "https://amda.irap.omp.eu/service/hapi"
 "https://csatools.esac.esa.int/HapiServer/hapi"
 "https://iswa.gsfc.nasa.gov/IswaSystemWebApp/hapi"
 "https://vires.services/hapi"
 "https://imag-data.bgs.ac.uk/GIN_V1/hapi"
 "https://supermag.jhuapl.edu/hapi"
 "https://wdcapi.bgs.ac.uk/hapi"
 "http://lasp.colorado.edu/lisird/hapi"
 "https://hapi.spaceweather.knmi.nl/hapi"
 "https://api.helioviewer.org/hapi/Helioviewer/hapi"
 "https://planet.physics.uiowa.edu/das/das2Server/hapi"
 "http://hapi-server.org/servers/TestData2.0/hapi"
 "http://hapi-server.org/servers/TestData2.1/hapi"
 "http://hapi-server.org/servers/TestData3.0/hapi"
 "http://hapi-server.org/servers/TestData3.1/hapi"
 "http://hapi-server.org/servers/TestData3.2/hapi"
 "http://hapi-server.org/servers/TestData3.3/hapi"

Getting Dataset Catalogs

Once you know which servers are available, you can browse their catalogs:

# Get catalog of available datasets from CDAWeb
catalog = hapi(CDAWeb)

3521-element Vector{Any}:
 Dict{String, Any}("id" => "A1_K0_MPA")
 Dict{String, Any}("id" => "A2_K0_MPA")
 Dict{String, Any}("id" => "AC_AT_DEF")
 Dict{String, Any}("id" => "AC_H0_MFI")
 Dict{String, Any}("id" => "AC_H0_SWE")
 Dict{String, Any}("id" => "AC_H1_EPM")
 Dict{String, Any}("id" => "AC_H1_MFI")
 Dict{String, Any}("id" => "AC_H1_SIS")
 Dict{String, Any}("id" => "AC_H2_CRIS")
 Dict{String, Any}("id" => "AC_H2_EPM")
 ⋮
 Dict{String, Any}("id" => "WI_PLSP_3DP")
 Dict{String, Any}("id" => "WI_PM_3DP")
 Dict{String, Any}("id" => "WI_SFPD_3DP")
 Dict{String, Any}("id" => "WI_SFSP_3DP")
 Dict{String, Any}("id" => "WI_SOPD_3DP")
 Dict{String, Any}("id" => "WI_SOSP_3DP")
 Dict{String, Any}("id" => "WI_STRAHL0_SWE")
 Dict{String, Any}("id" => "WI_SW-ION-DIST_SWE-FARADAY")
 Dict{String, Any}("id" => "WI_WA_RAD1_L3_DF")

Dataset Information

Get detailed information about parameters in a specific dataset:

dataset = "AC_H0_MFI"
params = hapi(CDAWeb, dataset)

Dict{String, Any} with 7 entries:
  "stopDate"    => "2025-05-29T23:59:58Z"
  "resourceURL" => "https://cdaweb.gsfc.nasa.gov/misc/NotesA.html#AC_H0_MFI"
  "parameters"  => Any[Dict{String, Any}("length"=>24, "name"=>"Time", "units"=…
  "startDate"   => "1997-09-02T00:00:12Z"
  "status"      => Dict{String, Any}("message"=>"OK", "code"=>1200)
  "HAPI"        => "2.0"
  "contact"     => "N. Ness @ Bartol Research Institute"

Data Retrieval and Access

Basic Data Download

Retrieve data for specific parameters within a time range:

using Dates

dataset = "AC_H0_MFI"
parameters = "Magnitude,BGSEc"
tmin = DateTime(2001, 1, 1, 5, 0, 0)
tmax = DateTime(2001, 1, 1, 6, 0, 0)

# Retrieve the data
data = hapi(CDAWeb, dataset, parameters, tmin, tmax)

HAPIVariables
  Magnitude [Time Range: 2001-01-01T05:00:14 to 2001-01-01T05:59:58, Units: nT, Size: (225,)]
  BGSEc [Time Range: 2001-01-01T05:00:14 to 2001-01-01T05:59:58, Units: nT, Size: (225, 3)]
Metadata - Dict{String, Any} with 8 entries:
  "stopDate"    => "2025-05-29T23:59:58Z"
  "resourceURL" => "https://cdaweb.gsfc.nasa.gov/misc/NotesA.html#AC_H0_MFI"
  "uri"         => URI("https://cdaweb.gsfc.nasa.gov/hapi/data?time.min=2001-01…
  "parameters"  => Any[Dict{String, Any}("length"=>24, "name"=>"Time", "units"=…
  "startDate"   => "1997-09-02T00:00:12Z"
  "status"      => Dict{String, Any}("message"=>"OK", "code"=>1200)
  "HAPI"        => "2.0"
  "contact"     => "N. Ness @ Bartol Research Institute"

Alternative Path Format

You can also use a path-like format for data retrieval. The path format is "server/dataset/parameter", where datasets may contain slashes:

data = get_data("CDAWeb/AC_H0_MFI/Magnitude,BGSEc", tmin, tmax)

Note

This path format cannot handle cases where both the dataset and parameter contain slashes (e.g., dataset=abc/123 and parameter=p1/v1). In such cases, use the hapi() function directly.

Accessing Retrieved Data

Once you have retrieved data, you can access individual variables:

Magnitude = data.Magnitude # or data[1] if you know the order (same as `parameters` order)
BGSEc = data.BGSEc # or data[2]
var = data[2]

HAPIVariable{Float64, 2, Matrix{Float64}, Vector{Dates.DateTime}}: BGSEc
  Time Range: 2001-01-01T05:00:14 to 2001-01-01T05:59:58
  Units: nT
  Size: (225, 3)
  Memory Usage: 7.858 KiB
  Metadata:
    units: nT
    name: BGSEc
    size: Any[3]
    fill: -1.0E31
    description: Magnetic Field Vector in GSE Cartesian coordinates (16 sec)
    type: double

Retrieve the values

values = parent(var)

225×3 Matrix{Float64}:
 -3.588   0.2    -2.425
 -3.534   0.149  -2.42
 -3.543   0.14   -2.427
 -3.581   0.067  -2.47
 -3.536   0.062  -2.463
 -3.557   0.063  -2.452
 -3.557   0.02   -2.429
 -3.593   0.04   -2.409
 -3.655  -0.017  -2.396
 -3.596   0.073  -2.406
  ⋮              
 -3.895   0.251  -2.019
 -3.877   0.229  -2.036
 -3.934   0.285  -2.028
 -3.781   0.283  -2.074
 -3.792   0.328  -2.15
 -3.831   0.333  -2.123
 -3.528   0.03   -2.519
 -3.398   0.072  -2.647
 -3.454   0.044  -2.663

Retrieve the timestamps

timestamps = times(var)

225-element Vector{Dates.DateTime}:
 2001-01-01T05:00:14
 2001-01-01T05:00:30
 2001-01-01T05:00:46
 2001-01-01T05:01:02
 2001-01-01T05:01:18
 2001-01-01T05:01:34
 2001-01-01T05:01:50
 2001-01-01T05:02:06
 2001-01-01T05:02:22
 2001-01-01T05:02:38
 ⋮
 2001-01-01T05:57:50
 2001-01-01T05:58:06
 2001-01-01T05:58:22
 2001-01-01T05:58:38
 2001-01-01T05:58:54
 2001-01-01T05:59:10
 2001-01-01T05:59:26
 2001-01-01T05:59:42
 2001-01-01T05:59:58

Retrieve the metadata

metadata = meta(var)

Dict{String, Any} with 6 entries:
  "units"       => "nT"
  "name"        => "BGSEc"
  "size"        => Any[3]
  "fill"        => "-1.0E31"
  "description" => "Magnetic Field Vector in GSE Cartesian coordinates (16 sec)"
  "type"        => "double"

Working with Different Servers

CSA Example

# Example with CSA (Cluster Science Archive) server
dataset = "C4_CP_FGM_FULL"
parameters = "B_vec_xyz_gse,B_mag"
tmin = DateTime(2001, 6, 11, 0, 0, 0)
tmax = DateTime(2001, 6, 11, 0, 1, 0)
data = hapi(CSA, dataset, parameters, tmin, tmax)

INTERMAGNET Example

# Example with INTERMAGNET server (datasets with slashes in names)
dataset = "aae/definitive/PT1M/xyzf"
parameters = "Field_Vector"
tmin = DateTime(2001, 6, 11, 0, 0, 0)
tmax = DateTime(2001, 6, 11, 0, 1, 0)
data = hapi(INTERMAGNET, dataset, parameters, tmin, tmax)
data = get_data("INTERMAGNET/aae/definitive/PT1M/xyzf/Field_Vector", tmin, tmax)

Data Analysis

The retrieved data integrates well with Julia's ecosystem:

using CairoMakie

f = Figure()
for (i, var) in enumerate(data)
    m = meta(var)
    ax = Axis(f[i,1]; xlabel="Time", ylabel=m["name"], title=m["description"])
    t = times(var)
    for c in eachcol(var)
        lines!(t, c)
    end
    i != length(data) && hidexdecorations!(; grid=false)
end
f

For advanced visualization capabilities, HAPIClient.jl works well with the SPEDAS.jl ecosystem. See the SPEDAS.jl quickstart guide for detailed visualization examples.