# Sunscreen & UV API
> Sun-safety maths as an API, computed locally and deterministically — the burn-time, SPF and reapplication numbers a sunscreen, weather or outdoor app keeps people safe with. The burntime endpoint estimates how long until sunburn from the Fitzpatrick skin type (1 very fair to 6 deeply pigmented), the UV index and the SPF: unprotected time is a skin-type base (type II around 15 minutes) scaled by 6 ÷ UV index, and protected time is that times the SPF — so fair type-II skin at UV 8 burns in about 11 minutes bare, or roughly 5½ hours under SPF 30, while very fair type-I skin in extreme UV 11 burns in 5 minutes. The spf endpoint flips it: the SPF needed = your desired minutes outdoors ÷ the unprotected time, with the reminder that real protection plateaus around SPF 30–50. The amount endpoint covers the part people get wrong — about 2 mg/cm², roughly 1 ounce (30 g, a shot glass) for a full adult body, reapplied every two hours — and totals the sunscreen for a day out. Everything is computed locally and deterministically, so it is instant and private. Ideal for sun-safety, weather, skincare and outdoor app developers, UV-alert and reminder tools, and wellness software. Pure local computation — no key, no third-party service, instant. Educational estimates, not medical advice. Live, nothing stored. 3 compute endpoints.

## 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/sunscreen-api/..."
```

## Pricing
- **Free** (Free) — 7,160 calls/Mo, 2 req/s
- **Starter** ($4/Mo) — 56,100 calls/Mo, 6 req/s
- **Pro** ($12/Mo) — 229,200 calls/Mo, 15 req/s
- **Mega** ($37/Mo) — 1,339,000 calls/Mo, 40 req/s

## Endpoints

### Sun

#### `GET /v1/amount` — Sunscreen amount + reapply

**Parameters:**
- `hours_outdoors` (query, required, string) — Hours outdoors Example: `6`
- `coverage` (query, optional, string) — Body fraction exposed 0-1 (default 1) Example: `1`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/sunscreen-api/v1/amount?hours_outdoors=6&coverage=1"
```

**Response:**
```json
{
    "data": {
        "note": "Use ~2 mg/cm² — about 1 oz (30 g, a shot glass) for full-body adult coverage, or a 'nickel of sunscreen' for the face. Reapply every 2 hours, and right after swimming, towelling or heavy sweat. Most people apply a quarter to a half of what they should.",
        "inputs": {
            "coverage": 1,
            "hours_outdoors": 6
        },
        "total_oz": 3.6,
        "total_grams": 102,
        "applications_needed": 3,
        "reapply_every_hours": 2,
        "grams_per_application": 34
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:48.686Z",
        "request_id": "bb54c144-e219-418d-bfea-808b28a55aee"
    },
    "status": "ok",
    "message": "Sunscreen amount",
    "success": true
}
```

#### `GET /v1/burntime` — Time to sunburn

**Parameters:**
- `skin_type` (query, required, string) — Fitzpatrick type 1-6 Example: `2`
- `uv_index` (query, required, string) — UV index (0-16) Example: `8`
- `spf` (query, optional, string) — Sunscreen SPF (default 1 = none) Example: `30`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/sunscreen-api/v1/burntime?skin_type=2&uv_index=8&spf=30"
```

**Response:**
```json
{
    "data": {
        "note": "Roughly: protected burn time = unprotected × SPF, where unprotected ≈ a skin-type base (type II ~15 min) scaled by 6 ÷ UV index. But sunscreen breaks down — reapply every 2 hours regardless of SPF, and sooner with sweat or water. Educational, not a substitute for caution or a doctor.",
        "inputs": {
            "spf": 30,
            "uv_index": 8,
            "skin_type": 2
        },
        "uv_risk": "very high",
        "protected_minutes_to_burn": 338,
        "unprotected_minutes_to_burn": 11
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:48.760Z",
        "request_id": "a6b703c9-d929-4bd8-84b3-c73e4db337fe"
    },
    "status": "ok",
    "message": "Burn time",
    "success": true
}
```

#### `GET /v1/spf` — SPF needed for a duration

**Parameters:**
- `skin_type` (query, required, string) — Fitzpatrick type 1-6 Example: `3`
- `uv_index` (query, required, string) — UV index Example: `8`
- `desired_minutes` (query, required, string) — Minutes outdoors Example: `240`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/sunscreen-api/v1/spf?skin_type=3&uv_index=8&desired_minutes=240"
```

**Response:**
```json
{
    "data": {
        "note": "SPF needed = desired minutes ÷ unprotected burn time. Real-world advice caps out around SPF 30–50 — above that the extra protection is marginal (SPF 30 blocks ~97 %, SPF 50 ~98 %) and people apply too little. Reapply rather than chase a huge number.",
        "inputs": {
            "uv_index": 8,
            "skin_type": 3,
            "desired_minutes": 240
        },
        "spf_needed": 16,
        "unprotected_minutes": 15
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:48.828Z",
        "request_id": "43aa03b8-cee8-44e9-aa4c-66fdffa28ead"
    },
    "status": "ok",
    "message": "SPF needed",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Fitzpatrick skin type 1-6; UV index 0-16. Protected time ≈ unprotected × SPF; reapply every 2 hours. ~2 mg/cm² (≈ 1 oz full body). Educational estimates — not medical advice; people with sensitive skin or conditions should be cautious.",
        "service": "sunscreen-api",
        "endpoints": {
            "GET /v1/spf": "SPF needed to stay out for a target number of minutes.",
            "GET /v1/meta": "This document.",
            "GET /v1/amount": "Sunscreen amount per application and reapplications for time outdoors.",
            "GET /v1/burntime": "Unprotected and protected time to sunburn from skin type, UV index and SPF."
        },
        "description": "Sun-safety maths: time to sunburn by skin type/UV/SPF, the SPF needed for a target time, and sunscreen amount & reapplication."
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:48.918Z",
        "request_id": "e2fbde2a-1db4-4bfb-84a1-c6f30a6e64b6"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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