# Sample Size API
> Survey and poll sample-size planning as an API, computed locally and deterministically. The proportion endpoint computes the number of respondents needed to estimate a proportion within a target margin of error at a chosen confidence level, n = z²·p(1−p)/E², defaulting to the worst-case p = 0.5 that maximises the required size, with an optional finite-population correction n/(1 + (n−1)/N) for a known population — the classic ±5 % margin at 95 % confidence needs 385 responses, ±3 % needs 1 068, and capping the population at 1 000 cuts the ±5 % requirement to 278. The mean endpoint sizes a sample for estimating a mean to within a margin of error from the standard deviation, n = (z·σ/E)². The margin endpoint inverts the relationship, returning the margin of error a given sample size actually achieves. The critical z-value is computed from the confidence level with a high-accuracy inverse-normal so any confidence works, not just the textbook 90/95/99 %. Margins, proportions and confidence are decimals (0.05, 0.5, 0.95). Everything is computed locally and deterministically, so it is instant and private. Ideal for market-research, polling, UX-research, survey-platform, product-analytics and statistics-education app developers, study-planning and sample-size tools, and research software. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is sample-size planning with the normal approximation; for A/B-test significance use an A/B-test API and for descriptive statistics a statistics 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/samplesize-api/..."
```

## Pricing
- **Free** (Free) — 6,200 calls/Mo, 2 req/s
- **Starter** ($6/Mo) — 62,000 calls/Mo, 6 req/s
- **Pro** ($16/Mo) — 280,000 calls/Mo, 15 req/s
- **Mega** ($50/Mo) — 1,550,000 calls/Mo, 40 req/s

## Endpoints

### SampleSize

#### `GET /v1/margin` — Margin of error for a sample size

**Parameters:**
- `sample_size` (query, required, string) — Sample size n Example: `385`
- `confidence` (query, optional, string) — Confidence level Example: `0.95`
- `proportion` (query, optional, string) — Proportion (default 0.5)
- `std_dev` (query, optional, string) — σ for a mean instead

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/samplesize-api/v1/margin?sample_size=385&confidence=0.95"
```

**Response:**
```json
{
    "data": {
        "kind": "proportion",
        "note": "Proportion margin of error E = z·√(p(1−p)/n). A sample of 385 gives about ±5 % at 95 %.",
        "inputs": {
            "confidence": 0.95,
            "proportion": 0.5,
            "sample_size": 385
        },
        "z_score": 1.959964,
        "margin_of_error": 0.04994451,
        "margin_of_error_percent": 4.994451
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:22.175Z",
        "request_id": "da6c5007-d870-4981-acd8-e8d04727955e"
    },
    "status": "ok",
    "message": "Margin of error",
    "success": true
}
```

#### `GET /v1/mean` — Sample size for a mean

**Parameters:**
- `margin_of_error` (query, required, string) — Margin of error (units of σ) Example: `2`
- `std_dev` (query, required, string) — Standard deviation σ Example: `10`
- `confidence` (query, optional, string) — Confidence level Example: `0.95`
- `population` (query, optional, string) — Population size N

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/samplesize-api/v1/mean?margin_of_error=2&std_dev=10&confidence=0.95"
```

**Response:**
```json
{
    "data": {
        "note": "Mean sample size n = (z·σ/E)². Uses the normal (z) approximation, appropriate when σ is known or the sample is large.",
        "inputs": {
            "std_dev": 10,
            "confidence": 0.95,
            "margin_of_error": 2
        },
        "z_score": 1.959964,
        "unrounded": 96.0365,
        "required_sample_size": 97
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:22.286Z",
        "request_id": "d4f5e832-2573-4472-9baf-59b0883ed40b"
    },
    "status": "ok",
    "message": "Sample size for a mean",
    "success": true
}
```

#### `GET /v1/proportion` — Sample size for a proportion

**Parameters:**
- `margin_of_error` (query, required, string) — Target margin of error (e.g. 0.05) Example: `0.05`
- `confidence` (query, optional, string) — Confidence level (e.g. 0.95) Example: `0.95`
- `proportion` (query, optional, string) — Expected proportion (default 0.5)
- `population` (query, optional, string) — Population size N (finite correction)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/samplesize-api/v1/proportion?margin_of_error=0.05&confidence=0.95"
```

**Response:**
```json
{
    "data": {
        "note": "Proportion sample size n = z²·p(1−p)/E²; p = 0.5 is the worst case (largest n). With a population N the finite-population correction is applied. A ±5 % margin at 95 % needs 385.",
        "inputs": {
            "confidence": 0.95,
            "proportion": 0.5,
            "margin_of_error": 0.05
        },
        "z_score": 1.959964,
        "unrounded": 384.1459,
        "required_sample_size": 385
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:22.395Z",
        "request_id": "776ba2fe-fbf4-4b28-9c11-ab5961ff28e2"
    },
    "status": "ok",
    "message": "Sample size for a proportion",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Margin of error and proportion as decimals (0.05 = ±5 %, 0.5 = 50 %); confidence as a decimal (0.95). Optional finite population N applies the correction. Uses the normal (z) approximation; for hypothesis testing use an A/B-test API.",
        "service": "samplesize-api",
        "endpoints": {
            "GET /v1/mean": "Required sample size for estimating a mean.",
            "GET /v1/meta": "This document.",
            "GET /v1/margin": "Margin of error achieved for a given sample size.",
            "GET /v1/proportion": "Required sample size for a proportion (survey/poll)."
        },
        "description": "Survey / poll sample-size planning: required n for a target margin of error, and margin of error for a given n, for a proportion or a mean."
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:22.483Z",
        "request_id": "7c1f666f-345f-43b6-8758-079b2e6af5cc"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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