# Black Hole Physics API
> Black-hole general-relativity maths as an API, computed locally and deterministically. The radius endpoint computes the Schwarzschild radius r_s = 2GM/c² — the event horizon of a non-rotating black hole — from a mass given in kilograms or solar masses, together with the photon sphere at 1.5·r_s and the innermost stable circular orbit (ISCO) at 3·r_s; the Sun would have an event horizon about 2.95 km across and the Earth about 9 mm. The time-dilation endpoint computes the gravitational time-dilation factor √(1 − r_s/r) at a distance r from a mass — a clock deep in a gravity well ticks slower than a far-away clock, and at the horizon time appears to stop. The hawking endpoint computes the Hawking temperature T = ħc³/(8πGMk_B), which is higher for smaller black holes, and the evaporation time, which scales as the cube of the mass — a solar-mass black hole would take about 10^67 years to evaporate. Masses are in kilograms or solar masses and distances in metres, using G, c, ħ and the Boltzmann constant. Everything is computed locally and deterministically, so it is instant and private. Ideal for astrophysics, cosmology, science-communication, simulation and education app developers, black-hole and relativity tools, and physics teaching. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is general-relativity black-hole physics; for special relativity (Lorentz factor, E=mc²) use a relativity 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/schwarzschild-api/..."
```

## Pricing
- **Free** (Free) — 3,750 calls/Mo, 2 req/s
- **Starter** ($5/Mo) — 35,500 calls/Mo, 6 req/s
- **Pro** ($14/Mo) — 216,500 calls/Mo, 15 req/s
- **Mega** ($44/Mo) — 1,305,000 calls/Mo, 40 req/s

## Endpoints

### BlackHole

#### `GET /v1/hawking` — Hawking temperature

**Parameters:**
- `mass` (query, optional, string) — Mass (kg)
- `solar_masses` (query, optional, string) — Or solar masses Example: `1`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/schwarzschild-api/v1/hawking?solar_masses=1"
```

**Response:**
```json
{
    "data": {
        "note": "Hawking temperature T = ħc³/(8πGMk_B) — smaller black holes are hotter. Evaporation time scales as M³; a solar-mass black hole would take ~10^67 years to evaporate.",
        "inputs": {
            "mass_kg": 1.98892e+30,
            "solar_masses": 1
        },
        "evaporation_time_s": 6.617961757605733e+74,
        "hawking_temperature_k": 6.168677824358303e-8,
        "evaporation_time_years": 2.0971055332489585e+67
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:33.596Z",
        "request_id": "a0aca178-bc8a-43b9-b94a-d3b6f7a1f13b"
    },
    "status": "ok",
    "message": "Hawking temperature",
    "success": true
}
```

#### `GET /v1/radius` — Schwarzschild radius

**Parameters:**
- `mass` (query, optional, string) — Mass (kg)
- `solar_masses` (query, optional, string) — Or mass in solar masses Example: `1`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/schwarzschild-api/v1/radius?solar_masses=1"
```

**Response:**
```json
{
    "data": {
        "note": "Schwarzschild radius r_s = 2GM/c² — the event horizon of a non-rotating black hole. The photon sphere is at 1.5·r_s and the innermost stable circular orbit (ISCO) at 3·r_s. The Sun's r_s is about 2.95 km.",
        "inputs": {
            "mass_kg": 1.98892e+30,
            "solar_masses": 1
        },
        "isco_m": 8862.023209,
        "photon_sphere_m": 4431.011605,
        "schwarzschild_radius_m": 2954.007736491099,
        "schwarzschild_radius_km": 2.954007736
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:33.704Z",
        "request_id": "ec8ae164-0570-40f1-8cb9-dba94e738574"
    },
    "status": "ok",
    "message": "Schwarzschild radius",
    "success": true
}
```

#### `GET /v1/time-dilation` — Gravitational time dilation

**Parameters:**
- `mass` (query, optional, string) — Mass (kg)
- `solar_masses` (query, optional, string) — Or solar masses Example: `1`
- `distance` (query, required, string) — Distance r from centre (m) Example: `5908`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/schwarzschild-api/v1/time-dilation?solar_masses=1&distance=5908"
```

**Response:**
```json
{
    "data": {
        "note": "Gravitational time dilation: a clock at radius r ticks at √(1 − r_s/r) of the rate of a far-away clock. Deep in a gravity well time runs slow; at the horizon it appears to stop.",
        "inputs": {
            "mass_kg": 1.98892e+30,
            "distance": 5908
        },
        "inverse_factor": 1.41421541,
        "proper_time_ratio": 0.7071058552,
        "time_dilation_factor": 0.7071058552,
        "schwarzschild_radius_m": 2954.007736
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:33.784Z",
        "request_id": "6c9b0ba3-dc89-41ba-9bb0-3d54617aca6c"
    },
    "status": "ok",
    "message": "Time dilation",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Mass in kg or 'solar_masses', distance in m. Non-rotating (Schwarzschild) black hole. The horizon is at r_s; time dilation diverges there.",
        "service": "schwarzschild-api",
        "formulae": {
            "hawking": "T = ħc³/(8πGMk_B)",
            "schwarzschild": "r_s = 2GM/c²",
            "time_dilation": "√(1 − r_s/r)"
        },
        "constants": {
            "G": 6.6743e-11,
            "c": 299792458,
            "k_B": 1.380649e-23,
            "hbar": 1.054571817e-34,
            "solar_mass_kg": 1.98892e+30
        },
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/radius": "Schwarzschild radius, photon sphere and ISCO from a mass.",
            "GET /v1/hawking": "Hawking temperature and evaporation time of a black hole.",
            "GET /v1/time-dilation": "Gravitational time-dilation factor at a distance from a mass."
        },
        "description": "Black-hole general-relativity calculator: Schwarzschild radius and orbits, gravitational time dilation, and Hawking temperature and evaporation time."
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:33.852Z",
        "request_id": "eb15aa82-147a-448d-83b1-bc54e6a35035"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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