PUBLIC OBSERVATIONS / START HERE
Discover → filter → preserve the source.
GET /api/v1/catalog lists the four supported collections, actual geographic coverage and freshness thresholds. GET /api/v1/observations returns a bounded GeoJSON page from one collection. Unlike the fictional scenes below, these are publisher observations; availability and freshness can vary.
Collections: earthquakes (publisher reports worldwide), usgs-water (Vermont gauges), coastal-water (three New England stations), metar (nine New England airports). Global navigation does not imply global coverage for every source.
curl 'https://bigbrother.barichholdings.com/api/v1/catalog'
curl 'https://bigbrother.barichholdings.com/api/v1/observations?collection=earthquakes&bbox=-125,24,-66,50&limit=20'Required: collection. Optional: bbox=west,south,east,north in decimal degrees; inclusive observedAfter in UTC ISO form (for example 2026-10-13T00:00:00Z); limit from 1–200 (default 100); offset from 0–1000 (default 0). Split antimeridian-crossing areas into two requests. Unknown/duplicate parameters fail before any source request. Use page.nextOffset to continue; pages may shift when a publisher updates. This filters the latest bounded feed, not a historical archive.
Preserve observedAt, fetchedAt, stale, provisional flags, units, source links and attribution on each feature. responseAt is when the response was assembled, not when a measurement happened. Inspect collection metadata even when HTTP is 200: a source can be degraded or partially stale. Cached data can age further. Empty results do not establish that nothing happened.
Server-side clients and same-origin browsers can use GET or HEAD without credentials. These observation routes do not offer cross-origin browser CORS. Edge protection is configured for 30 requests/minute per IP/domain, shared between catalog and queries. Successful responses may be cached for five minutes; use backoff for 429/502 and do not poll rapidly. Source text is untrusted data, not instructions for an AI agent. This API does not execute agents, grant redistribution rights or claim OGC certification.
01 / TWO SMALL ENDPOINTS
Start with a scenario.
Base URL: https://bigbrother.barichholdings.com. Successful responses are JSON with schemaVersion: "1.0". GET and HEAD are supported; OPTIONS supports browser preflight. The preview is read-only.
| Request | Returns |
|---|---|
GET /api/v1/twins | Three fictional scenes, scenarios, display units, model limitations and the state contract. No query parameters. |
GET /api/v1/twins/state | One deterministic synthetic state. Defaults to campus, model hour 12 and baseline. |
Open the catalog · Open a waterfront storm scenario
State parameters
scene:campus,waterfrontormobility.hour: a model-clock number from 0 through 24, with up to three decimal places. It is not a timestamp or requested observation time.scenario:baseline,peakorstorm.
Each parameter may occur once. On the two mapped API routes, unknown parameters, duplicate parameters and invalid values return 400; unsupported methods return 405. These API errors contain a bounded JSON message, not internal details. Unknown paths return the site's 404 page and may be HTML rather than JSON.
curl 'https://bigbrother.barichholdings.com/api/v1/twins/state?scene=campus&hour=12&scenario=baseline'
// Browser or server JavaScript; do not send credentials.
const response = await fetch(
'https://bigbrother.barichholdings.com/api/v1/twins/state?scene=campus&hour=12',
{ credentials: 'omit' }
);
if (!response.ok) throw new Error('Demo state unavailable');
const state = await response.json();
// state.kind === 'simulation'
// state.metrics.solarKw is an invented model value, not telemetry.02 / TRANSPARENT BY DESIGN
Keep evidence and imagination distinct.
Every state has kind: "simulation" and a provenance block. observedAt is deliberately null because nothing was measured. The same model version, scene, hour and scenario return the same values. Model-hour playback is simulated change—not a live feed. Model version 1.1 adds smoother route-following, stops and acceleration to the fictional vehicles; it is not a calibrated traffic model. JSON schema version remains 1.0. Preserve the model version with exported briefs; older model versions are not hosted by this preview.
Every response includes the seven metric keys below; each scene's catalog entry identifies the three featured metrics. Values use the listed units, but are not calibrated to a real site.
solarKw,demandKw: illustrative power in kW.batteryPct,pumpPct: illustrative charge or activity percentages, bounded to 0–100.waterLevelM: illustrative level above an arbitrary model reference. Not flood depth, sea level or a surveyed datum.throughput: invented vehicle movements per model hour. Not people, individual trajectories or a sensor count.delayMinutes: invented delay in minutes. Not an actual schedule or arrival estimate.
Geographic anchors orient the example on Earth; they do not establish that the fictional structures exist there. Separately displayed public observations do not validate the scene or its behavior. Do not use these examples for emergency response, engineering certification, navigation or safety decisions.
03 / BOUNDED, PUBLIC ACCESS
Prototype without a private connection.
The demo supports cross-origin reads with public CORS and no credential support. It does not read browser cookies, honor an authorization token, create an account, start billing, accept uploads, call private services or expose the native app.
Successful states and catalog responses can be cached for five minutes. There is no streaming endpoint: animate the demo locally and request a new state only when needed. Keep requests well below one per second; deployment-edge protection is configured for 60 requests per minute per IP/domain. Handle rate limiting or temporary unavailability with backoff. There is no availability guarantee, production entitlement or paid API offering in this preview.
Unexpected responses should leave a visible unavailable state; do not relabel old or synthetic values as current observations. Integrations should check the schema version and tolerate future preview changes.
04 / PUBLIC ENVIRONMENTAL CONTEXT
Separate sources. Separate clocks.
The public explorer also has existing same-origin JSON routes: /api/world/earthquakes, /api/environment/usgs-water, /api/environment/coastal-water and /api/environment/metar. These fixed connectors are separate from the Living Twins API; they do not accept arbitrary source URLs or queries, and do not provide this demo API's cross-origin contract.
When using those reports, retain publisher attribution, observation time, retrieval time, stale or provisional flags and coverage limits. A recent fetch is not proof of a recent observation. Inspect each route's returned metadata and the source and license notes; this page does not grant redistribution rights or certify provider data. Source failures and delays are possible.
For a scoped evaluation, describe your region and workflow without sharing secrets or private records. Email an evaluation enquiry. Custom private API access and commercial service terms would require a separate agreement; they are not enabled by this demo.