# Epidemiology API
> Epidemiology-basics maths as an API, computed locally and deterministically. The herd-immunity endpoint computes the herd-immunity threshold HIT = 1 − 1/R0 — the immune fraction of a population at which an outbreak can no longer sustain itself — from the basic reproduction number R0, and adjusts for an imperfect vaccine by dividing by its efficacy, so a disease with R0 = 3 needs about 67 % immune (74 % vaccinated with a 90 %-effective vaccine) while measles at R0 ≈ 15 needs about 93 %. The r-effective endpoint computes the effective reproduction number Re = R0 · susceptible fraction and flags whether the epidemic is growing (Re > 1) or shrinking. The final-size endpoint solves the final-epidemic-size equation Z = 1 − e^(−R0·Z) for the eventual attack rate of an unmitigated SIR epidemic — about 80 % at R0 = 2. The doubling-time endpoint gives the case-doubling time from a growth rate, or from R0 and the serial interval. Fractions are 0–1 and percentages are derived. Everything is computed locally and deterministically, so it is instant and private. Ideal for public-health, epidemiology-education, dashboard, science-communication and outbreak-planning app developers, herd-immunity and reproduction-number tools, and health software. Simple compartmental relations for education and planning, not a substitute for full epidemiological modelling. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 4 endpoints. This is epidemiology basics; for population-genetics Hardy-Weinberg use a genetics API.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/epidemic-api/..."
```

## Pricing
- **Free** (Free) — 4,250 calls/Mo, 2 req/s
- **Starter** ($5/Mo) — 42,500 calls/Mo, 6 req/s
- **Pro** ($14/Mo) — 199,000 calls/Mo, 15 req/s
- **Mega** ($42/Mo) — 1,215,000 calls/Mo, 40 req/s

## Endpoints

### Epidemiology

#### `GET /v1/doubling-time` — Case doubling time

**Parameters:**
- `growth_rate` (query, optional, string) — Daily growth rate
- `r0` (query, optional, string) — R0 (with serial interval) Example: `2`
- `serial_interval` (query, optional, string) — Serial interval (days) Example: `5`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/epidemic-api/v1/doubling-time?r0=2&serial_interval=5"
```

**Response:**
```json
{
    "data": {
        "note": "Doubling time = ln2 / growth rate. From R0 and the serial interval, growth rate ≈ ln(R0)/serial interval.",
        "inputs": {
            "growth_rate": 0.13862944
        },
        "doubling_time_days": 5
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:17.888Z",
        "request_id": "923ed2c7-476d-46f8-866a-a29660f8c0d4"
    },
    "status": "ok",
    "message": "Doubling time",
    "success": true
}
```

#### `GET /v1/final-size` — Final epidemic size

**Parameters:**
- `r0` (query, required, string) — Basic reproduction number R0 Example: `2`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/epidemic-api/v1/final-size?r0=2"
```

**Response:**
```json
{
    "data": {
        "note": "Final epidemic size (attack rate) solves Z = 1 − e^(−R0·Z) — the eventual fraction infected in an unmitigated SIR epidemic. R0=2 gives ≈80%.",
        "inputs": {
            "r0": 2
        },
        "final_size": 0.79681213,
        "final_size_percent": 79.681213
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:17.981Z",
        "request_id": "decf139c-d789-40ef-958a-cfbfb14d7af0"
    },
    "status": "ok",
    "message": "Final epidemic size",
    "success": true
}
```

#### `GET /v1/herd-immunity` — Herd-immunity threshold

**Parameters:**
- `r0` (query, required, string) — Basic reproduction number R0 Example: `3`
- `vaccine_efficacy` (query, optional, string) — Vaccine efficacy (0–1) Example: `0.9`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/epidemic-api/v1/herd-immunity?r0=3&vaccine_efficacy=0.9"
```

**Response:**
```json
{
    "data": {
        "note": "Herd-immunity threshold HIT = 1 − 1/R0 — the immune fraction at which spread stops. Adjust for an imperfect vaccine by dividing by its efficacy. Measles (R0≈15) needs ≈93%.",
        "inputs": {
            "r0": 3,
            "vaccine_efficacy": 0.9
        },
        "herd_immunity_percent": 66.6667,
        "herd_immunity_threshold": 0.666667,
        "vaccination_percent_needed": 74.0741,
        "vaccination_coverage_needed": 0.740741
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:18.080Z",
        "request_id": "54b8f2bb-cf65-4f4d-aee2-e00a8ebbf3fa"
    },
    "status": "ok",
    "message": "Herd immunity threshold",
    "success": true
}
```

#### `GET /v1/r-effective` — Effective reproduction number

**Parameters:**
- `r0` (query, required, string) — Basic reproduction number R0 Example: `3`
- `immune_fraction` (query, optional, string) — Immune fraction (0–1) Example: `0.5`
- `susceptible_fraction` (query, optional, string) — Or susceptible fraction

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/epidemic-api/v1/r-effective?r0=3&immune_fraction=0.5"
```

**Response:**
```json
{
    "data": {
        "note": "Effective reproduction number Re = R0 · susceptible fraction. The epidemic grows while Re > 1 and declines once Re < 1.",
        "inputs": {
            "r0": 3,
            "susceptible_fraction": 0.5
        },
        "status": "growing",
        "r_effective": 1.5,
        "epidemic_growing": true
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:18.185Z",
        "request_id": "7b1416d6-b169-4c2f-84f6-80b3676d508f"
    },
    "status": "ok",
    "message": "Effective reproduction number",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/epidemic-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "notes": "R0 is the basic reproduction number; fractions are 0–1, percentages are derived. Simple compartmental (SIR) relations for education and planning, not a substitute for epidemiological modelling.",
        "service": "epidemic-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/final-size": "Final epidemic size (attack rate) from R0.",
            "GET /v1/r-effective": "Effective reproduction number from R0 and the susceptible fraction.",
            "GET /v1/doubling-time": "Doubling time from a growth rate, or from R0 and the serial interval.",
            "GET /v1/herd-immunity": "Herd-immunity threshold from R0 (with optional vaccine efficacy)."
        },
        "description": "Epidemiology basics: herd-immunity threshold, effective reproduction number, final epidemic size and doubling time."
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:18.266Z",
        "request_id": "9678453c-1691-4950-b6de-712ffac37389"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/epidemic-api
OpenAPI spec: https://www.oanor.com/api/epidemic-api/openapi.json