# CalculationTime API

Reliable time, date, geo, holiday, solar, astronomy, and utility calculations for apps, websites, dashboards, and AI agents.

Base URL:

```text
https://api.calculationtime.com
```

The API is built around visible assumptions and auditable calculation methods. It is useful when a product needs more than a loose snippet: scheduling rules, local time, business-day windows, geospatial estimates, solar geometry, or calculation utilities that should be repeatable and explainable.

## Public Demo Endpoint

### `GET /v1/time/utc`

Returns the API host's current UTC timestamp, Unix seconds, Unix milliseconds, and clock-accuracy wording. This is public and exists for proof/status surfaces, not as a hard SLA statement.

```bash
curl 'https://api.calculationtime.com/v1/time/utc'
```

### `GET /v1/status`

Returns live service status, route-family inventory, uptime for the current API process, and measured-status wording. This endpoint deliberately reports that no public SLA is claimed yet.

```bash
curl 'https://api.calculationtime.com/v1/status'
```

### `GET /api/v1/utility/tagline`

Returns one deterministic daily tagline for the current UTC date. It is public, lightweight, and edge-cacheable.

```bash
curl 'https://api.calculationtime.com/api/v1/utility/tagline'
```

Example response:

```json
{
  "date": "2026-07-29",
  "tagline": "Pi never repeats itself, but it keeps the circle honest.",
  "category": "Mathematical Anomalies"
}
```

The selected tagline is seeded by `YYYY-MM-DD` in UTC, so every user receives the same line for the same global calendar day.

## API Families

- Time by coordinate.
- Geospatial calculations.
- Date calculations.
- Holiday/business-day helpers.
- Solar position calculations.
- Astronomy ephemeris calculations.
- Observatory private share links.
- Daily utility content.

## Accuracy Model

This API does not estimate time from longitude. It resolves the coordinate to an IANA timezone identifier using geographic timezone boundary lookup, then calculates local time with IANA timezone rules from the server runtime.

This matters because real time is political as well as geographic: daylight saving rules, island territories, border towns, and historical rule changes cannot be handled by simple UTC offset math.

## Time Endpoints

### `GET /v1/time`

Query parameters:

- `lat`: latitude, `-90` to `90`.
- `lon`: longitude, `-180` to `180`.
- `at`: optional ISO-8601 timestamp, epoch seconds, or epoch milliseconds. Defaults to now.

Example:

```bash
curl 'https://api.calculationtime.com/v1/time?lat=48.137154&lon=11.576124&at=2026-07-29T12:00:00Z' \
  -H 'X-API-Key: your-key'
```

### `POST /v1/time/batch`

Body:

```json
{
  "at": "2026-07-12T12:00:00Z",
  "points": [
    { "lat": 48.137154, "lon": 11.576124 },
    { "lat": -33.8688, "lon": 151.2093 }
  ]
}
```

Maximum batch size: 100 points.

### `GET /health`

Basic service health response. Public.

### `GET /v1/canary`

Protected monitoring endpoint for external uptime probes that need to verify the API-key path as well as the public health path.

```bash
curl 'https://api.calculationtime.com/v1/canary' \
  -H 'X-API-Key: monitoring-key'
```

Use a private monitoring-only key for this endpoint. Do not place that key in public site code, public docs, screenshots, or client-side JavaScript.

## Observatory Share Endpoints

### `POST /v1/observatory/share`

Creates an unlisted private share token for Observatory/Orrery links. The response includes an expiry timestamp and a `https://calculationtime.com/observatory/share/{token}/` URL. Share responses set `X-Robots-Tag: noindex, nofollow`.

```bash
curl 'https://api.calculationtime.com/v1/observatory/share' \
  -H 'Content-Type: application/json' \
  -d '{"poster":"moment","date":"2026-08-01","location":{"name":"Munich","lat":48.137154,"lng":11.576124},"time":"12:00","ttl_days":30}'
```

### `GET /v1/observatory/share/{token}`

Resolves a valid, unexpired token into the stored Observatory parameters. Expired or invalid tokens return `404`.

## Astronomy Endpoints

### `GET /v1/astronomy/ephemeris`

Returns geocentric and heliocentric telemetry for the Sun, Moon, and planets on a requested UTC date or timestamp.

```bash
curl 'https://api.calculationtime.com/v1/astronomy/ephemeris?date=2029-10-21' \
  -H 'X-API-Key: your-key'
```

Query parameters:

- `date`: ISO date or timestamp, for example `2029-10-21` or `2029-10-21T00:00:00Z`.

The beta endpoint accepts dates from `1900-01-01` through `2100-12-31`. Results include astronomical-unit vectors, heliocentric distance, geocentric distance, right ascension, declination, and ecliptic longitude/latitude. It is designed as the backend feed for semantic astronomy pages and interactive orrery hydration, not as a location-specific sky visibility forecast.

## Geospatial Endpoints

### `GET /v1/geo/distance`

Calculates distance and initial bearing between two coordinates.

```bash
curl 'https://api.calculationtime.com/v1/geo/distance?from_lat=48.137154&from_lon=11.576124&to_lat=52.52&to_lon=13.405' \
  -H 'X-API-Key: your-key'
```

Returns kilometers, miles, meters, nautical miles, bearing degrees, and compass direction.

### `GET /v1/geo/midpoint`

Calculates the great-circle midpoint between two coordinates.

