/diseases/surveys/filter

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** | Name | Required | Description | | --- | --- | --- | | `disease` | No | Numeric GIDEON disease identifier. | | `country` | No | GIDEON country code. | | `survey_start_year` | No | Lower bound on survey start year. | | `survey_end_year` | No | Upper bound on end year; uses end year when present, otherwise start year. | | `test_type` | No | Substring match on test-type labels. | | `pathogen` | No | Substring match on pathogen labels. | | `percentRange` | No | Filter on primary percentage: operators `<`, `>`, `<=`, `>=` plus a number (e.g. `>=10`), or a plain number (treated as **>=** that value). | | `population` | No | Survey population group id (values from filter-options). | | `region` | No | Subdivision (state or equivalent) code from filter-options when available. | | `type` | No | `Prevalence` or `Seroprevalence` (exact spelling). | | `size` | No | Survey 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).