Skip to navigation
GIDEON API 1.0Diseases

/diseases/surveys/filter

View as Markdown

Returns prevalence and seroprevalence survey rows matching optional filters. Results are ordered by the greater of survey start year and publication year (newest first).

Each row includes core survey fields, resolved pathogens and test_types name arrays (underlying id lists are not returned), and a top-level timestamp (Unix epoch seconds) reflecting the most recent row update in the filtered set.

If the filter set matches more than the server limit (see max_records in the capped response; default 500 when no setting override), the API returns HTTP 200 with { "data": { "record_count", "max_records" } } instead of the full list—add filters (for example disease and country) and call again.

Use GET /diseases/surveys/filter-options to discover available filter values for the current dataset.

Query parameters

NameRequiredDescription
diseaseNoNumeric GIDEON disease identifier.
countryNoGIDEON country code.
survey_start_yearNoLower bound on survey start year.
survey_end_yearNoUpper bound on end year; uses end year when present, otherwise start year.
test_typeNoSubstring match on test-type labels.
pathogenNoSubstring match on pathogen labels.
percentRangeNoFilter on primary percentage: operators <, >, <=, >= plus a number (e.g. >=10), or a plain number (treated as >= that value).
populationNoSurvey population group id (values from filter-options).
regionNoSubdivision (state or equivalent) code from filter-options when available.
typeNoPrevalence or Seroprevalence (exact spelling).
sizeNoSurvey size bucket: min-max (e.g. 0-500, 500-1000) or threshold+ (e.g. 500000+).

Success with rows

{ "data": [ ... ], "timestamp": <unix_epoch_seconds> } — each survey object uses lowercase keys (e.g. id prefixed with s_, survey_start, survey_end, publication_year, region, population, percent1, percent2, surveysize, disease_id, hash_id, disease_name, country_code, country_name, last_update_date, survey_type, pathogens, test_types). Top-level timestamp is a Unix epoch integer (seconds), not an ISO string. The Postman example shows one data row for brevity.

Too many matches

{ "data": { "record_count": <n>, "max_records": <cap> } } with 200.

Errors

  • 500 — Invalid request (generic error body).

Authentication

Authorizationstring
API Key authentication via header

Query parameters

diseaseintegerOptional
Numeric GIDEON disease identifier.
countrystringOptional
GIDEON country code.
typestringOptional
Prevalence or Seroprevalence

Response

OK
datalist of objects
timestampinteger