```bash
curl 'https://api.calculationtime.com/v1/geo/midpoint?from_lat=48.137154&from_lon=11.576124&to_lat=52.52&to_lon=13.405' \
  -H 'X-API-Key: your-key'
```

### `GET /v1/geo/bounding-box`

Returns a spherical-approximation bounding box around a coordinate and radius.

```bash
curl 'https://api.calculationtime.com/v1/geo/bounding-box?lat=48.137154&lon=11.576124&radius_km=50' \
  -H 'X-API-Key: your-key'
```

### `GET /v1/geo/elevation`

Returns terrain elevation for a latitude/longitude using the Open-Meteo Elevation API backed by Copernicus DEM GLO-90.

```bash
curl 'https://api.calculationtime.com/v1/geo/elevation?lat=48.137154&lon=11.576124' \
  -H 'X-API-Key: your-key'
```

This is open-data terrain elevation, not survey-grade property elevation, building height, or tree-canopy height.

## Solar Endpoints

### `GET /v1/solar/position`

Returns local solar geometry for a coordinate and UTC timestamp without calling a paid provider.

```bash
curl 'https://api.calculationtime.com/v1/solar/position?lat=48.137154&lon=11.576124&at=2026-07-26T12:00:00Z' \
  -H 'X-API-Key: your-key'
```

The response includes solar azimuth, elevation, apparent elevation, zenith, hour angle, declination, equation of time, and daylight state. Terrain horizon, buildings, trees, weather, and local obstructions are not included in this endpoint.

## Date Endpoints

### `GET /v1/date/difference`

Calculates calendar day difference.

```bash
curl 'https://api.calculationtime.com/v1/date/difference?start=2026-07-12&end=2026-08-01' \
  -H 'X-API-Key: your-key'
```

### `GET /v1/date/add`

Adds years, months, weeks, and days to a date.

```bash
curl 'https://api.calculationtime.com/v1/date/add?start=2026-07-12&months=1&days=5' \
  -H 'X-API-Key: your-key'
```

### `POST /v1/date/business-days`

Counts business days between two dates, excluding Saturdays, Sundays, and optional holiday dates.

```json
{
  "start": "2026-07-12",
  "end": "2026-07-31",
  "holidays": ["2026-07-20"]
}
```

## API Keys

Set `TIME_API_KEYS` to a comma-separated list of accepted keys. Clients may send either:

- `Authorization: Bearer <key>`
- `X-API-Key: <key>`

Most calculation endpoints require an API key on the public service. Public demo and health endpoints do not.

Keys can optionally be scoped as `customer_id:key-value` so rate limits and usage logs can identify the customer without logging the secret.

## CORS

Browser access is deliberately allowlisted, not wildcarded. The default allowed origins are:

- `https://www.calculationtime.com`
- `https://calculationtime.com`
- `https://buildaiops.com`
- `http://localhost:3000`
- `http://127.0.0.1:3000`

Override with `CORS_ORIGINS` as a comma-separated list when staging or production origins change.

## Rate Limiting

Set `RATE_LIMIT_PER_MINUTE` to control basic in-process rate limiting. The default is `120` requests per minute per customer. Set `TIME_API_CUSTOMER_RATE_LIMITS` to a JSON object such as `{"customer_a":240}` for customer-specific limits. Set the default to `0` only behind a stronger gateway-level limiter.

## Deterministic Cache

Set `TIME_API_CACHE=memory` for the default in-process cache, `TIME_API_CACHE=off` to disable it, or `TIME_API_CACHE=redis` only after Redis is deliberately provisioned and `REDIS_URL` is configured.

The API does not cache current-time responses where `at` is omitted. It can cache deterministic inputs such as explicit timestamp coordinate conversions, date calculations, business-day calculations, distance, midpoint, and bounding-box results.

## Logging

The Fastify HTTP layer emits structured request logs with route, status, latency, customer id, API key fingerprint, and cache status. It avoids logging request bodies, query inputs, or raw API keys.

## Use Cases

CalculationTime API is useful for:

- Local time and timezone-aware scheduling.
- Payroll, billing, SLA, and deadline windows.
- Business-day and holiday-aware planning.
- Field-service distance/radius checks.
- Delivery, dispatch, and branch proximity tools.
- Solar angle, outdoor-work, and education prototypes.
- Astronomy and time explainer pages.
- AI-agent workflows that need repeatable calculation calls.

## Commercial Notes

This API is suitable for scheduling, compliance timestamps, logistics, CRM records, remote workforce tools, event planning, travel, billing cutoffs, and time-sensitive customer notifications.

Geospatial endpoints are suitable for territory checks, routing estimates, field-service assignment, delivery radius filters, branch proximity tools, and customer segmentation. They are not a replacement for surveyed legal boundaries or turn-by-turn routing engines.

Date endpoints are suitable for billing windows, SLA calculations, business-day estimates, subscription periods, due dates, and payroll-like date workflows. Jurisdiction-specific holidays should be supplied by the client or a future jurisdiction-holiday module.

Public commercial usage should account for:

- API keys per customer.
- Rate limits per customer.
- Usage logging without storing unnecessary personal data.
- SLA wording tied to IANA timezone database freshness.
- Versioned response schema.
- Monitoring and external uptime checks.

## Example Files

Internal example pack:

```text
/root/.openclaw/workspace/ops/calculationtime/promotion/api-examples/
```

That pack contains curl, Node.js, Python, and agent-integration notes.