The Heliophysics Application Programmer's Interface (HAPI) Specification

1 Signi ican Changes o Speci ica ion
1.1 2 o 3 API Changes
1.2 2 o 3 Schema Changes
1.3 3.X changes
2 In oduc ion
2.1 O e iew
2.2 Facili a ing Adop ion
2.3 Limi a ions
3 Endpoin s
3.1 O e iew
3.2 hapi
3.3 abou
3.4 capabili ies
3.5 ca alog
3.6 in o
3.6.1 Reques Pa ame e s
3.6.2 in o Response Objec
3.6.3 uni sSchema De ails
3.6.4 coo dina eSys emSchema De ails
3.6.5 addi ionalMe ada a Objec
3.6.6 s ingType Objec
3.6.7 pa ame e Objec
3.6.8 size De ails
3.6.9 ill De ails
3.6.10 uni s and label A ay
3.6.11 ec o Componen s Objec
3.6.12 loca ion and geoLoca ion De ails
3.6.13 bins Objec
3.6.14 JSON Re e ences
3.7 da a
3.7.1 Reques Pa ame e s
3.7.2 Response
3.7.3 Examples
3.7.3.1 Da a wi h Heade
3.7.3.2 Da a Only
3.7.4 Response o ma s
3.7.4.1 CSV
3.7.4.2 Bina y
3.7.4.3 JSON
3.7.5 E o s While S eaming
3.7.6 Rep esen a ion o Time
3.7.6.1 Incoming ime alues
3.7.6.2 Ou going ime alues
3.7.6.3 Time Range Wi h No Da a
3.7.6.4 Time Range Wi h All Fill Values
4 S a us Codes
4.1 s a us Objec
4.2 s a us E o Codes
4.3 Clien E o Handling
5 Implemen a ion De ails
5.1 C oss-O igin Resou ce Sha ing
5.2 Secu i y No es
5.3 HEAD Reques s and E iciency
6 Re e ences
7 Con ac
8 Appendix
8.1 Sample Landing Page
8.2 Allowed Cha ac e s in id, da ase , and pa ame e s
8.3 JSON Objec o S a us Codes
8.4 Examples
8.5 Robo clien s
8.6 FAIR
8.6.1 Findable
8.6.2 Accessible
8.6.3 In e ope able
8.6.4 Reusable
Ve sion 3.3.1 | Heliophysics Da a and Model Conso ium (HDMC) |
DOI
DOI 10.5281/zenodo.17516129
10.5281/zenodo.17516129
1 Signi ican Changes o Speci ica ion
No e ha e sion 3.0 in oduced some b eaking changes. They a e lis ed he e and a e documen ed as
issues in he 3.0 Miles one lis .
1.1 2 o 3 API Changes
Non-backwa d compa ible changes in oduced o he eques in e ace in HAPI 3.0:
1. The URL pa ame e id was eplaced wi h da ase .
2. ime.min and ime.max we e eplaced wi h s a and s op, espec i ely.
3. Addi ion o a new endpoin , “abou “, o se e desc ip ion me ada a.
These changes we e discussed in issue #77. HAPI 3 se e s mus accep bo h he old and hese new
pa ame e names, bu he HAPI 2 speci ica ion equi es an e o esponse i he new URL pa ame e
names a e used. In a u u e e sion, he dep eca ed olde names will no longe be alid.
1.2 2 o 3 Schema Changes
This lis cap u es new op ional elemen s ha can be included in he in o esponse as o 3.0:
1. Abili y o speci y ime- a ying bins (#83)
2. Abili y o use JSON e e ences in in o esponse (#82)
3. Abili y o indica e a uni s schema (i one is being used o uni s s ings) (#81)
1.3 3.X changes
3.0, 3.1, 3.2, and 3.3 changes a e documen ed in he changelog. We ollow Seman ic Ve sioning
con en ions, so all 3.X e sions a e backwa d compa ible wi h e sion 3.0.
2 In oduc ion
2.1 O e iew
This documen desc ibes he Heliophysics Applica ion P og amme ’s In e ace (HAPI) speci ica ion,
which is an API, me ada a, and da a s eaming o ma speci ica ion o ime-se ies da a. The in en o
his speci ica ion is o enhance in e ope abili y among ime se ies da a p o ide s. The objec i e o his
speci ica ion is o cap u e ea u es a ailable om many exis ing da a p o ide s and o codi y
implemen a ion de ails so ha p o ide s can use a common API. This will make i possible o ob ain
ime se ies science da a con en seamlessly om many sou ces and use a a ie y o p og amming
languages.
This documen is in ended o be used by wo g oups o people: i s by da a p o ide s who wan o make
ime-se ies da a a ailable h ough a HAPI se e , and second by da a use s who wan o unde s and how
da a is made a ailable om a HAPI se e , o pe haps o w i e clien so wa e o ob ain da a om an
exis ing HAPI se e .
HAPI cons i u es a minimum bu comple e se o capabili ies needed o a se e o allow access o he
ime se ies da a alues wi hin one o mo e da a collec ions. Because o i s ocus on da a access, he
HAPI me ada a s anda d is no in ended o complex sea ch and disco e y. Howe e , he me ada a
schema allows ways o indica e whe e u he desc ip i e de ails o any da ase could be ound and he
me ada a con ains enough in o ma ion o enable i s use by complex sea ch and disco e y so wa e.
The HAPI API is based on REp esen a ional S a e T ans e (REST ul) p inciples, which emphasize ha
URLs a e s able endpoin s h ough which clien s can eques da a. Because i is based on well-
es ablished HTTP eques and esponse ules, a wide ange o HTTP clien s can be used o in e ac wi h
HAPI se e s.
Key de ini ions o e ms used in his documen include
pa ame e – a measu ed science quan i y o a ela ed ancilla y quan i y a one ins an in ime; may
be scala o a mul i-dimensional a ay as a unc ion; mus ha e uni s and mus ha e a ill alue ha
indica es no measu emen was a ailable o absen in o ma ion
eco d – all he pa ame e s and an associa ed ime alue
da ase – a collec ion o eco ds wi h he same pa ame e s; a HAPI se ice p esen s a da ase as a
seamless collec ion o ime- eco ds such ha i o a subse o i can be e ie ed wi hou knowledge
o he ac ual s o age de ails
ca alog - a collec ion o da ase s
eques pa ame e – keywo ds ha appea a e he ? in a URL
Fo example, in he eques (see change no es)
h p://se e /hapi/da a?da ase =alpha&s a =2016-07-13&s op=2016-07-14
he h ee eques pa ame e s a e da ase (co esponding o he iden i ie o he da ase ), s a , and
s op. They ha e alues o alpha, 2016-07-13, and 2016-07-14, espec i ely. This documen will
always use he ull ph ase “ eques pa ame e ” o e e o hese URL elemen s o dis inguish hem
om he pa ame e s in a da ase .
In he abo e URL, he segmen ep esen ed as se e cap u es he hos name o he HAPI se e as
well as any p e ix pa h elemen s be o e he equi ed hapi elemen . Fo example, in
h p://example.com/public/da a/hapi, he se e elemen is example.com/public/da a.
2.2 Facili a ing Adop ion
The ex om his sec ion was aken om Weigel e al., 2021.
The HAPI speci ica ion is designed o p o ide a s anda dized way o p o ide s eaming se ices ha
many ime-se ies da a p o ide s al eady o e . The use o he common aspec s o exis ing ea u es o HP
da a p o ide s means ha da a p o ide s can, wi h minimal e o , modi y exis ing s eaming se e s o
make hem HAPI complian .
In addi ion, se e al ools ha e been de eloped o acili a e adop ion.
1. Al hough he HAPI s eaming o ma s a e simple enough ha only 10-20 lines o code a e needed o
ead a basic HAPI esponse, he e a e e o condi ions and o he op imiza ions o conside (such as
caching and pa alleliza ion o eques s); a obus and comp ehensi e clien implemen a ion is
beyond wha should be expec ed o science use s o e en so wa e de elope s who wan o c ea e
ools ha use HAPI da a. Ma u e HAPI se e clien lib a ies a e a ailable om open-sou ce HAPI
p ojec s o Ja a, IDL, MATLAB, and Py hon, so mos use s can begin wi h hese lib a ies. These
clien s ead a HAPI esponse in o a da a s uc u e app op ia e o he gi en language (e.g., in Py hon,
he esponse is ead in o a NumPy N-D a ay wi h imes amps con e ed o Py hon da e ime
objec s). Wo k is unde way o inco po a e HAPI eade s in o exis ing popula analysis amewo ks,
such as SPEDAS in IDL and Py hon, Au oplo in Ja a, SunPy in Py hon, and SpacePy in Py hon.
2. To assis se e de elope s wi h adop ion, a c oss-pla o m e e ence se e has been de eloped.
Wi h his se e , a da a p o ide only needs o p o ide HAPI JSON me ada a and a command-line
p og am ha emi s HAPI CSV gi en inpu s o a da ase iden i ie and s a /s op imes. The se e
handles HAPI e o esponses, eques alida ion, and logging.
3. A alida o / e i ie has been de eloped ha uns many es s on a se e . The se e execu es a
comp ehensi e sui e o es s o compliance wi h he speci ica ion. By ei he downloading and
unning he es so wa e locally, o by en e ing he URL o a HAPI se e in o a websi e, da a
p o ide s can es mos aspec s o hei HAPI implemen a ion, wi h de ailed esul s indica ing
wa nings o e o s. This has p o en o be a e y e ec i e way o assis de elope s, and i helps
ensu e ha new HAPI se e s a e ully unc ional. The es s include checks o JSON esponses
agains he HAPI me ada a schema, e i ying ha he se e handles di e en allowed s a /s op ime
ep esen a ions (e.g, yea , day-o -yea and yea , mon h day wi h a ying amoun s o addi ional ime
p ecision), e o esponses and message, imeou s, and es ing ha ou pu is independen o he
ou pu o ma . Also, he alida o / e i ie makes ecommenda ions. Fo example, i a se e does no
include c oss-o igin eques sha ing heade s o espond wi h comp essed da a when gzip is speci ied
in he Accep -Encoding eques heade , i emi s a message no ing hei ad an ages and a link o
in o ma ion on how o enable o implemen hese ea u es.
2.3 Limi a ions
Because HAPI equi es a single ime column o be he i s column, each eco d (one ow o da a) mus
be associa ed wi h one ime alue ( he i s alue in he ow). This has implica ions o se ing iles wi h
mul iple ime a ays. Suppose a ile con ains 1-second da a, 3-second da a, and 5-second da a, all om
he same measu emen bu a e aged di e en ly. A HAPI se e could expose his da a, bu no as a
single da ase . To a HAPI se e , each ime esolu ion could be p esen ed as a sepa a e da ase , each wi h
i s unique ime a ay.
No e ha he e a e only a ew suppo ed da a ypes: iso ime, s ing, in ege , and double. This is
in ended o keep he clien code simple in e ms o dealing wi h he da a s eam. Howe e , he spec may
be expanded o include o he ypes, such as 4-by e loa ing-poin alues (which would be called loa ),
o 2-by e in ege s (which would be called sho ).
3 Endpoin s
3.1 O e iew
The HAPI speci ica ion has i e equi ed endpoin s ha gi e clien s a p ecise way o i s de e mine he
da a holdings o he se e and hen o eques da a. The unc ionali y o he equi ed endpoin s is as
ollows:
1. /hapi/capabili ies lis s he ou pu o ma s he se e can s eam (cs , bina y, o json, desc ibed
below).
2. /hapi/abou lis s he se e id and i le, con ac in o ma ion, and a b ie desc ip ion o he da ase s
se ed ( his endpoin is new in he e sion 3 HAPI speci ica ion).
3. /hapi/ca alog lis s he ca alog o a ailable da ase s; each da ase is associa ed wi h a unique id and
may op ionally ha e a i le.
4. /hapi/in o lis s in o ma ion abou a da ase wi h a gi en id; a p ima y componen o he desc ip ion
is he lis o pa ame e s in he da ase .
5. /hapi/da a s eams da a o a da ase o a gi en id and o e a gi en ime ange; a subse o
pa ame e s in a da ase may be eques ed (de aul is all pa ame e s).
The e is also an op ional landing page endpoin /hapi ha e u ns human- eadable HTML. Al hough
he e is ecommended con en o his landing page, i is no essen ial o he unc ioning o he se e .
Se e s may ha e non-s anda d endpoin s (an endpoin no gi en abo e) unde /hapi/ i hey a e
p e ixed by x_, e.g., /hapi/x_cus om_endpoin . This will communica e o he use ha his is no a
s anda d endpoin and will p e en a name con lic i he HAPI s anda d adds cus om_endpoin o he
speci ica ion.
The i e equi ed endpoin s a e REST ul-s yle in ha he esul ing HTTP esponse is he comple e
esponse o each endpoin . In pa icula , he /da a endpoin does no gi e URLs o ile o links o
whe e he da a can be downloaded; ins ead, i s eams he da a in he HTTP esponse body. The ull
speci ica ion o each endpoin is desc ibed below.
All endpoin s mus ha e a /hapi pa h elemen in he URL, and only he /in o and /da a endpoin s ake
que y pa ame e s:
h p://se e /hapi (Op ional HTML landing page) 1
h p://se e /hapi/capabili ies 2
h p://se e /hapi/abou 3
h p://se e /hapi/ca alog 4
h p://se e /hapi/in o?da ase =...[&...] 5
h p://se e /hapi/da a?da ase =...&... 6
We ecommend ha any eques s wi h a ailing slash a e handled by sending a 301 edi ec , e.g.,
h p://se e /hapi/ => 301 edi ec o h p://se e /hapi
h p://se e /hapi/in o/?da ase =... => 301 edi ec o h p://se e /hapi/in o?
da ase =...
Reques s o a HAPI se e mus no change he se e s a e. The e o e, all HAPI endpoin s mus espond
only o HTTP HEAD and GET eques s.
The eques pa ame e s and hei allowed alues mus be s ic ly en o ced by he se e . HAPI se e s
mus no add eques pa ame e s beyond hose in he speci ica ion. I a eques URL con ains any
un ecognized o misspelled eques pa ame e s, a HAPI se e mus espond wi h an e o s a us (see
HAPI S a us Codes o mo e de ails). The p inciple being ollowed is ha he se e mus no silen ly
igno e un ecognized eques pa ame e s because his would alsely indica e o clien s ha he eques

pa ame e was unde s ood and was aken in o accoun when c ea ing he ou pu . Tha is, i a se e is
gi en a eques pa ame e ha is no pa o he HAPI speci ica ion, such as a e agingIn e al=5s, he
se e mus epo an e o o wo easons: 1. addi ional eques pa ame e s a e no allowed, and 2. he
se e will no do any a e aging.
The ou pu s om a HAPI se e o he abou , ca alog, capabili ies, and in o endpoin s a e JSON
objec s, he o ma s o which a e desc ibed below in he sec ions de ailing each endpoin . The da a
endpoin mus be able o deli e Comma Sepa a ed Value (CSV) da a ollowing he RFC 4180 s anda d
[1], bu may op ionally deli e da a con en in bina y o ma o JSON o ma . The esponse s eam
o ma s a e desc ibed in he Da a S eam Con en sec ion.
The ollowing is he de ailed speci ica ion o he i e main HAPI endpoin s as well as he op ional
landing page endpoin .
3.2 hapi
This oo endpoin is op ional and should p o ide a human- eadable landing page o he se e . Unlike
he o he endpoin s, he e is no s ic de ini ion o he ou pu , bu i p esen , i should include a b ie
desc ip ion o he da a and o he endpoin s and links o documen a ion on how o use he se e . An
example landing page ha can be easily cus omized o a new se e is in he Appendix.
The e a e many op ions o landing page con en , such as an HTML iew o he ca alog o links o
commonly eques ed da a.
Sample In oca ion
h p://se e /hapi
Reques Pa ame e s
None
Response
The esponse is in HTML o ma wi h a mime ype o ex /h ml. The e is no speci ica ion o he
con en bu should p o ide an o e iew ha is use ul o science use s.
Example
Re ie e he landing page o his se e .
h p://se e /hapi
Example Response
See he Appendix.
3.3 abou
Sample In oca ion
h p://se e /hapi/abou
Reques Pa ame e s
None
Response
The se e ’s esponse o his endpoin mus be in JSON o ma [3] as de ined by RFC-7159, and he
esponse mus indica e a mime ype o applica ion/json. Se e a ibu es a e desc ibed using
keywo d- alue pai s, wi h he equi ed and op ional keywo ds desc ibed in he ollowing able.
Abou Objec
Name Type Desc ip ion
HAPI s ing Requi ed The e sion numbe o he HAPI speci ica ion his
desc ip ion complies wi h.
s a us S a us
objec Requi ed Se e esponse s a us o his eques .
id s ing
Requi ed A unique ID o he se e . Ideally, his ID has he
o ganiza ion name in i , e.g., NASA/SPDF/SSCWeb,
NASA/SPDF/CDAWeb, INTERMAGNET, UIowa/RPWG,
LASP/TSI, e c. A lis o known ids is a ailable in he se e s
eposi o y.
i le s ing
Requi ed A sho human- eadable name o he se e ha
de ines an ac onym in he id o p o ided addi ional con ex
abou da a se ed (e.g., LASP To al Sola I adiance (TSI)
da a). The sugges ed maximum leng h is 40 cha ac e s. We
ecommend agains including “HAPI” and/o he HAPI
e sion o he se e in he i le.
con ac s ing
Requi ed Con ac in o ma ion o email add ess o se e
issues. HAPI clien s should show his con ac in o ma ion
when i is ce ain ha an e o is due o a p oblem wi h he
se e (as opposed o he clien ). Ideally, a HAPI clien will
ecommend ha he use check hei connec ion and y again
a leas once be o e con ac ing he se e con ac .
desc ip ion s ing Op ional A b ie desc ip ion o he ype o da a he se e
p o ides.
con ac ID s ing
Op ional The iden i ie in he disco e y sys em o
in o ma ion abou he con ac . Fo example, a SPASE ID o a
pe son iden i ied in he con ac s ing.
esou ceID s ing Op ional An iden i ie associa ed wi h all da ase s.
ci a ion s ing Op ional Dep eca ed; use se e Ci a ion.
se e Ci a ion s ing Op ional How o ci e he HAPI se e . An ac ionable DOI is
p e e ed (e.g., h ps://doi.o g/…). This se e Ci a ion
di e s om he da aCi a ion in an /in o esponse. He e he
Name Type Desc ip ion
se e Ci a ion is o he en i y ha main ains he da a
se e .
no e
s ing o
a ay o
s ings
Op ional Gene al no es abou he se e ha a e no
app op ia e o include in desc ip ion. Fo example, a
change log ha lis s added da ase s o pa ame e s in da ase s.
I an a ay o s ings is used o desc ibe da es amped no es,
we ecommend p e ixing he no e wi h a HAPI es ic ed ISO
8601 o ma , e.g., ["2024-01-01T00: No e on his
da e/ ime", "2024-04-02T00: No e on his
da e/ ime"].
wa ning
s ing o
a ay o
s ings
Op ional Tempo a y wa nings abou he da a se e , such as
scheduled down ime and known gene al p oblems. Da ase -
speci ic wa nings should be placed in he wa ning elemen o
he /in o esponse.
da aTes Da aTes
Op ional In o ma ion ha a clien can use o check ha a
se e is ope a ional. Da a esponse should con ain mo e han
ze o eco ds. See below o he de ini ion o his objec .
Da aTes Objec
Name Type Desc ip ion
que y Que y Requi ed See he Que y objec de ini ion below.
name s ing Op ional Name o he es .
A se e es que y hen has he ollowing de ini ion:
Que y Objec
Name Type Desc ip ion
da ase s ing Requi ed S ing iden i ie o he da ase o be used in he es .
s a s ing Requi ed S ing alue o es da a s a ime in es ic ed ISO 8601
o ma .
s op s ing Requi ed S ing alue o es da a s op ime in es ic ed ISO 8601
o ma .
pa ame e s s ing
Op ional A comma-sepa a ed lis o pa ame e s o include in he
esponse (allowed cha ac e s). I no p o ided, all pa ame e s will be
included.
Example
h p://se e /hapi/abou
Example Response:
{ 1
"HAPI": "3.3",2
"s a us": {"code": 1200, "message": "OK"}, 3
"id": "Tes Da a3.3", 4
" i le": "HAPI 3.3 Tes Da a and Me ada a", 5
"con ac ": "[email p o ec ed]",6
"da aTes ": { 7
"name": "Ping Tes ", 8
"que y": { 9
"da ase ": "da ase 1",10
"s a ": "2023-01-01T12:00:00Z",11
"s op": "2023-01-01T14:00:01Z",12
"pa ame e s": "pa ame e 1,pa ame e 2" 13
}14
}15
}16
3.4 capabili ies
This endpoin desc ibes ele an implemen a ion capabili ies o his se e . Cu en ly, he only possible
a iabili y om se e o se e is he lis o ou pu o ma s ha a e suppo ed.
A se e mus suppo he cs ou pu o ma , bu bina y ou pu o ma and json ou pu may op ionally
be suppo ed. Se e s may suppo cus om ou pu o ma s, which would be ad e ised he e. All cus om
o ma s lis ed by a se e mus begin wi h he s ing x_ o indica e ha hey a e cus om o ma s and
a oid naming con lic s wi h possible u u e addi ions o he speci ica ion.
Sample In oca ion
h p://se e /hapi/capabili ies
Reques Pa ame e s
None
Response
The se e ’s esponse o his endpoin mus be in JSON o ma [3] as de ined by RFC 7159, and he
esponse mus indica e a mime ype o applica ion/json. Se e capabili ies a e desc ibed using
keywo d- alue pai s, wi h ou pu Fo ma s being he only keywo d cu en ly in use.
Capabili ies Objec
Name Type Desc ip ion
HAPI s ing Requi ed The e sion numbe o he HAPI speci ica ion
his desc ip ion complies wi h.
Da ase A ibu e Type Desc ip ion
pa ame e s a ay o
Pa ame e Requi ed Desc ip ion o he pa ame e s in he da a.
s a Da e s ing Requi ed Res ic ed ISO 8601 da e/ ime o i s
eco d o da a in he en i e da ase .
s opDa e s ing
Requi ed Res ic ed ISO 8601 da e/ ime o he las
eco d o da a in he en i e da ase . Fo ac i ely
g owing da ase s, he end da e can be app oxima e,
bu i is he se e ’s job o epo an accu a e end
da e.
imeS ampLoca ion s ing
Op ional Indica es he posi ioning o he imes amp
wi hin he measu emen window. Mus be one o
begin, cen e , end o o he . I his a ibu e is
absen , clien s a e o assume a de aul alue o
cen e , which is mean o indica e he exac middle
o he measu emen window. A alue o o he
indica es ha he loca ion o he ime s amp in he
measu emen window is no known o hese op ions
canno be used o an accu a e desc ip ion. See also
HAPI con en ion no es. (No e: e sion 2.0 indica ed
ha hese labels we e in all uppe case. S a ing wi h
e sion 2.1, se e s should use all lowe case.
Clien s, howe e , should be able o handle bo h all
uppe case and all lowe case e sions o hese
labels.)
cadence s ing
Op ional Time di e ence be ween eco ds as an
ISO 8601 du a ion. This is mean as a guide o he
nominal cadence o he da a and no a p ecise
s a emen abou he ime be ween measu emen s.
See also HAPI con en ion no es.
sampleS a Da e s ing
Op ional Res ic ed ISO 8601 da e/ ime o he s a
o a sample ime pe iod o a da ase , whe e he ime
pe iod mus con ain a manageable, ep esen a i e
example o alid, non- ill da a. Requi ed i
sampleS opDa e gi en.
sampleS opDa e s ing
Op ional Res ic ed ISO 8601 da e/ ime o he end
o a sample ime pe iod o a da ase , whe e he ime
pe iod mus con ain a manageable, ep esen a i e
example o alid, non- ill da a. Requi ed i
sampleS a Da e gi en.
maxReques Du a ion s ing Op ional An ISO 8601 du a ion indica ing he
maximum du a ion o a eques . This du a ion
should be in e p e ed by clien s as a limi abo e
which a eques o all pa ame e s will e y likely be

Da ase A ibu e Type Desc ip ion
ejec ed wi h a HAPI 1408 e o ; eques s o ewe
pa ame e s and a longe du a ion may o may no be
ejec ed.
desc ip ion s ing
Op ional A de ailed desc ip ion o he da ase
con en , ca ea s, ela ionships o o he da a,
e e ences and links – he in o ma ion use s need o
know o a basic in e p e a ion o he da a.
Sugges ed leng h is a ew lines o ex , e.g., 1000
cha ac e s; ex ended de ails can be e e enced wi h
links.
uni sSchema s ing
Op ional The name o he uni s con en ion ha
desc ibes how o pa se all uni s s ings in his
da ase . Cu en ly, he only allowed alues a e:
uduni s2, as opy3, and cd -clus e . See
uni sSchema De ails o addi ional in o ma ion
abou hese con en ions. The lis o allowed uni
speci ica ions is expec ed o g ow o include o he
well-documen ed uni s anda ds.
coo dina eSys emSchema s ing
Op ional The name o he schema o con en ion
ha con ains a lis o coo dina e sys em names and
de ini ions. I his keywo d is p o ided, any
coo dina eSys emName keywo d gi en in a
pa ame e de ini ion should ollow his schema. See
coo dina eSys emSchema De ails o addi ional
in o ma ion.
loca ion objec
Op ional A way o speci y whe e a da ase ’s
measu emen s we e made. See loca ion and
geoLoca ion De ails o an explana ion o he wo
ways o indica e loca ion: one o a ixed loca ion
and one o when he measu emen loca ion changes
wi h ime.
geoLoca ion a ay o
double
Op ional A simpli ied, compac way o indica ing a
ixed loca ion o a da ase in Ea h-based
coo dina es. The a ay has 2 o 3 elemen s:
[longi ude in deg ees, la i ude in deg ees, (op ional)
al i ude in me e s]. Fo in o ma ion and examples,
see loca ion and geoLoca ion De ails.
esou ceURL s ing Op ional URL linking o mo e de ailed in o ma ion
abou his da ase .
esou ceID s ing Op ional An iden i ie by which his da a is known
in ano he se ing (e.g., DOI)
c ea ionDa e s ing Op ional Res ic ed ISO 8601 da e/ ime o he
Da ase A ibu e Type Desc ip ion
da ase c ea ion.
ci a ion s ing Op ional Dep eca ed; use da ase Ci a ion.
da ase Ci a ion s ing
Op ional How o ci e he da a se . An ac ionable
DOI is p e e ed (e.g., h ps://doi.o g/…). No e ha
he e is a se e Ci a ion in an /abou esponse o
ci ing he da a se e , bu da ase Ci a ion is o
he da ase ci a ion, which is ypically di e en .
licenseURL
s ing o
a ay o
s ings
Op ional A URL o a ay o URLs o a license
landing page. I he license is in he spdx.o g lis ,
p o ide a link o i . A lis o licenses implies ha
use s may choose any one om he lis .
p o enance s ing Op ional A desc ip ion o he p o enance o his
da ase .
modi ica ionDa e s ing
Op ional Res ic ed ISO 8601 da e/ ime o he las
modi ica ion o me ada a and/o da a has changed.
(Use his o signal ha any con en o he da ase in
he ull ime ange o da a has changed; mo e
g anula i y may be possible in he u u e, see (issue
218)[h ps://gi hub.com/hapi-se e /da a-
speci ica ion/issues/218].)
con ac s ing
Op ional Rele an con ac pe son name (and
possibly con ac in o ma ion) o science ques ions
abou he da ase .
con ac ID s ing
Op ional The iden i ie in he disco e y sys em o
in o ma ion abou he con ac . Fo example, he
SPASE ID o ORCID o he pe son.
addi ionalMe ada a objec
Op ional A way o include a block o o he (non-
HAPI) me ada a. See below o a desc ip ion o he
objec , which can di ec ly con ain he me ada a o
poin o i ia a URL.
de ini ions objec Op ional An objec con aining de ini ions ha a e
e e enced using a JSON e e ence
no e
s ing o
a ay o
s ings
Op ional Gene al no es abou he da ase ha a e
inapp op ia e o include in desc ip ion. Fo
example, a change log ha lis s added pa ame e s. I
an a ay o s ings is used o desc ibe da es amped
no es, we ecommend p e ixing he no e wi h a
HAPI es ic ed ISO 8601 o ma , e.g., ["2024-01-
01T00: No e on his da e ime", "2024-04-
02T00: No e on his da e ime"].
Da ase A ibu e Type Desc ip ion
wa ning
s ing o
a ay o
s ings
Op ional Tempo a y wa nings abou he da ase ,
such as “da ase s opDa e is ypically upda ed
con inuously, bu …”
3.6.3 uni sSchema De ails
One op ional a ibu e is uni sSchema. This allows a se e o speci y, o each da ase , wha con en ion
is ollowed o he uni s s ings in he pa ame e s o he da ase . Cu en ly, he only allowed alues o
uni sSchema a e: uduni s2, as opy3, and cd -clus e . These ep esen he cu en ly known se o
uni con en ions wi h so wa e a ailable o pa sing and in e p e ing uni s ings. Only majo e sion
numbe s (i a ailable) a e indica ed in he con en ion name. I is expec ed ha his lis will g ow o e
ime as needed. The cu en loca ions o he o icial de ini ions and so wa e ools o in e p e ing he
a ious uni con en ions a e in he ollowing able:
Con en ion
Name Cu en URL
Desc ip ion (con ex
help i link is
b oken)
uduni s2 h ps://www.unida a.uca .edu/so wa e/uduni s
Unida a om UCAR;
a C lib a y o uni s o
physical quan i ies
as opy3 h ps://docs.as opy.o g/en/s able/uni s/
package inside
as opy ha handles
de ining, con e ing
be ween, and
pe o ming a i hme ic
wi h physical
quan i ies, such as
me e s, seconds, Hz,
e c
cd -
clus e
h ps://caa.esac.esa.in /documen s/DS-QMW-TN-
0010.pd which is e e enced on his page:
h ps://www.cosmos.esa.in /web/csa/documen a ion
con en ions c ea ed
and used by ESA’s
Clus e mission
ouni s1.1 h ps://www.i oa.ne /documen s/VOUni s/
IVOA
Recommenda ion o
Uni s in he VO
3.6.4 coo dina eSys emSchema De ails
The pa ame e objec (desc ibed below) allows o a coo dina eSys emName o be associa ed wi h any
pa ame e . To allow a p ecise and compu e - eadable meaning o hese coo dina e sys em names, a
da ase can ha e a coo dina eSys emSchema. This schema should con ain a compu e - eadable and
publically a ailable lis o coo dina e sys em names and de ini ions. Few such schemas exis . One
sugges ed schema designa ion o Heliophysics is p o ided in he ollowing able. I mo e communi y-
app o ed schemas eme ge o coo dina e sys ems, hen hey could be included in he able, and i hese
schemas become widely adop ed, i migh make sense in he u u e o es ic coo dina eSys emSchema
o a se o enume a ed alues, bu o now i is uncons ained.
Schema
Name URL Desc ip ion
spase2.4.1
h ps://spase-
g oup.o g/da a/schema/spase-
2.4.1.xsd
Schema con aining he names and
de ini ions o coo dina e sys ems
commonly used in Heliophysics. See also
an ΗΤΜL e sion o ele an sec ion o
schema.
This schema cap u es a Heliophysics-speci ic lis o coo dina e sys ems and is pa o he la ge SPASE
me ada a model (also Heliophysics-speci ic). I se es as an example o how a publically accessible lis
o coo dina e ames can be e e enced by he coo dina eSys emSchema keywo d. Di e en
communi ies can e e ence hei schemas.
Wi hin he pa ame e objec is he coo dina eSys emName keywo d, which con ains he name o he
coo dina e sys em (mus be om he schema). The e is also he ec o Componen s keywo d o cap u e
he de ails abou which coo dina e componen s a e p esen in he pa ame e . See he desc ip ion below
( he ec o Componen s sec ion) o de ails on how o desc ibe pa ame e s ha con ain di ec ional (i.e.,
ec o ) quan i ies.
3.6.5 addi ionalMe ada a Objec
HAPI allows o bulk inclusion o addi ional me ada a ha may exis o a da ase . Addi ional me ada a
keywo ds can be inse ed by p e ixing hem wi h x_ (which indica es ha he elemen is no pa o he
HAPI s anda d), bu his means any o iginal me ada a would ha e o modi y i s keywo ds.
The addi ionalMe ada a objec is a lis o objec s ep esen ed by he able below and allows o one o
mo e se s o addi ional me ada a, which can be isola ed om each o he and HAPI keywo ds.
{
"addi ionalMe ada a" : [ md1, md2, md3 ]
}
The e can be one o mo e me ada a objec s (md1, md2, md3, e c abo e) in he lis , and he keywo ds o
hese objec s a e as ollows:
Keywo d Type Desc ip ion
name s ing Op ional he name o he addi ional me ada a
con en
s ing o
JSON
objec
Requi ed (i no con en URL) ei he a s ing wi h he me ada a
con en ( o XML), o a JSON objec ep esen ing he objec ee
o he addi ional me ada a
con en URL s ing Requi ed (i no con en ) URL poin ing o addi ional me ada a
schemaURL s ing Op ional poin s o compu e - eadable schema o he addi ional
me ada a
abou URL s ing Op ional poin s o human- eadable explana ion o he me ada a
The name is app op ia e i he addi ional me ada a ollows a known s anda d ha people know abou .
One o con en o con en URL mus be p esen . The con en can be a s ing e sion o he ac ual
me ada a o a JSON objec ee. I he e is a schema e e ence embedded in he me ada a (easy o do
wi h XML and JSON), clien s can igu e ha ou , bu i no in e nal schema is in he me ada a, hen he
schemaURL can poin o an ex e nal schema. The abou URL is o humans o lea n abou he gi en ype o
addi ional me ada a.
Fo he name, please use hese i app op ia e CF, FITS, ISTP, SPASE. O he ields beyond Heliophysics
will likely ha e hei me ada a names, which could be lis ed he e i eques ed.
Example
{ 1
"addi ionalMe ada a" : [ 2
{ "name": "SPASE", 3
"con en URL": "h ps://hpde.io/NASA/DisplayDa a/ACE/MAG/27-Day.xml", 4
"abou URL": "h p://spase-g oup.o g" 5
}, 6
{ "name": "CF", 7
"con en ": { "keywo d" : " alue1", "keywo d2": " alue2" }, 8
"abou URL": "h ps://c con en ions.o g/" 9
}, 10
{ "name": "ISTP",11
"con en ": { "json objec (no shown) ep esen ing he ee o ISTP
keywo d- alue pai s" },
12
"abou URL": "h ps://spd .gs c.nasa.go /is p_guide/ a iables.h ml" 13
}, 14
{ "name": "FITS",15
"con en ": { " i s_heade _keywo d1" : " alue1", " i s_heade _keywo d2":
" alue2" },
16
"abou URL": "h p:// i s.gs c.nasa.go " 17
}18
]19
}20
No e ha no single da ase would likely ha e his a ie y o addi ional me ada a – hese a e p o ided o
illus a ion.
3.6.6 s ingType Objec
s ingType is an op ional elemen wi hin each pa ame e objec , and i allows se e s o indica e ha a
s ing pa ame e has a special in e p e a ion.
Cu en ly, he only special s ingType allowed is a URI, and i can be used o indica e ha a s ing
pa ame e con ains a ime se ies o links o esou ces (poin ed o by he URIs).
The main use o HAPI is se ing nume ic da a, bu he abili y o also se e URIs ha poin o da a opens
up wo use cases o HAPI se e s.

1. Se ing image URIs. In his case, he images should be in a widely ecognized o ma ha could be
easily in e p e ed by lib a ies a ailable o many clien s, such as JPG, PNG, e c.
2. Se ing da a ile URIs o p o ide a lis o iles used o cons uc a HAPI nume ic da a esponse. Fo
example, i a se e has a da ase named da ase 1, he iles used o cons uc a eques o da ase 1
could be p o ided in a da ase named da ase 1Files. In his case, a use can eques da ase 1 o e
a ime ange and de e mine wha iles da ase 1 came om using a eques o da ase 1Files o e
he same ime ange.
I is emphasized ha a HAPI se e ha p o ides only da ase s wi h da a ile URIs ha con ain ime
se ies da a ha could be se ed as HAPI nume ic da a is no ecommended. HAPI clien s should
only need o ead a HAPI s eam and no ha e o ead and pa se da a in a bi a y ile o ma s.
A ecommended p ac ice in bo h cases is also o include columns ha p o ide me ada a alues.
The s ingType a ibu e can ei he ha e a simple alue ha is jus he s ing u i, o i can be an objec
ha is a dic iona y wi h u i as he key and a alue ha is ano he objec wi h h ee op ional elemen s:
mediaType, scheme, and base. Thus a s ingType will ha e one o he ollowing o ms:
"s ingType": "u i"
o
"s ingType": { 1
"u i": { 2
"mediaType": "image/png",3
"scheme": "h ps", 4
"base":
"h ps://cdaweb.gs c.nasa.go /pub/p e_gene a ed_plo s/de/pwi/"
5
} 6
} 7
The u i objec a ibu es a e:
s ingType
A ibu e Type Desc ip ion
mediaType s ing Op ional indica es con en ype behind he URI (also e e ed o
as MIME ype)
scheme s ing Op ional he access p o ocol o he URI
base s ing Op ional allows each URI s ing alue o be ela i e o a base
URI
The media ype indica es he ype o da a each URI poin s o. HAPI places no cons ain s on he alues
o mediaType, bu se e s should only use s anda d alues, such as image/ i s, ‘
image/pngo applica ion/x-cd `. The e a e s anda d lis s o media ypes a ailable, and we do no epea
hem in he HAPI speci ica ion.
The scheme desc ibes he access p o ocol. Again, he e a e no es ic ions, bu he e is an expec a ion
ha i should be a well-known p o ocol, such as h p o h ps o p o doi o s3 (used o Amazon
objec s o es).
The base allows he indi idual s ing alues o he pa ame e o be ela i e o a base URI, ypically a
web-accessible loca ion ending in a slash.
URIs should ollow he syn ax ou lines in RFC 3986. The basic pa e n is:
URI = scheme ":" ["//" au ho i y] pa h ["?" que y] ["#" agmen ]
URI s ings should no be encoded because his is wha mos clien s expec , and clien s ypically do hei
own encoding o a URI be o e issuing a eques o e ie e he con en .
The uni s o a s ing pa ame e ha is a URI should be null. The uni s alue he e should no be used o
y and desc ibe he con en s behind he URIs. URI con en is likely oo a iable o be uni o mly handled
by his simple uni s indica o .
Example:
"pa ame e s": 1
[ { "name": "Time", 2
" ype": "iso ime", 3
"uni s": "UTC",4
" ill": null, 5
"leng h": 24 6
}, 7
{ "name": "sola _images",8
"desc ip ion": " ull-disk images o he Sun by SDO/AIA a wa eleng h o
304 angs oms",
9
" ype": "s ing",10
"leng h": 64,11
"s ingType": {"u i": {"mediaType": "image/ i s", "scheme": "h ps"}}, 12
"uni s": null,13
" ill": null 14
}, 15
{ "name": "cadence",16
"desc ip ion": " ime be ween images",17
" ype": "double",18
"uni s": "sec",19
" ill": "-999" 20
}, 21
{ "name": "wa eleng h",22
"desc ip ion": "which wa eleng h il e was ac i e o his image",23
" ype": "double",24
"uni s": "angs om",25
" ill": "NaN" 26
}, 27
{ "name": "con ains_ac i e_ egion",28
"desc ip ion": "boolean indica o o ac i e egion p esence: 0=no,
1=yes",
29
" ype": "in ege ",30
"uni s": null,31
" ill": "NaN" 32
} 33
]34
This example shows wha he pa ame e s po ion o a HAPI in o esponse would look like o a se o
sola images. The pa ame e name sola _images is gi en a s ingType o u i and has a mediaType
and scheme speci ied. No base is gi en, so he URIs mus be ully quali ied. The e a e also o he
pa ame e s (cadence, wa eleng h, and con ains_ac i e_ egion) ha could be used on he clien side
o il e ing he images based on he alues o hose pa ame e s.
The app oach shown he e emphasizes a use ul way o HAPI o p o ide image lis s. HAPI que ies can
only cons ain a se o images by ime, bu i he esponse con ains me ada a alues in o he columns,
clien s can es ic he image lis u he by il e ing on alues in he me ada a columns.
3.6.7 pa ame e Objec
The ocus o he heade is o lis he pa ame e s in a da ase . The i s pa ame e in he lis mus be a ime
alue. This ime column se es as he independen a iable o he da ase . The ime column pa ame e
may ha e any name, bu i s ype mus be iso ime, and he e mus no be any ill alues in he da a
s eam o his column. No e ha he HAPI speci ica ion does no cla i y i he ime alues gi en a e he
s a , middle, o end o he measu emen in e als. The e can be o he pa ame e s o ype iso ime in he
pa ame e lis . The able below desc ibes he pa ame e objec a ibu es.
Pa ame e A ibu e Type Desc ip ion
name s ing
Requi ed A sho name o his pa ame e . Each
pa ame e mus ha e a unique name. I is ecommended
ha all pa ame e names s a wi h a le e o unde sco e,
ollowed by le e s, unde sco es, o numbe s. This allows
he pa ame e names o become a iable names in
compu e languages. Pa ame e names in a da ase mus
be unique, and names a e no allowed o di e only by
ha ing a di e en case. No e ha because pa ame e
names can appea in URLs ha can se e as pe manen
links o da a, changing hem will ha e nega i e
implica ions, such as b eaking links o da a. The e o e,
pa ame e names should be s able o e ime.
ype s ing
Requi ed One o s ing, double, in ege , o iso ime.
Bina y con en o double is always 8 by es in IEEE 754
o ma , in ege is 4 by es signed li le-endian. The e is
no de aul leng h o s ing o iso ime ypes. S ing
pa ame e s may include UTF-8 encoded Unicode
cha ac e s. S ings may be lagged as ep esen ing URIs -
see he op ional s ingType a ibu e in his able.
leng h in ege Requi ed Fo ype s ing and iso ime; no allowed o
o he s. The maximum numbe o by es ha he s ing
may con ain. I he esponse o ma is bina y and a s ing
has ewe han his maximum numbe o by es, he s ing
mus be padded wi h ASCII null by es. I he s ing
pa ame e con ains only ASCII cha ac e s, leng h means
he maximum numbe o ASCII cha ac e s. I a s ing
pa ame e con ains UTF-8 encoded Unicode cha ac e s,
leng h means he maximum numbe o by es equi ed o
ep esen all o he cha ac e s. Fo example, i a s ing
pa ame e can be A o α leng h: 2 is equi ed because α
in Unicode equi es wo by es when encoded as UTF-8.
HAPI clien s ha ead CSV ou pu om a HAPI se e
will gene ally no need o use he leng h pa ame e .
Howe e , o HAPI bina y, he leng h pa ame e is
Example
{ 1
"HAPI": "3.3",2
"s a us": {"code": 1200, "message": "OK"}, 3
"s a Da e": "1998-001Z", 4
"s opDa e" : "2017-100Z", 5
"pa ame e s": [ 6
{ "name": "Time", 7
" ype": "iso ime", 8
"uni s": "UTC", 9
" ill": null,10
"leng h": 24 }, 11
{ "name": " adial_posi ion",12
" ype": "double",13
"uni s": "km",14
" ill": null,15
"desc ip ion": " adial posi ion o he spacec a ",16
"label": "R Posi ion"}, 17
{ "name": "quali y_ lag",18
" ype": "in ege ",19
"uni s": "none",20
" ill": null,21
"desc ip ion ": "0=OK and 1=bad " }, 22
{ "name": "mag_GSE",23
"desc ip ion": "B ield as magni ude and wo angles he a (cola i ude)
and phi (longi ude)",
24
" ype": "double",25
"size" : [3], 26
"coo dina eSys emName": "GSE",27
" ec o Componen s": [ " ", "cola i ude", "longi ude" ], 28
"uni s": ["nT","deg ees", "deg ees"], 29
"label": ["B Magni ude", " he a", "phi"], 30
" ill": "-1e31" } 31
]32
}33
Each elemen in he s ing a ay applies o he co esponding elemen in he mag_GSE da a a ay.
The ollowing a e examples o uni s and label alues o a pa ame e o size=[2,3]. The pa ame e
is ec o eloci y om wo sepa a e ins umen s. In a JSON esponse, he pa ame e a a gi en ime
would ha e he o m

["2017-11-13T12:34:56.789Z", [ [1, 2, 3] [4, 5, 6] ] ]
The [1,2,3] a e measu emen s om he i s ins umen and he [4, 5, 6] a e measu emen s om he
second ins umen .
Allowed (scala o uni s and o label applies o all elemen s in he a ay)
"size": [2,3]
"uni s": "m/s",
"label": " eloci y"
Allowed (scala uni s applied o all six elemen s in he a ay; unique label o each elemen )
"size": [2,3],
"uni s": "m/s",
"label": [["V1x","V1y","V1z"],["V2x","V2y","V2z"]]
Allowed (a ay o leng h 1 is ea ed like scala ; no p e e ed bu allowed)
"size": [2,3]
"uni s": ["m/s"],
"label": [["V1x","V1y","V1z"],["V2x","V2y","V2z"]]
Allowed (all elemen s a e p ope ly gi en hei own uni s s ing)
"size": [2,3],
"uni s": [["m/s","m/s","km/s"],["m/s","m/s","km/s"]],
"label": [["V1x","V1y","V1z"],["V2x","V2y","V2z"]]
No Allowed (a ay size does no ma ch pa ame e size – mus speci y all uni s elemen s i no jus
gi ing a scala )
"size": [2,3],
"uni s": ["m/s","m/s","km/s"],
"label": [["V1x","V1y","V1z"],["V2x","V2y","V2z"]]
No Allowed (uni s a ay size does no ma ch pa ame e size)
"size": [2,3]
"uni s": ["m/s",["m/s","m/s","km/s"]],
"label": [["V1x","V1y","V1z"],["V2x","V2y","V2z"]]
3.6.11 ec o Componen s Objec
Fo a pa ame e ha desc ibes a ec o - ela ed quan i y (posi ion o spacec a ela i e o a body,
loca ion o g ound s a ion, di ec ion o measu ed ec o quan i y, de ec o look di ec ion), he
ec o Componen s keywo d indica es he ec o - ela ed componen s p esen in he da a. Fo a scala
pa ame e ha is associa ed wi h a ec o componen , his keywo d con ains a single s ing desc ibing
he componen . Fo non-scala pa ame e s, his keywo d con ains an a ay o s ings naming he
coo dina e alues p esen in he pa ame e .
The names ep esen he ma hema ical componen s ypically ound in ec o o posi ional quan i ies.
Possible componen names a e cons ained o be one o he ollowing:
Componen
Name Meaning
xCa esian x componen o ec o
yCa esian y componen o ec o
zCa esian z componen o ec o
Magni ude o ec o
ho Magni ude o adial componen (pe pendicula dis ance om z-axis) in a
Cylind ical coo dina e ep esen a ion
la i ude Angle ela i e o x-y plane om -90° o 90°, o -π o π (90° co esponds o +z
axis)
cola i ude Angle ela i e o +z axis, om 0 o 180°, o 0 o π
longi ude
Angle ela i e o +x axis o a p ojec ion o he ec o in o he x-y plane, om
-180° o 180°, o -π o π (90° co esponds o +y axis; his is also known as
“Eas longi ude”)
longi ude0
Angle ela i e o +x axis o a p ojec ion o he ec o in o he x-y plane, om
0° o 360°, o 0 o 2π (270° co esponds o -y axis; his is also known as “Eas
longi ude”)
al i ude
Al i ude abo e a e e ence sphe e o su ace as iden i ied in
coo dina eSys emName. Fo example, Ea h’s loca ions a e o en desc ibed by
longi ude, la i ude, and al i ude.
o he Any pa ame e componen ha canno be desc ibed by a name in his lis
No e ha ec o Componen s should be in e p e ed as desc ibing ec o - ela ed elemen s. In some
ins ances, he ec o Componen s will desc ibe a p ope ec o (e.g., i ec o Componen s = ["x",
"y", "z"]).
Many angula quan i ies in da ase s ha e di e en names han he ones he e (azimu h ins ead o
longi ude, o ele a ion o inclina ion ins ead o la i ude), bu mos quan i ies di ec ly map o hese
commonly used componen names, which come om sphe ical o cylind ical coo dina e sys ems. A
u u e e sion o HAPI may o e a way o ep esen o he angula componen s.
The ollowing pa ame e objec o an /in o esponse (bu no a ull /in o esponse) demons a es he
use o di ec ional quan i ies.
"pa ame e s": [ 1
{ "name": "spacec a Loca ionXYZ", 2
"desc ip ion": "S/C loca ion in X,Y,Z; ec o di ec ion om cen e o
Ea h o spacec a ",
3
"size": [3], 4
"uni s": "km", 5
"coo dina eSys emName": "GSM", 6
" ec o Componen s": ["x", "y", "z"] }, 7
8
{ "name": "spacec a Loca ionSphe ical", 9
"desc ip ion": "posi ion in R, MLT and magne ic la i ude", 10
"size": [3], 11
"uni s": ["Re", "hou s", "deg ees" ], 12
"coo dina eSys emName": "GSM", 13
" ec o Componen s": [" ", "longi ude", "la i ude"] }, 14
15
{ "name": "magne ic_ ield", 16
"desc ip ion": "mag ec o in Ca esian coo ds; componen s a e x,y,z
which is he assumed de aul o size [3]",
17
"size": [3], 18
"uni s": "nT", 19
"coo dina eSys emName": "GSM" }, 20
21
{ "name": "magne ic_ ield_cylind ical", 22
"desc ip ion": "mag ec o in cylind ical coo ds", 23
"size": [3], 24
"uni s": ["nT","deg ees", "nT"], 25
"coo dina eSys emName": "GSM", 26
" ec o Componen s": [" ho", "longi ude", "z"] }, 27
28
{ "name": "Bx", 29
"desc ip ion": "mag X componen ", 30
"uni s": "nT", 31
"coo dina eSys emName": "GSE", 32
" ec o Componen s": "x" }, 33
34
{ "name": "By", 35
"desc ip ion": "mag Y componen ", 36
"uni s": "nT", 37
"coo dina eSys emName": "GSE", 38
" ec o Componen s": "y" }, 39
40
{ "name": "Bz", 41
"desc ip ion": "mag Z componen ", 42
"uni s": "nT", 43
"coo dina eSys emName": "GSE", 44
" ec o Componen s": "z" }, 45
46
]47
In his example, he spacec a posi ion is p o ided in wo di e en ways, Ca esian and sphe ical. The
de aul alue o ec o Componen s is ["x", "y", "z"], and so i may be included i desi ed, as is he
case wi h he i s posi ion pa ame e , spacec a Loca ionXYZ, o omi ed as is shown o he
magne ic_ ield pa ame e . I he uni s p o ided is a scala , i applies o all componen s o he
pa ame e ( his is ue ega dless o whe he he pa ame e is a ec o ). The pa ame e
magne ic_ ield_cylind ical is indeed in cylind ical coo dina es, so i does lis speci ic ec o
componen s o [" ho", "longi ude", "z"], and since he uni s o each componen a e no he same,
hose a e lis ed in an a ay as ["nT", "deg ees", "nT"].
No e ha he longi ude uni s o he spacec a Loca ionSphe ical pa ame e a e hou s. This mus
be a loa ing poin alue o cap u e ac ions o hou s, no a s ing wi h hou s, minu es, and seconds. So,
wi hin he da a alues o his pa ame e componen , 20.5 would be an in e p e able alue o 20 hou s
30 minu es, bu 20:30:00 would no be ok.
The las h ee pa ame e s in his example (Bx, By, and Bz) illus a e how a ec o quan i y can be sp ead
ac oss mul iple scala pa ame e s. The ec o Componen s a ibu e iden i ies which componen is in he
pa ame e . All ele an componen s would need o be manually combined o c ea e he ec o quan i y.
3.6.12 loca ion and geoLoca ion De ails
Some da ase s ha e pa ame e s whose measu emen s a e associa ed wi h a ixed loca ion. O he
measu emen s a e made om loca ions ha change wi h ime. The loca ion a ibu e can exp ess he
loca ion o measu emen s ei he as a single, ixed loca ion, o as loca ion alues ha change wi h ime.
An al e na i e a ibu e, geoLoca ion, can be used ins ead as a compac way o desc ibing an Ea h-
based posi ion o a da ase ’s measu emen s. Only loca ion o geoLoca ion should be used, no bo h.
Fo he case o a ixed loca ion on Ea h, he geoLoca ion a ibu e concisely ep esen s a poin loca ion
wi h an a ay o longi ude, la i ude, and op ionally al i ude.
"geoLoca ion": [longi ude, la i ude]
-OR-
"geoLoca ion": [longi ude, la i ude, al i ude]
Angles in geoLoca ion mus be in deg and al i ude in m and he coo dina e sys em is WGS84 (see
Geode ic Coo dina e Sys ems). This makes geoLoca ion consis en wi h he GeoJSON speci ica ion o
a poin loca ion.
As an example, he loca ion o measu emen s made by a hypo he ical magne ome e a he peak o
Suga loa Moun ain in Ma yland, USA, could be ep esen ed as:
"geoLoca ion": [-77.395, 39.269, 391.0]

Fo a ixed loca ion exp essed in a di e en coo dina e sys em, o wi h o he ec o componen s o he
loca ion, use a loca ion objec wi h hese ou a ibu es:
loca ion A ibu e Type Desc ip ion
poin
double o
double
a ay
Requi ed alues o speci y he loca ion
ec o Componen s
s ing o
s ing
a ay
Requi ed he kind o ec o Componen s alues in he
poin a ay. Numbe o alues should ma ch wha is in
poin .
uni s
s ing o
s ing
a ay
Requi ed uni s s ing o s ings o he
ec o Componen s alues. To see how uni s a e
applied o scala s o a ays, see he sec ion abou uni s
and a ays
coo dina eSys emName s ing Requi ed he name o he coo dina e sys em o he
ec o Componen s quan i ies
I a uni sSchema has been speci ied o his da ase , any s ing gi en o he uni s mus be consis en
wi h ha schema. Simila ly, i a coo dina eSys emSchema has been speci ied o his da ase , any s ing
gi en o he coo dina eSys emName mus be consis en wi h ha schema.
Examples
A e bose e sion o "geoLoca ion": [-77.395, 39.269, 391.0]:
"loca ion": { 1
"poin ": [-77.395, 39.269, 391.0], 2
" ec o Componen s": ["longi ude", "la i ude", "al i ude"], 3
"uni s": ["deg", "deg", "m"], 4
"coo dina eSys emName": "wgs84" 5
}6
Loca ion in non-WGS84 coo dina e sys em and wi h ca esian ec o componen s:
"loca ion": { 1
"poin ": [-4.1452e3, 1.2050e3, 0.10201e3], 2
" ec o Componen s": ["x", "y", "z"], 3
"uni s": "km",4
"coo dina eSys emName": "GSE" 5
} 6
No e ha in he second example, he uni s alue o km applies o all componen s elemen s.
Time-Va ying Loca ions
I a da ase has pa ame e s whe e he measu emen loca ion changes o e ime, he loca ion objec can
indica e he names o o he pa ame e s in he da ase ha con ain he co esponding ime- a ying
loca ions. I he ime- a ying posi ion is p esen in mo e han one coo dina e sys em, each can be
e e enced. The e o e, he loca ion a ibu e is an a ay (ou e a ay) consis ing o a lis o inne a ays
o s ing pa ame e names. I a pa ame e con aining loca ion in o has all he ec o Componen s in i o
ully ep esen he loca ion, hen he inne a ay will ha e jus one elemen : he name o he ully
su icien pa ame e . I he posi ion in o o one coo dina e sys em is sp ead o e mul iple pa ame e s,
hen each pa ame e name needs o be in he inne a ay.
"loca ion": {
"pa ame e s": [ ["pa am_name_ o _loca ion_using_coo d_sys_A"],
["pa am_name_ o _loca ion_using_coo d_sys_B"] ]
# each pa ame e he e mus be a ec o and ha e in i s a ibu es a ull se
o ` ec o Componen s` o desc ibe he ec o
}
Examples help illus a e:
"loca ion": {
"pa ame e s": [ ["Loca ion_GEO"], ["Loca ion_GSE"] ]
}
In his i s example, wo pa ame e s p o ide posi ion in o, each in a di e en coo dina e sys em. Wi hin
he de ini ion o each loca ion pa ame e , he e mus be a ec o Componen desc ip ion.
loca ion: { 1
"pa ame e s": [ ["Loca ion_GEO_X", "Loca ion_GEO_Y", "Loca ion_GEO_Z], 2
["Loca ion_J2000_X", "Loca ion_J2000_Y", "Loca ion_J2000_Z"] 3
] 4
}5
In his second example, he e a e also wo coo dina e sys ems, bu each one is exp essed ac oss h ee
pa ame e s, one each o he x, y, and z alues o he posi ion.
3.6.13 bins Objec
The bins a ibu e o a pa ame e is an a ay o JSON objec s wi h he ollowing a ibu es.
Bins
A ibu e Type Desc ip ion
name s ing Requi ed Name o he dimension (e.g.
“F equency”).
cen e s a ay o n doubles Requi ed i no anges The cen e s o each bin ange.
anges a ay o n a ays o 2
doubles
Requi ed i no cen e s The bounda ies o each bin
(a ay o [min, max]).
uni s s ing Requi ed The uni s o he bin anges and/o cen e
alues.
Bins
A ibu e Type Desc ip ion
label s ing Op ional A label app op ia e o a plo (use i name is
no app op ia e)
desc ip ion s ing Op ional B ie commen explaining wha he bins
ep esen .
No es:
A leas one o anges and cen e s mus be gi en.
Some dimensions o a mul i-dimensional pa ame e may no ep esen binned da a. Each dimension
mus be desc ibed in he bins objec , bu any dimension no ep esen ing binned da a should indica e
his by using "cen e s": null and no including he ' anges' a ibu e.
Bin cen e s and/o anges may depend on ime (bu he numbe o cen e s and/o anges may no
change), see he desc ip ion o ime- a ying bins la e in his sec ion.
Bin cen e s and/o anges may no depend on non– ime dimensions. Fo example, suppose he
pa ame e dimensions a e ime, ene gy and pi ch angle. The pi ch angle bin cen e s and/o anges
canno depend on he ene gy bins.
Example
"pa ame e s": 1
[ 2
{ 3
"name": "Time",4
" ype": "iso ime", 5
"uni s": "UTC", 6
" ill": null, 7
"leng h": 24 8
}, 9
{10
"name": "P o ons_10_ o_20_keV_pi ch_angle_spec og am",11
" ype": "double",12
"uni s": "1/(cm^2 s^2 s e keV)",13
" ill": "-1.0e31",14
"size": [6], 15
"bins": [{ 16
"name": "angle_bins",17
" anges": [ 18
[0.0, 30.0], 19
[30.0, 60.0], 20
[60.0, 90.0], 21
[90.0, 120.0], 22
[120.0, 150.0], 23
[150.0, 180.0]24
], 25
"uni s": "deg ees",26
"label": "Pi ch Angle" 27
}] 28
}29
]30
The da a gi en o cen e s and anges mus no con ain any null o missing alues. The numbe o
alid numbe s in he cen e s a ay and he numbe o alid min/max pai s in he anges a ay mus
ma ch he size o he pa ame e dimension being desc ibed. So his is no allowed:
In alid
cen e s = [2.0, 3.0, 4.0],
anges = [[1.0, 3.0], null, [3.0, null]]
In alid
cen e s = [2.0, 3.0, null]
{ 1
"HAPI": "3.3", 2
"s a us": { 3
"code": 1200,4
"message": "OK" 5
}, 6
"s a Da e": "2016-01-01T00:00:00.000Z", 7
"s opDa e": "2016-01-31T24:00:00.000Z",8
"de ini ions": { 9
"spec um_uni s": "pa icles/(sec s e cm^2 keV)",10
"spec um_uni s_explici ": ["pa icles/(sec s e cm^2
keV)","pa icles/(sec s e cm^2 keV)","pa icles/(sec s e cm^2
keV)","pa icles/(sec s e cm^2 keV)"],
11
"spec um_bins_cen e s": [15, 25, 35, 45], 12
"spec um_bins": { 13
"name": "ene gy",14
"uni s": "keV",15
"cen e s": [15, 25, 35, 45]16
}17
}, 18
"pa ame e s": [{ 19
"name": "Time",20
" ype": "iso ime",21
"uni s": "UTC",22
" ill": null,23
"leng h": 24 24
}, 25
{26
"name": "p o on_spec um",27
" ype": "double",28
"size": [4], 29
"uni s": {"$ e ": "#/de ini ions/spec um_uni s"}, 30
" ill": "-1e31",31
"bins": [{ 32
"name": "ene gy",33
"uni s": "keV",34
"cen e s": {"$ e ": "#/de ini ions/spec um_bins_cen e s"}35
}] 36
}, 37
{38
"name": "p o on_spec um2",39

" ype": "double",40
"size": [4], 41
"uni s": {"$ e ": "#/de ini ions/spec um_uni s"}, 42
"bins": [ 43
{"$ e ": "#/de ini ions/spec um_bins"}44
]45
}, 46
{47
"name": "p o on_spec um3",48
" ype": "double",49
"size": [4], 50
"uni s": {"$ e ": "#/de ini ions/spec um_uni s_explici "}, 51
"bins": [ 52
{"$ e ": "#/de ini ions/spec um_bins"}53
]54
}55
]56
}57
3.7 da a
This endpoin p o ides access o a da ase and allows o selec ing ime anges and pa ame e s o e u n.
Da a is e u ned as a CSV [2], bina y, o JSON s eam. The Da a S eam Con en sec ion desc ibes he
s eam s uc u e and layou o each o ma .
The esul ing da a s eam can be conside ed a s eam o eco ds, whe e each eco d con ains one alue
o each da ase pa ame e . Each da a eco d mus con ain a da a alue o a ill alue (o he same da a
ype) o each pa ame e .
3.7.1 Reques Pa ame e s
I ems wi h a * supe sc ip in he ollowing able ha e been modi ied om e sion 2 o 3; see change
no es.
Name Desc ip ion
da ase * Requi ed The iden i ie o he da ase (allowed cha ac e s).
s a * Requi ed The inclusi e begin ime o he da a o include in he esponse.
s op * Requi ed The exclusi e end ime o he da a o include in he esponse.
pa ame e s
Op ional A comma-sepa a ed lis o pa ame e s o include in he esponse
(allowed cha ac e s). De aul is all; ...¶me e s=&... in URL should be
in e p e ed as meaning all pa ame e s.
include Op ional Has one possible alue o “heade ” o indica e ha he in o heade
should p ecede he da a. The heade lines will be p e ixed wi h he “#“ cha ac e .
Name Desc ip ion
o ma Op ional The desi ed o ma o he da a s eam. Possible alues a e “cs ”,
“bina y”, and “json”.
3.7.2 Response
The da a endpoin esponse is in one o h ee o ma s: CSV o ma as de ined by [2] wi h a mime ype
o ex /cs ; bina y o ma whe e loa ing poin s numbe a e in IEEE 754 [4] o ma and by e o de is
LSB and a mime ype o applica ion/oc e -s eam; JSON o ma wi h he s uc u e as desc ibed
below and a mime ype o applica ion/json. The de aul da a o ma is CSV. See he Da a S eam
Con en sec ion o mo e de ails.
I he heade is eques ed, hen o bina y and CSV o ma s, each line o he heade mus begin wi h a
hash (#) cha ac e . Fo JSON ou pu , no p e ix cha ac e should be used because he da a objec will be
ano he JSON elemen wi hin he esponse. O he han he possible p e ix cha ac e , he con en s o he
heade should be he same as e u ned om he in o endpoin . When a da a s eam has an a ached
heade , he heade mus con ain an addi ional “ o ma ” a ibu e o indica e i he con en a e he heade
is cs , bina y, o json. No e ha when a heade is included in a CSV esponse, he da a s eam is no
s ic ly in CSV o ma .
The i s pa ame e in he da a mus be a ime column ( ype o iso ime) and his mus be he
independen a iable o he da ase . I a subse o pa ame e s is eques ed, he ime column is always
p o ided, e en i i is no eques ed.
No e ha he s a eques pa ame e ep esen s an inclusi e lowe bound, and he s op eques
pa ame e is he exclusi e uppe bound. The se e mus e u n da a eco ds wi hin hese ime
cons ain s, i.e., no ex a eco ds ou side he eques ed ime ange. This enables he conca ena ion o
esul s om adjacen ime anges.
The e is a ela ionship be ween he in o endpoin and he da a endpoin because he heade om he
in o endpoin desc ibes he eco d s uc u e o da a emi ed by he da a endpoin . Thus, a e a single
call o he in o endpoin , a clien could make mul iple calls o he da a endpoin ( o mul iple ime
anges, o example) wi h he expec a ion ha each da a esponse would con ain eco ds desc ibed by
he single call o he in o endpoin . The da a endpoin can op ionally p e ix he da a s eam wi h heade
in o ma ion, po en ially ob ia ing he need o he in o endpoin .
Bo h he in o and da a endpoin s ake an op ional eques pa ame e ( ecall he de ini ion o eques
pa ame e in he in oduc ion) called pa ame e s ha allows use s o es ic he da ase pa ame e s
lis ed in he heade and da a s eam, espec i ely. This enables clien s ( ha al eady ha e a lis o da ase
pa ame e s om a p e ious in o o da a eques ) o eques a heade o a subse o pa ame e s ha will
ma ch a da a s eam o he same subse o pa ame e s. The pa ame e s in he subse eques mus be
o de ed acco ding o he o iginal o de o he pa ame e s in he me ada a, i.e., he subse can con ain
ewe pa ame e s, bu hei o de mus be he same as in he pa ame e a ay in he /in o esponse.
Conside he ollowing da ase heade o a ic ional da ase wi h he iden i ie MY_MAG_DATA.
An in o eques o his da ase *
h p://se e /hapi/in o?da ase =MY_MAG_DATA
esul s in a heade lis ing o all he da ase pa ame e s:
{ 1
"HAPI": "3.3", 2
"s a us": { "code": 1200, "message": "OK"}, 3
"s a Da e": "2005-01-21T12:05:00.000Z",4
"s opDa e" : "2010-10-18T00:00:00Z", 5
"pa ame e s": [ 6
{ "name": "Time", 7
" ype": "iso ime",8
"uni s": "UTC", 9
" ill": null,10
"leng h": 24 }, 11
{ "name": "Bx", " ype": "double", "uni s": "nT", " ill": "-1e31"}, 12
{ "name": "By", " ype": "double", "uni s": "nT", " ill": "-1e31"}, 13
{ "name": "Bz", " ype": "double", "uni s": "nT", " ill": "-1e31"}, 14
]15
}16
An in o eques o a single pa ame e has he o m
h p://se e /hapi/in o?da ase =MY_MAG_DATA¶me e s=Bx
and would esul in he ollowing heade :
{ 1
"HAPI": "3.3", 2
"s a us": { "code": 1200, "message": "OK"}, 3
"s a Da e": "2005-01-21T12:05:00.000Z", 4
"s opDa e" : "2010-10-18T00:00:00Z",5
"pa ame e s": [ 6
{ "name": "Time", 7
" ype": "iso ime", 8
"uni s": "UTC",9
" ill": null,10
"leng h": 24 }, 11
{ "name": "Bx", " ype": "double", "uni s": "nT", " ill": "-1e31" }, 12
]13
}14
No e ha he ime pa ame e is included e en hough i was no eques ed.
In his eques *,
h p://se e /hapi/in o?da ase =MY_MAG_DATA¶me e s=By,Bx
he pa ame e s a e ou o o de . So he se e should espond wi h an e o code. See HAPI S a us Codes
o mo e abou e o condi ions.
3.7.3 Examples
Two examples o da a eques s and esponses a e gi en – one wi h he heade and one wi hou .
3.7.3.1 Da a wi h Heade
No e ha in he ollowing eques , he heade is o be included, so he same heade om he in o
endpoin will be p epended o he da a bu wi h a ‘#’ cha ac e as a p e ix o e e y heade line.
h p://se e /hapi/da a?da ase =pa h/ o/ACE_MAG&s a =2016-01-01Z&s op=2016-02-
01Z&include=heade
Response
#{ 1
# "HAPI": "3.3", 2
# "s a us": { "code": 1200, "message": "OK"}, 3
# " o ma ": "cs ", 4
# "s a Da e": "1998-001Z", 5
# "s opDa e" : "2017-001Z", 6
# "pa ame e s": [ 7
# { "name": "Time", 8
# " ype": "iso ime", 9
# "uni s": "UTC", 10
# " ill": null, 11
# "leng h": 24 12
# }, 13
# { "name": " adial_posi ion", 14
# " ype": "double", 15
# "uni s": "km", 16
# " ill": null, 17
# "desc ip ion": " adial posi ion o he spacec a " 18
# }, 19
# { "name": "quali y lag", 20
# " ype": "in ege ", 21
# "uni s ": null, 22
# " ill": null, 23
# "desc ip ion ": "0=OK and 1=bad " 24
# }, 25
# { "name": "mag_GSE", 26
# " ype": "double", 27
# "uni s": "nT", 28
# " ill": "-1e31", 29
# "size" : [3], 30
# "desc ip ion": "hou ly a e age Ca esian magne ic ield in nT in GSE" 31
# } 32
# ] 33
#} 34
2016-01-01T00:00:00.000Z,6.848351,0,0.05,0.08,-50.98 35
2016-01-01T01:00:00.000Z,6.890149,0,0.04,0.07,-45.26 36
... 37
... 38
2016-01-01T02:00:00.000Z,8.142253,0,2.74,0.17,-28.62 39
3.7.3.2 Da a Only

The ollowing example is he same, excep i lacks he eques o include he heade .
h p://se e /hapi/da a?da ase =pa h/ o/ACE_MAG&s a =2016-01-01&s op=2016-02-01
Response
Conside a da ase ha con ains a ime ield, wo scala ields, and one a ay ield o leng h 3. The
esponse will ha e he o m:
2016-01-01T00:00:00.000Z,6.848351,0,0.05,0.08,-50.98 1
2016-01-01T01:00:00.000Z,6.890149,0,0.04,0.07,-45.26 2
... 3
... 4
2016-01-01T02:00:00.000Z,8.142253,0,2.74,0.17,-28.62 5
No e ha he e is no leading ow wi h column names. The RFC 4180 CSV s anda d [2] indica es ha
such a heade ow is op ional. Lea ing ou his ow a oids he complica ion o naming indi idual
columns ep esen ing a ay elemen s wi hin an a ay pa ame e . Recall ha an a ay pa ame e has only
a single name. HAPI speci ies pa ame e names ia he in o endpoin , which also p o ides size de ails
o each pa ame e (scala o a ay, and a ay size i needed). The size o each pa ame e mus be used o
de e mine how many columns i will use in he CSV da a. By no speci ying a ow o column names,
HAPI a oids he need o ha e a naming con en ion o columns ep esen ing elemen s wi hin an a ay
pa ame e .
3.7.4 Response o ma s
The h ee possible ou pu o ma s a e cs , bina y, and json. A HAPI se e mus suppo cs , while
bina y and json a e op ional. We emphasize ha his is a simple and epheme al s eaming anspo
o ma and should no be conside ed o used in he same way as s anda d ile o ma s such as FITS,
HDF, CDF, and ne CDF, which we e no designed o s eaming.
3.7.4.1 CSV
The o ma o he CSV s eam should ollow he guidelines o CSV da a as desc ibed by RFC 4180 [2].
Each CSV eco d is one line o ex , wi h commas be ween he alues o each da ase pa ame e . Any
alue con aining a comma mus be su ounded wi h double quo es, and any double-quo e wi hin a alue
mus be escaped by a p eceding double quo e. An a ay pa ame e (i.e., he alue o a pa ame e wi hin
one eco d is an a ay) will ha e mul iple columns esul ing om placing each elemen in he a ay in o
i s own column. Fo 1-D a ays, he o de ing o he unwound columns is jus he index o de ing o he
a ay elemen s. Fo 2-D a ays o highe , he igh -mos a ay index is he as es mo ing index when
mapping a ay elemen s o columns.
I is up o he se e o decide how much p ecision o include in he ASCII alues when gene a ing CSV
ou pu .
Clien s p og ams in e p e ing he HAPI CSV s eam a e encou aged o use exis ing CSV pa sing
lib a ies o be able o in e p e he ull ange o possible CSV alues, including quo ed commas and
escaped quo es. Howe e , i is expec ed ha a simple CSV pa se would p obably handle mo e han 90%
o known cases.
3.7.4.2 Bina y
The bina y da a ou pu is bes desc ibed as a bina y ansla ion o he CSV s eam, wi h ull nume ical
p ecision and no commas o newlines. Recall ha he da ase heade p o ides ype in o ma ion o each
da ase pa ame e , and his de ini i ely indica es he numbe o by es and he by e s uc u e o each
pa ame e and, hus, o each bina y eco d in he s eam. A ay pa ame e s a e unwound in he same way
o bina y as o CSV da a as desc ibed abo e. All nume ic alues a e li le-endian (LSB), in ege s a e
always signed and ou -by e and loa ing-poin alues a e always IEEE 754 double-p ecision alues.
Da ase pa ame e s o ype s ing and iso ime (s ings o ISO 8601 da es) ha e a maximum leng h
speci ied in he in o heade . This leng h indica es how many by es o ead o each s ing alue. I he
s ing con en is less han he leng h, he emaining by es mus be padded wi h ASCII null by es. I a
s ing uses all he by es speci ied in he leng h, no null e mina o o padding is needed.
3.7.4.3 JSON
Fo he JSON ou pu , an addi ional da a elemen added o he heade con ains he a ay o da a eco ds.
These eco ds a e simila o he CSV ou pu , excep ha s ings mus be quo ed and a ays mus be
delimi ed wi h a ay b acke s in s anda d JSON ashion. An example helps o illus a e wha he JSON
o ma looks like. Conside a da ase wi h ou pa ame e s: ime, a scala alue, a 1-D a ay alue wi h
an a ay leng h o 3, and a s ing alue. The heade wi h he da a objec migh look like his:
{ "HAPI": "3.3", 1
"s a us": { "code": 1200, "message": "OK"}, 2
"s a Da e": "2005-01-21T12:05:00.000Z",3
"s opDa e" : "2010-10-18T00:00:00Z", 4
"pa ame e s": [ 5
{ "name": "Time", " ype": "iso ime", "uni s": "UTC", " ill": null,
"leng h": 24 },
6
{ "name": "quali y_ lag", " ype": "in ege ", "desc ip ion": "0=ok; 1=bad",
" ill": null },
7
{ "name": "mag_GSE", " ype": "double", "uni s": "nT", " ill": "-1e31",
"size" : [3],
8
"desc ip ion": "hou ly a e age Ca esian magne ic ield in nT in GSE"
},
9
{ "name": " egion", " ype": "s ing", "leng h": 20, " ill": "???",
"uni s" : null}
10
], 11
" o ma ": "json",12
"da a" : [ 13
["2010-001T12:01:00Z",0,[0.44302,0.398,-8.49],"shea h"], 14
["2010-001T12:02:00Z",0,[0.44177,0.393,-9.45],"shea h"], 15
["2010-001T12:03:00Z",0,[0.44003,0.397,-9.38],"shea h"], 16
["2010-001T12:04:00Z",1,[0.43904,0.399,-9.16],"shea h"]17
]18
19
}20
The da a elemen is a JSON a ay o eco ds. Each eco d is i sel an a ay o pa ame e s. The ime and
s ing alues a e in quo es, and any da a pa ame e in he eco d ha is an a ay mus be inside squa e
b acke s. This da a elemen appea s as he las JSON elemen in he heade .
The eco d-o ien ed a angemen o he JSON o ma is designed o allow a s eaming clien eade o
begin eading (and p ocessing) he JSON da a s eam be o e i is comple e. No e also ha se e s can
s eam he da a when eco ds a e a ailable. In o he wo ds, he JSON o ma can be ead and w i en
wi hou holding all he eco ds in memo y. This may equi e a cus om JSON o ma e , bu his
s eaming capabili y is impo an o la ge esponses.
3.7.5 E o s While S eaming
I he se e encoun e s an e o a e he da a has begun and can no longe con inue, i mus e mina e
he s eam. As a esul , clien s mus de ec an abno mally e mina ed s eam and ea his abo ed
condi ion he same as an in e nal se e e o . See HAPI S a us Codes o mo e abou e o condi ions.
3.7.6 Rep esen a ion o Time
Time alues a e always s ings, and he HAPI Time o ma is a subse o he ISO 8601 da e and ime
o ma [1].
The es ic ion on he ISO 8601 s anda d is ha ime mus be ep esen ed as
yyyy-mm-ddThh:mm:ss.sssZ
o
yyyy-dddThh:mm:ss.sssZ
and he ailing Z is equi ed. S ings wi h less p ecision a e allowed as pe ISO 8601, e.g., 1999-01Z and
1999-001Z. The HAPI JSON schema lis s a se ies o egula exp essions ha codi ies he in en ion o
he HAPI Time speci ica ion. The schema allows leap seconds and hou =24, bu i should be expec ed
ha no all clien s will be able o co ec ly in e p e such ime s amps.
The name o he ime pa ame e is no cons ained. Howe e , he ime column name is s ongly
ecommended o be “Time” o “Epoch” o some easily ecognizable label.
No e ha he ISO 8601 ime o ma allows a bi a y p ecision on he ime alues. HAPI se e s and
clien s should be able o in e p e imes wi h a leas nanosecond p ecision.
3.7.6.1 Incoming ime alues
Se e s mus equi e incoming ime alues om clien s (i.e., he s a and s op alues on a da a
eques ) o be alid ISO 8601 ime alues. The ull ISO 8601 speci ica ion allows many eso e ic op ions,
bu se e s mus only accep a subse o he ull ISO 8601 speci ica ion, namely one o ei he yea -
mon h-day (yyyy-mm-ddThh:mm:ss.sssZ) o day-o -yea (yyyy-dddThh:mm:ss.sssZ). Any da e o ime
elemen s missing om he s ing a e assumed o ake on hei smalles possible alue. Fo example, he
s ing 2017-01-15T23:00:00.000Z could be gi en in unca ed o m as 2017-01-15T23Z. Se e s
should be able o pa se and p ope ly in e p e hese unca ed ime s ings. When clien s p o ide a da e a
day esolu ion only, he T mus no be included, so se e s should be able o pa se day-le el ime s ings
wi hou he T, as in 2017-01-15Z.
No e ha in he ISO 8601 speci ica ion, a ailing Z on he ime s ing indica es ha no ime zone o se
should be applied (so he ime zone is GMT+0). I a se e ecei es an inpu alue wi hou he ailing Z,
i should s ill in e p e he ime zone as GMT+0 a he han a local ime zone. This is ue o ime
s ings wi h all ields p esen and o unca ed ime s ings wi h some ields missing.
Example ime ange eques commen s
s a =2017-01-15T00:00:00.000Z&s op=2017-
01-16T00:00.000Z
OK - ully speci ied ime alue wi h
p ope ailing Z
s a =2017-01-15Z&s op=2017-01-16Z OK - unca ed ime alue ha assumes
00:00.000 o he ime
s a =2017-01-15&s op=2017-01-16 OK - unca ed wi h missing ailing Z, bu
GMT+0 should be assumed
The e is no es ic ion on he ea lies da e o la es da e a HAPI se e can accep , bu as a p ac ical limi ,
clien s a e likely o be w i en o handle da es only om 1700 o 2100.
3.7.6.2 Ou going ime alues
Time alues in he ou going da a s eam mus be ISO 8601 s ings. A se e may use one o ei he he
yyyy-mm-ddThh:mm:ss.sssZ o he yyyy-dddThh:mm:ss.sssZ o m, bu mus use one o ma and
leng h wi hin any gi en da ase . The ime alues mus no ha e any local ime zone o se , and hey mus
indica e his by including he ailing Z. Time o da e elemen s may be omi ed om he end o indica e
ha he missing ime o da e elemen s should be gi en hei lowes possible alue. Fo da e alues a day
esolu ion (i.e., no ime alues), he T mus be omi ed, bu he Z is s ill equi ed. No e ha his implies
ha clien s mus be able o pa se po en ially unca ed ISO s ings o bo h Yea -Mon h-Day and Yea -
Day-o -yea s yles.
Fo bina y and cs da a, he leng h o he ime s ing, unca ed o no , is indica ed wi h he leng h
a ibu e o he ime pa ame e , which e e s o he numbe o p in able cha ac e s in he s ing. E e y
ime s ing mus ha e he same leng h, so padding o ime s ings is unnecessa y.
The da a e u ned om a eques should s ic ly all wi hin he limi s o s a and s op, i.e., se e s
should no pad he da a wi h ex a eco ds ou side he eques ed ime ange. Fu he mo e, no e ha he
s a alue is inclusi e (da a a o beyond his ime can be included), while s op is exclusi e (da a a o
beyond his ime shall no be included in he esponse).
The p ima y ime column is no allowed o con ain any ill alues. Each eco d mus be iden i ied wi h a
alid ime alue. I o he columns con ain pa ame e s o ype iso ime (i.e., ime columns ha a e no
he p ima y ime column), he e may be ill alues in hese columns. No e ha he ill de ini ion is
equi ed o all ypes, including iso ime pa ame e s. The ill alue o a (non-p ima y) iso ime
pa ame e does no ha e o be a alid ime s ing - i can be any s ing, bu i mus be he same leng h
s ing as he ime a iable.
HAPI me ada a (in he in o heade o a da ase ) allows a se e o speci y whe e imes amps all wi hin
he measu emen window. The imeS ampLoca ion a ibu e o a da ase is an enume a ion wi h
possible alues o begin, cen e , end, o o he . This a ibu e is op ional, bu he de aul alue is
cen e , which e e s o he exac middle o he measu emen window. I he loca ion o he imes amp is
no known o is mo e complex han any o he allowed op ions, he se e can epo o he o he
imeS ampLoca ion. Clien s a e likely o use cen e o o he , simply because he e is no much else
hey can do. No e ha he op ional cadence a ibu e is no mean o be accu a e enough o use as a way
o compu e an al e na e ime s amp loca ion. In o he wo ds, gi en a imeS ampLoca ion o begin and a
cadence o 10 seconds, i may no always wo k o jus add 5 seconds o ge o he cen e o he
measu emen in e al o his da ase . This is because he cadence p o ides a nominal du a ion, and he
ac ual du a ion o each measu emen may a y signi ican ly h oughou he da ase . Some da ase s may
ha e speci ic pa ame e s de o ed o accumula ion ime o o he measu emen window pa ame e s, bu
{ 1
"1200": {"s a us":{"code": 1200, "message": "OK"}}, 2
"1201": {"s a us":{"code": 1201, "message": "OK - no da a o ime ange"}}, 3
"1400": {"s a us":{"code": 1400, "message": "Bad eques - use inpu e o "}}, 4
"1401": {"s a us":{"code": 1401, "message": "Bad eques - unknown API
pa ame e name"}},
5
"1402": {"s a us":{"code": 1402, "message": "Bad eques - syn ax e o in
s a ime"}},
6
"1403": {"s a us":{"code": 1403, "message": "Bad eques - syn ax e o in s op
ime"}},
7
"1404": {"s a us":{"code": 1404, "message": "Bad eques - s a equal o o
a e s op"}},
8
"1405": {"s a us":{"code": 1405, "message": "Bad eques - s a < s a Da e
and/o s op > s opDa e"}},
9
"1406": {"s a us":{"code": 1406, "message": "Bad eques - unknown da ase
id"}},
10
"1407": {"s a us":{"code": 1407, "message": "Bad eques - unknown da ase
pa ame e "}},
11
"1408": {"s a us":{"code": 1408, "message": "Bad eques - oo much ime o
da a eques ed"}},
12
"1409": {"s a us":{"code": 1409, "message": "Bad eques - unsuppo ed ou pu
o ma "}},
13
"1410": {"s a us":{"code": 1410, "message": "Bad eques - unsuppo ed include
alue"}},
14
"1411": {"s a us":{"code": 1411, "message": "Bad eques - ou -o -o de o
duplica e pa ame e s"}},
15
"1412": {"s a us":{"code": 1412, "message": "Bad eques - unsuppo ed
esol e_ e e ences alue"}},
16
"1413": {"s a us":{"code": 1413, "message": "Bad eques - unsuppo ed dep h
alue"}},
17
"1500": {"s a us":{"code": 1500, "message": "In e nal se e e o "}}, 18
"1501": {"s a us":{"code": 1501, "message": "In e nal se e e o - ups eam
eques e o "}}
19
}20
8.4 Examples
The ollowing wo examples illus a e wo di e en ways o ep esen a magne ic ield da ase . The i s
lis s a ime column and h ee scala da a columns, Bx, By, and Bz o he Ca esian componen s.

{ 1
"HAPI": "3.3", 2
"s a us": { "code": 1200, "message": "OK"}, 3
"s a Da e": "2016-01-01T00:00:00.000Z",4
"s opDa e": "2016-01-31T24:00:00.000Z", 5
"pa ame e s": [ 6
{"name" : " imes amp", " ype": "iso ime", "uni s": "UTC", " ill": null,
"leng h": 24},
7
{"name" : "bx", " ype": "double", "uni s": "nT", " ill": "-1e31"}, 8
{"name" : "by", " ype": "double", "uni s": "nT", " ill": "-1e31"}, 9
{"name" : "bz", " ype": "double", "uni s": "nT", " ill": "-1e31"}10
]11
}12
This example shows a heade o he same concep ual da a ( ime and h ee magne ic ield componen s),
bu wi h he h ee componen s g ouped in o a one-dimensional a ay o size 3.
{1
"HAPI": "3.3", 2
"s a us": { "code": 1200, "message": "OK"}, 3
"s a Da e": "2016-01-01T00:00:00.000Z", 4
"s opDa e": "2016-01-31T24:00:00.000Z",5
"pa ame e s": [ 6
{ "name" : " imes amp", " ype": "iso ime", "uni s": "UTC", " ill": null,
"leng h": 24 },
7
{ "name" : "b_ ield", " ype": "double", "uni s": "nT", " ill": "-1e31",
"size": [3] }
8
] 9
}10
These wo di e en ep esen a ions a ec how a subse o pa ame e s could be eques ed om a se e .
The i s example, by lis ing Bx, By, and Bz as sepa a e pa ame e s, allows clien s o eques indi idual
componen s:
h p://se e /hapi/da a?da ase =MY_MAG_DATA&s a =2001Z&s op=2010Z¶me e s=Bx
This eques would jus e u n a ime column (always included as he i s column) and a Bx column.
Bu in he second example, he componen s a e all inside a single pa ame e named b_ ield and so a
eques o his pa ame e mus always e u n all he componen s o he pa ame e . The e is no way o
eques indi idual elemen s o an a ay pa ame e .
The ollowing example shows a p o on ene gy spec um and illus a es he use o he ‘bins’ elemen .
No e also ha he unce ain y o he alues associa ed wi h he p o on spec um is a sepa a e a iable.
The e is cu en ly no way in he HAPI spec o explici ly link a a iable o i s unce ain ies.
{"HAPI": "3.3", 1
"s a us": { "code": 1200, "message": "OK"}, 2
"s a Da e": "2016-01-01T00:00:00.000Z", 3
"s opDa e": "2016-01-31T24:00:00.000Z",4
"pa ame e s": [ 5
{ "name": "Time", 6
" ype": "iso ime", 7
"uni s": "UTC",8
" ill": null, 9
"leng h": 24 10
}, 11
{ "name": "qual_ lag",12
" ype": "in ",13
"uni s": null,14
" ill": null 15
}, 16
{ "name": "magla ",17
" ype": "double",18
"uni s": "deg ees",19
" ill": null,20
"desc ip ion": "magne ic la i ude" 21
}, 22
{ "name": "MLT",23
" ype": "s ing",24
"leng h": 5,25
"uni s": "hou s:minu es",26
" ill": "??:??",27
"desc ip ion": "magne ic local ime in HH:MM" 28
}, 29
{ "name": "p o on_spec um",30
" ype": "double",31
"size": [3], 32
"uni s": "pa icles/(sec s e cm^2 keV)",33
" ill": "-1e31",34
"bins": [ { 35
"name": "ene gy",36
"uni s": "keV",37
"cen e s": [ 15, 25, 35 ], 38
} ], 39
{ "name": "p o on_spec um_unce s",40
" ype": "double",41
"size": [3], 42
"uni s": "pa icles/(sec s e cm^2 keV)",43
" ill": "-1e31",44
"bins": [ { 45
"name": "ene gy",46
"uni s": "keV",47
"cen e s": [ 15, 25, 35 ], 48
} ] 49
}50
51
]52
}53
This shows how “ anges” can speci y he bins:
{ 1
"HAPI": "3.3", 2
"s a us": { "code": 1200, "message": "OK"}, 3
"s a Da e": "2016-01-01T00:00:00.000Z",4
"s opDa e": "2016-01-31T24:00:00.000Z", 5
"pa ame e s": [ 6
{ 7
"leng h": 24,8
"name": "Time", 9
" ype": "iso ime",10
" ill": null,11
"uni s": "UTC" 12
}, 13
{14
"bins": [{ 15
" anges": [ 16
[ 0, 30 ], 17
[ 30, 60 ], 18
[ 60, 90 ], 19
[ 90, 120 ], 20
[ 120, 150 ], 21
[ 150, 180 ] 22
], 23
"uni s": "deg ees" 24
}], 25
" ill": "-1e31",26
"name": "pi chAngleSpec um",27
"size": [6], 28
" ype": "double",29
"uni s": "pa icles/sec/cm^2/s e /keV" 30
}31
]32
}33
8.5 Robo clien s
P ocesses ha in oduce a ic o se e s which does no ep esen immedia e use o science pu poses
should be iden i iable by he se e s. Fo example, an indexing se ice ha que ies a se e o me ada a
o a p ocess ha e i ies ha a se e is esponsi e. Robo clien s making such eques s should se he
Use -Agen p ope y. This p ope y should iden i y bo h an id and a URL ha desc ibes he bo . Fo
example, hapibo -a pings all HAPI se e s each hou o see each is esponsi e and se s he Use -Agen
agen o
"hapibo -a/1.0; h ps://gi hub.com/hapi-se e /da a-speci ica ion/wiki/hapi-
bo s.md#hapibo -a".
No e ha he use o he wiki page o desc ibe bo s is encou aged.
8.6 FAIR
Fo each o he elemen s o FAIR lis ed below (copied om h ps://www.go- ai .o g/ ai -p inciples/), we
desc ibe hei ela ionship wi h he HAPI speci ica ion.
Some aspec s o HAPI, which is an API and me ada a s anda d, di ec ly add ess FAIR; howe e , some
FAIR p inciples mus be add essed by an ex e nal se ice o he da a p o ide . As such, HAPI suppo s
FAIR p inciples o he ex en ha he p inciples a e wi hin i s scope.
8.6.1 Findable
The i s s ep in ( e)using da a is o ind hem. Me ada a and da a should be easy o ind o bo h humans
and compu e s. Machine- eadable me ada a a e essen ial o au oma ic disco e y o da ase s and
se ices, so his is an essen ial componen o he FAIRi ica ion p ocess.
1. (Me a)da a a e assigned a globally unique and pe sis en iden i ie
The esou ceID a ibu e can be used o a globally unique and pe sis en iden i ie .
Al e na i ely,
I each HAPI da ase does no ha e a globally unique and pe sis en iden i ie , bu he se e does, a
da a p o ide can use he esou ceID in he /abou esponse (bu da a p o ide s a e encou aged o
ha e da ase -le el esou ceIDs).
I a da ase is associa ed wi h mo e han one iden i ie , a da a p o ide can c ea e a da ase o
iden i ie s and se e his da ase as a ime se ies.
2. Da a a e desc ibed wi h ich me ada a (de ined by Reusable, i em 1. below)
Reusable, i em 1: (Me a)da a a e ichly desc ibed wi h a plu ali y o accu a e and ele an a ibu es
The HAPI me ada a speci ica ion has accu a e and ele an a ibu es; he da a p o ide needs o ensu e
he a ibu e alues accu a ely desc ibe he da a and include in o ma ion equi ed o in e p e a ion.
3. Me ada a clea ly and explici ly include he iden i ie o he da a hey desc ibe
The HAPI me ada a speci ica ion equi es an iden i ie (id) o e e y da ase . The lis o all ids is
e u ned in a ca alog/ eques . id is also used in he da ase eques pa ame e in he URL o an
in o/ o da a/ eques . (The HAPI /in o esponse does no con ain he id because we ha e gene ally
a oided he duplica ion o me ada a in esponses om di e en endpoin s.)
4. (Me a)da a a e egis e ed o indexed in a sea chable esou ce
This is ou side he scope o he HAPI speci ica ion. Howe e , he e is a way o explo e all known HAPI
se e s a h ps://hapi-se e .o g/se e s/. We also wo k wi h o he p ojec s ha add ess egis a ion,
indexing, and sea ching.
8.6.2 Accessible

Once he use inds he equi ed da a, hey need o know how hey can be accessed, possibly including
au hen ica ion and au ho iza ion.
1. (Me a)da a a e e ie able by hei iden i ie using a s anda dized communica ions p o ocol
All HAPI endpoin s use he HTTP p o ocol; HAPI me ada a is JSON. The in o/ endpoin akes he
da ase id and e u ns JSON me ada a. The da a/ endpoin also akes he id and e u ns da a in CSV,
JSON, o bina y.
2. The p o ocol is open, ee, and uni e sally implemen able
HAPI deli e s JSON me ada a and well-s uc u ed da a o e HTTP(S). The schema o he da a and
me ada a is ee, open, and can be implemen ed in any p og amming language.
3. The p o ocol allows o an au hen ica ion and au ho iza ion p ocedu e, whe e necessa y
This is ou o scope o HAPI, which was designed o access open da a. The HAPI speci ica ion
explici ly does no include an op ion o au hen ica ion. Access es ic ions can s ill be implemen ed
using au hen ica ion mechanisms ou side o independen o HAPI.
4. Me ada a a e accessible, e en when he da a a e no longe a ailable
This is ou side he scope o he HAPI speci ica ion. Howe e , an a ilia ed HAPI p ojec caches
me ada a om all known HAPI se e s nigh ly.
8.6.3 In e ope able
The da a usually needs o be in eg a ed wi h o he da a. In addi ion, he da a needs o in e ope a e wi h
applica ions o wo k lows o analysis, s o age, and p ocessing.
1. (Me a)da a use a o mal, accessible, sha ed, and b oadly applicable language o knowledge
ep esen a ion.
HAPI me ada a a e in JSON, and JSON schemas a e a ailable o alida ion. HAPI da a is ansmi ed
as JSON o Comma Sepa a ed Values (CSV), bo h widely used. (HAPI se e s may use a simple bina y
o ma , which uses IEEE s anda ds o bina y numbe s, and he layou mimics he CSV ou pu .)
2. (Me a)da a use ocabula ies ha ollow FAIR p inciples
HAPI me ada a does no use ocabula ies di ec ly, bu links can be made o ex e nal me ada a ha uses
ocabula ies (see nex i em).
3. (Me a)da a include quali ied e e ences o o he (me a)da a
O he me ada a can be e e enced using addi ionalMe ada a.
8.6.4 Reusable
The ul ima e goal o FAIR is o op imize he euse o da a. To achie e his, me ada a and da a should be
well-desc ibed so ha hey can be eplica ed and/o combined in di e en se ings.
1. (Me a)da a a e ichly desc ibed wi h a plu ali y o accu a e and ele an a ibu es
This is sa is ied by he HAPI speci ica ion.
2. (Me a)da a a e eleased wi h a clea and accessible da a usage license
This can be sa is ied by using he license a ibu e.
3. (Me a)da a a e associa ed wi h de ailed p o enance
This can be sa is ied using he p o enance a ibu e.
4. (Me a)da a mee domain- ele an communi y s anda ds
HAPI is buil using he widely adop ed REST ul app oach o web-accessible esou ces. We use JSON in
a way ha is common in he communi y. The ime s anda d is a subse o he ISO8601 s anda d o ime
s ings. The design o he HAPI API o eques ing and ecei ing da a ollowed om an analysis o he
API o many ime se ies da a p o ide s, and HAPI is a s anda d ha p o ides a common se o ea u es.