webxr-geospatial

Dependency-free TypeScript utilities for manually fetching local geospatial data inside WebXR applications.

The package reads from a local API on the same device as the WebXR app:

http://127.0.0.1:8765/location

It does not poll automatically. Trigger a fetch when your app needs a fresh geospatial override, for example from a button.

Install

npm install webxr-geospatial

Fetch a location

import { fetchGeospatialLocation } from "webxr-geospatial";

const result = await fetchGeospatialLocation();

if (result.available) {
  console.log(result.latitude, result.longitude, result.altitude);
} else {
  console.warn(result.message);
}

Select specific fields

Without fields, the full API payload is returned. With fields, only the selected location fields are included.

const result = await fetchGeospatialLocation({
  fields: ["latitude", "longitude", "altitude"]
});

if (result.available) {
  console.log(result.latitude, result.longitude, result.altitude);
}

Available fields:

type GeospatialLocationField =
  | "latitude"
  | "longitude"
  | "altitude"
  | "heading"
  | "horizontalAccuracy"
  | "verticalAccuracy"
  | "headingAccuracy"
  | "timestampMs";

Button-triggered WebXR usage

Use the provider when your app wants to refresh the override manually and read the latest fetched value elsewhere in the WebXR flow.

import { createGeospatialLocationProvider } from "webxr-geospatial";

const provider = createGeospatialLocationProvider();
const button = document.querySelector<HTMLButtonElement>("#refresh-location");

button?.addEventListener("click", async () => {
  const result = await provider.refresh({
    fields: ["latitude", "longitude", "altitude", "heading", "timestampMs"]
  });

  if (!result.available) {
    console.warn(result.message);
  }
});

function updateWebXRScene() {
  const location = provider.getLocation();

  if (location?.available) {
    // Use this location as the app's geospatial override.
    console.log(location.latitude, location.longitude, location.altitude);
  }
}

Configuration

await fetchGeospatialLocation({
  baseUrl: "http://127.0.0.1:8765",
  timeoutMs: 5000,
  signal: abortController.signal
});

baseUrl may point either to the local server root or directly to /location.

Result shape

Successful responses are flat and mirror the local API:

{
  available: true,
  latitude: 52.47,
  longitude: 13.29,
  altitude: 83.4,
  heading: 120.5,
  horizontalAccuracy: 1.8,
  verticalAccuracy: 2.4,
  headingAccuracy: 4.2,
  timestampMs: 1781773200000
}

Unavailable or failed requests return a typed unavailable result:

{
  available: false,
  message: "Noch keine Geospatial-Position verfügbar.",
  errorCode: "unavailable"
}