GeoTrustIn 🌍🛡️

GeoTrustIn is a modular, cross-platform geolocation intelligence library. It doesn't just fetch coordinates—it evaluates the confidence of the location data and detects spoofing risks, ensuring your applications can trust the location data they receive.

📦 Installation

Since this library is modular, you can install the specific packages you need. For most browser and React applications, you will want the @geotrustin/web package:

npm install @geotrustin/web

If you only want the underlying data engines without the browser integration:

npm install @geotrustin/core @geotrustin/confidence-engine @geotrustin/spoof-detector

🚀 Quick Start (Web & React)

The @geotrustin/web package wraps the standard HTML5 navigator.geolocation API, making it a drop-in replacement that instantly adds confidence and anti-spoofing metrics.

1. Fetching the Current Position

Use getCurrentPosition to get a single, enriched location snapshot.

import { GeoTrustInWeb } from "@geotrustin/web";

async function fetchSecureLocation() {
  try {
    const location = await GeoTrustInWeb.getCurrentPosition({
      enableHighAccuracy: true,
      timeout: 5000,
    });

    console.log("Latitude:", location.latitude);
    console.log("Longitude:", location.longitude);
    
    // 🛡️ GeoTrustIn Exclusive Metrics:
    console.log("Data Confidence (0-100):", location.confidence);
    console.log("Spoof Risk (0-100):", location.spoofRisk);

    if (location.spoofRisk > 50) {
      console.warn("High probability of location spoofing detected!");
    }
    
  } catch (error) {
    console.error("Failed to fetch location:", error.message);
  }
}

2. Watching the Position (Live Tracking)

If you need to track the user's location in real-time (e.g., for navigation or delivery tracking), use watchPosition.

import { GeoTrustInWeb } from "@geotrustin/web";

// Start watching the position
const watchId = GeoTrustInWeb.watchPosition(
  (location) => {
    console.log("New position update:", location);
    
    if (location.confidence < 70) {
      console.warn("Location accuracy is currently low.");
    }
  },
  (error) => {
    console.error("Tracking error:", error);
  },
  { enableHighAccuracy: true }
);

// Stop watching later on when the component unmounts
GeoTrustInWeb.clearWatch(watchId);

🏗️ Architecture & Packages

This monorepo is divided into specific micro-packages to ensure you only bundle what you need:

• @geotrustin/web: The main entry point for browser environments (React, Next.js, Vue, vanilla JS). Uses navigator.geolocation.
• @geotrustin/core: The central orchestrator that pipes raw coordinates through the confidence and spoofing engines.
• @geotrustin/confidence-engine: Calculates a 0-100 score based on GPS accuracy bounds.
• @geotrustin/spoof-detector: Identifies inconsistencies and flags (like isMockLocation) to calculate a spoof risk score.
• (Coming Soon) @geotrustin/react-native: Native wrappers for iOS and Android environments.

📊 The LocationResult Object

All successful requests return a LocationResult object shaped like this:

interface LocationResult {
  latitude: number;
  longitude: number;
  accuracy: number;        // Raw radius of accuracy in meters
  provider: "gps" | "network" | "fused" | "unknown";
  confidence: number;      // 0-100 score of how accurate the fix is
  spoofRisk: number;       // 0-100 score of how likely the data is faked
  timestamp: number;       // Epoch time in milliseconds
}

📝 License

ISC License.