An application programming interface (API) message specification for covid19 diagnostic data. Enables to re-connect all kinds of disparate third-party covid19 apps safely and securely, to exchange pseudonymous diagnostic profile data. Moreover, this API message specification defines also message formats to allow to officially authorize and authenticate a wide range of re-connected covid19 apps as trusted apps. This could be achieved by national and international official public health organizations patronizing a future API and its infrastucture, such as e.g. the Swiss Federal Public Health Office or the U.S. CDC on a national level, and ultimately, the World Health Organization.
The specified Covid19Clue API messages are in a JSON-like format, with comments and example data, thus cannot be used in code without modification - they serve for specification purposes only. For use in large-scale messaging systems, they must be adapted.
Currently, no proper API implementation of Covid19Clue API messages exists (yet), but find some very brief API message end-point scenarios here, developed during the versusvirus.ch hackathon by our team, see the presentation submitted by the team here.
Re-connect 3rd-party mobile apps via this endpoint. Provide pseudonymous user diagnosis profile message records for predictions for all 3rd-party public health dashboard apps, epidemiologic dashboards via a messaging API service.
1.2 Covid19Clue API message end-point scenario description for health offices, hospitals and physicians
This API end-point reconnects 3rd-party big-data apps for epidemiologics & prediction in governments as well as 3rd-party health care apps for physicians' patient management to get infection data and patient profiles in near-real time. It e.g. helps physicians to speed up writing and revoking work dispenses in case of positive test results and/or ordered quarantine, hospitalization, etc.
This API end-point scenario connects to Test Lab computers and appliances, as well as home testing appliances IoT (Internet-of-Things) in a machine-to-machine future.
This API end-point specification defines app session and token-based authentication message record types.
This API specification defines app and app contact authorization record types.
JSON-like diagnostic profile message record for time series, with (bogus) example data.
"profile-msg": {
"profile":"369e1fac-820b-4695-98a4-e22901584e0c" // pseudonymous diagnostic profile v4 RFC 4122 UUID e.g., see https://https://uuidgen.org/v/4, as string, mandatory
"agent":"d303aea7-3604-46c5-84c9-ad2758fb2852" // agent v4 RFC 4122 UUID e.g., see https://https://uuidgen.org/v/4, as string, mandatory
"user-tx-timestamp":"1586483743" // user transmission GMT time, unix UTC-timestamp, as string, optional
"user-tx_tz":"+0100" // user timezone, string concatenation of "+" or "-" with "hhmm" time format, excluding daylight saving time, as string, optional
"agent-tx-timestamp":"1586485743" // agent transmission GMT time, unix UTC-timestamp, as string, mandatory
"agent-tx-tz":"+0100", mandatory // agent timezone, string concatenation of "+" or "-" with "hhmm" time format, excluding daylight saving time, as string
"agent-gps-lat:"46.9465" // GPS latitude, float value, as string, optional
"agent-gps-long":"7.4443" // GPS longitude, float value, as string, optional
"agent-gps-prec":"50" // GPS precision in meters, integer as string, optional
"age":"55" // age, integer as string, optional
"sex":"m" // sex, string, "f" = female, "m" = male, optional
"infectuous_proximity":"0" // infectuous proximity warning flag, boolean value, default = "0", as string, optional
"self-diag-has_fever":"1" // symptom, fever, boolean, as string, optional
"self-diag-body-temp-scale":"C" // temperature scale, "C" = Celsius, "F" = Fahrenheit, as string, optional
"self-diag-body-temp":"38.9" // body temperature, float, as string, optional
"self-diag-oxy-level:"96" // oxygen level percentage, integer, as string, optional
"self-diag-cough-sound-AI-result: "74" // cough-sound-AI-correspondance percentage, integer, as string, optional
"self-diag-has-dry-cough":"0" // symptom, dry cough, boolean value, default = "0" as string, optional
"self-diag-has-freq-sneezing":"0" // symptom, frequent sneezing, boolean value, default = "0" as string, optional
"self-diag-has-short-breath:"1" // symptom, short breath, boolean value, default = "0" as string, optional
"self-diag-has-breath-difficult:"0" // symptom, difficulty breathing, boolean value, as string, optional
"self-diag-has-taste-loss":"0" // symptom, taste loss, boolean value, default = "0", as string, optional
"self-diag-has-diarrhea":"0" // symptom, diarrhea, boolean value, default = "0" as string
"self-diag-has-constipation:"0" // symptom, constipation, boolean value, default = "0" as string, optional
"self-diag-has-stool_color-change:"1" // symptom, stool color change, boolean value, default = "0", as string, optional
"self-diag-has-urine-color-change:"0" // symptom, urine color change, boolean value, default = "0", as string, optional
"self-diag-has-migraine-like-ache:"1" // symptom, migraine-like headache, boolean value, default ="0", as string optional
"self-diag-has-bodyskin-rash":"1" // symptom, sudden body skin rash, boolean value, default ="0", as string, optional
"self-diag-has-pruritus":"1" // symptom, pruritus (itches), boolean value, default = "0", as string, optional
"self-diag-has-tachycardy:"1" // symptom, tachycardy at rest, boolean value, default = "0", as string, optional
"self-diag-has-cardial-arrhythmy:"0" // symptom, cardial arrhythmy, boolean value, default = "0", as string, optional
"vrfd-diag-has-virustest:"0" // verified tested for virus, boolean value, default = "0", as string, optional
"vrfd-diag-virustest-result:"0" // verified virus test result, boolean value, default = "0", as string, optional
"vrfd-diag-has-immunetest:"0" // verified tested for immunity, boolean value, default = "0", as string, optional
"vrfd-diag-immunetest-result:"0" // verified immune test result, boolean value, default = "0", as string, optional
vrfd-is-plasma-donor:"0" // verified plasma donor, boolean value, default = "0", as string, optional
"stage":"1" // "0" = undiagnosed,
// "1" = self-diagnosed,
// "2" = verified-virustest
// "4" = verified-immunetest-negative,
// "5" = verified-immunetest-positive,
// integer, as string, mandatory
"quarantine":"1" // "0" = shelter-at-home-commuting,
// "1" = shelter-at-home-permanent,
// "2" = ordered-at-home,
// "3" = hospitalized,
// "4" = immunized-released,
// integer, as string, mandatory
}
JSON-like agent authentication message record for time series, with (bogus) example data.
"agent-authn-msg": {
"agent":"d303aea7-3604-46c5-84c9-ad2758fb2852" // agent v4 RFC 4122 UUID e.g., see https://https://uuidgen.org/v/4, as string
"token":"216f00f4be13890449c1852cffd7a8bd9557258eacda56e0b4e8166b943405cc" // token SHA-256 hash code, as string
"session":"e696ebe85bb17ac62ac40e58a07224bb65654935617349ddf538fd5ac176512e" // session SHA-256 hash-code, as string
"timestamp:"1586485642" // Authentication GMT time, unix UTC-timestamp, as string
"tz":"+0100" // Authentication timezone, string concatenation of "+" or "-" with "hhmm" time format, excluding daylight saving time, as string
"session-timeout":"3600" // Authentication timeout, in seconds, as string
} // all fields are mandatory
JSON-like agent contact authentication message record for time series, with (bogus) example data.
"contact-authn-msg": {
"contact":"4e8f2603-4591-4392-952f-bfbe86bd06eb" // contact v4 RFC 4122 UUID e.g., see https://https://uuidgen.org/v/4, as string
"agent":"d303aea7-3604-46c5-84c9-ad2758fb2852" // agent v4 RFC 4122 UUID e.g., see https://https://uuidgen.org/v/4, as string
"token":"216f00f4be13890449c1852cffd7a8bd9557258eacda56e0b4e8166b943405cc" // token SHA-256 hash code, as string
"session":"e696ebe85bb17ac62ac40e58a07224bb65654935617349ddf538fd5ac176512e" // session SHA-256 hash-code, as string
"timestamp:"1586485642" // Authentication GMT time, unix UTC-timestamp, as string
"tz":"+0100" // Authentication timezone, string concatenation of "+" or "-" with "hhmm" time format, excluding daylight saving time, as string
"session-timeout":"3600" // Authentication timeout, in seconds, as string
} // all fields are mandatory
JSON-like agent authorization record, with (bogus) data examples.
"agent-authr": {
"agent":"d303aea7-3604-46c5-84c9-ad2758fb2852" // agent v4 RFC 4122 UUID e.g., see https://https://uuidgen.org/v/4, as string
"timestamp:"1586485642" // Authorization GMT time, unix UTC-timestamp, as string
"tz":"+0100" // Authorization time zone, string concatenation of "+" or "-" with "hhmm" time format, excluding daylight saving time, as string
"authorization":"0" // valid authorization, default = "0" = false, "1" = true
"type":"user-app" // Authorization type, "profile-app", "health-app","research-app", "test-lab", "test-site", "self-test-appliance", "nho", "gho", "source", as string
} // all fields are mandatory
JSON-like contact authorization record, with (bogus) example data.
"contact-authr": {
"contact":"4e8f2603-4591-4392-952f-bfbe86bd06eb" // agent contact, v4 RFC 4122 UUID e.g., see https://https://uuidgen.org/v/4, as string
"agent":"d303aea7-3604-46c5-84c9-ad2758fb2852" // agent, v4 RFC 4122 UUID e.g., see https://https://uuidgen.org/v/4, as string
"timestamp:"1586485642" // Authorization GMT time, unix UTC-timestamp, as string
"tz":"+0100" // Authorization time zone, string concatenation of "+" or "-" with "hhmm" time format, excluding daylight saving time, as string
"agent-name":"Covidtracker" // agent name, as string
"agent-url":"https://covidtracker.ch" // valid url, as string
"agent-org-fqdn":"covidtracker.ch" // valid org domain, as string
"agent-org-name":"Canton of Bern" // organization name, as string
"agent-org-spoc-usermail":"mailto:admin-at-covidtracker.ch" // valid mail uri, as string
"agent-org-spoc-password:"2207f568da6b4d1ba8a9cdebb18d5c79847a4fb23a41b27489a3c6d84aeab215" // sha-256 salted password hash, as string
"agent-org-spoc-tel-intl":"41123456789" // valid international phone number, as string
"agent-org-spoc-tel-ext":"12345" // internal extension, as string, optional
"agent-org-addr-line-1":"1234, Main Street" // address line 1, as string
"agent-org addr-line-2":"P.O. Box 1234" // address line 2, as string, optional
"agent-org-city":"Bern" // city, as string
"agent-org-zip":"3000" // Postal code, as string
"agent-org-region":"BE" // region or county code, as string
"agent-org-country":"Switzerland" // Country, as string
} // fields are mandatory, exceptions see field comments.