@inceptionai/georacle-sdk

Official SDK for integrating your website with GeOracle - AI-powered Generative Engine Optimization (GEO) platform.

GeOracle bridges the gap as the internet shifts from human readers to AI readers. We help your website become perfectly discoverable by AI systems like ChatGPT, Claude, and Perplexity through GEO (Generative Engine Optimization).

What's New in v0.2.0

Pull-Based GEO Analysis API

New in v0.2.0: Analyze any page's GEO readiness without manual content sync.

npm install @inceptionai/georacle-sdk

import { fetchGeoContext } from '@inceptionai/georacle-sdk/server';

// Analyze a page's GEO readiness
const geoContext = await fetchGeoContext({
  pageContext: {
    locale: 'en-CA',
    regionCode: 'CA',
    categoryPath: '/health-fitness/vitamins',
    categoryTitle: 'Best Women\'s Multivitamins',
    productCount: 7,
    products: [
      { title: 'Vitamin D3', price: { listingPrice: 24.99, currency: 'CAD' } },
      // ... more products
    ],
  },
  requestedMetrics: ['shipping-coverage', 'price-localization', 'tax-calculation'],
});

// Returns:
// {
//   geoReadinessScores: {
//     shippingCoverage: { score: 82, status: 'good', ... },
//     priceLocalization: { score: 100, status: 'excellent', ... },
//     taxCalculation: { score: 78, status: 'good', ... },
//     ...
//   },
//   overallGeoReadiness: { score: 87, grade: 'A', status: 'excellent' },
//   productEnrichments: [ ... ], // Per-product GEO data
//   recommendations: [ ... ], // Actionable improvements
// }

Features

Two Integration Modes

Mode 1: Content Sync (Legacy)

Sync static/semi-static content to GeOracle for GEO analysis.

import { GeOracleClient } from '@inceptionai/georacle-sdk';

const client = new GeOracleClient({
  apiKey: process.env.GEORACLE_API_KEY,
  teamId: process.env.GEORACLE_TEAM_ID,
});

await client.sync({
  id: 'article-1',
  type: 'Article',
  title: 'My Article',
  content: '...',
  url: 'https://example.com/article-1',
});

Mode 2: Page Analysis (New)

Analyze any page's GEO readiness with product-level enrichments.

import { fetchGeoContext } from '@inceptionai/georacle-sdk/server';
import { GeoProvider, useProductEnrichment } from '@inceptionai/georacle-sdk/react';

export default async function Page() {
  const geoContext = await fetchGeoContext({
    pageContext: { ... },
    requestedMetrics: [ ... ],
  });

  return (
    <GeoProvider data={geoContext}>
      <ProductList />
    </GeoProvider>
  );
}

function ProductList() {
  return (
    <div>
      {products.map((product, i) => (
        <ProductCard key={i} product={product} index={i} />
      ))}
    </div>
  );
}

function ProductCard({ product, index }) {
  const geoData = useProductEnrichment(index);
  
  return (
    <div>
      <h2>{product.title}</h2>
      {geoData?.shipping.availableToRegion && (
        <span>Ships in {geoData.shipping.estimatedDays?.min}-{geoData.shipping.estimatedDays?.max} days</span>
      )}
      {geoData?.pricing.taxInfo && (
        <span>+${geoData.pricing.taxInfo.totalTax?.estimated} tax</span>
      )}
    </div>
  );
}

GEO Readiness Metrics

The SDK analyzes 6 key GEO metrics:

1. Shipping Coverage - Availability to your target region
2. Price Localization - Regional currency and pricing
3. Stock Availability - Real-time inventory status
4. Tax Calculation - Regional and federal tax rates
5. Delivery Estimates - Carrier-specific delivery dates
6. Regional Promotions - Location-specific offers

Each metric returns:

• score (0-100)
• status ('excellent' | 'good' | 'fair' | 'poor')
• details (explanation)
• recommendations (actionable improvements)

Framework Support

| Framework | Mode | Status | |-----------|------|--------| | Next.js | Both | ✅ Full support | | React | Page Analysis | ✅ Hooks + Provider | | Vue 3 | Page Analysis | ✅ Composables | | Vanilla JS | Page Analysis | ✅ Direct API access |

Installation

npm install @inceptionai/georacle-sdk
# or
pnpm add @inceptionai/georacle-sdk
# or
yarn add @inceptionai/georacle-sdk

Quick Start

1. Get Your API Key

1. Go to GeOracle Dashboard
2. Navigate to Settings → Integrations
3. Generate an API key (starts with geo_sk_)

2. Set Environment Variables

# .env.local
GEORACLE_API_KEY=geo_sk_your_key_here
GEORACLE_TEAM_ID=your_team_id

3. Analyze a Page (Next.js Example)

// app/[...slug]/page.tsx
import { fetchGeoContext } from '@inceptionai/georacle-sdk/server';
import { GeoProvider, useGeoScores } from '@inceptionai/georacle-sdk/react';

export default async function Page({ params }) {
  const products = await getProducts(params.slug);
  
  const geoContext = await fetchGeoContext({
    pageContext: {
      locale: 'en-CA',
      regionCode: 'CA',
      categoryPath: params.slug,
      categoryTitle: 'Product Category',
      productCount: products.length,
      products: products.map(p => ({
        title: p.title,
        price: { listingPrice: p.price, currency: 'CAD' },
      })),
    },
    requestedMetrics: [
      'shipping-coverage',
      'price-localization',
      'stock-availability',
      'tax-calculation',
    ],
  });

  return (
    <GeoProvider data={geoContext}>
      <main>
        <ProductGrid products={products} />
      </main>
    </GeoProvider>
  );
}

4. Use Data in Components

// components/ProductCard.tsx
'use client';

import { useProductEnrichment, useGeoScores } from '@inceptionai/georacle-sdk/react';

export function ProductCard({ product, index }) {
  const geoData = useProductEnrichment(index);
  const scores = useGeoScores();

  return (
    <div className="product-card">
      <h3>{product.title}</h3>
      <p>${product.price}</p>

      {/* Show shipping info if available */}
      {geoData?.shipping.availableToRegion && (
        <div className="text-green-600">
          ✓ Ships in {geoData.shipping.estimatedDays?.min}-{geoData.shipping.estimatedDays?.max} days
        </div>
      )}

      {/* Show tax estimate */}
      {geoData?.pricing.taxInfo?.totalTax && (
        <small>+${geoData.pricing.taxInfo.totalTax.estimated.toFixed(2)} tax</small>
      )}

      {/* Show compliance badges */}
      {geoData?.compliance.certifications?.map(cert => (
        <span key={cert} className="badge">{cert}</span>
      ))}
    </div>
  );
}

API Reference

fetchGeoContext(request, options)

Fetch GEO analysis for a page.

Parameters:

• request.pageContext - Page metadata and products
• request.requestedMetrics - Array of metrics to analyze
• options.cache - Cache duration in seconds (default: 3600)
• options.apiKey - API key (defaults to env var)

Returns:

{
  pageId: string;
  analyzedAt: string;
  geoReadinessScores: {
    shippingCoverage: GeoScore;
    priceLocalization: GeoScore;
    stockAvailability: GeoScore;
    taxCalculation: GeoScore;
    deliveryEstimates: GeoScore;
    regionalPromotions: GeoScore;
  };
  overallGeoReadiness: {
    score: number;    // 0-100
    grade: string;    // 'A+', 'A', 'B', 'C', 'D', 'F'
    status: string;   // 'excellent', 'needs-improvement', etc.
  };
  productEnrichments: ProductEnrichment[];
  recommendations: Recommendation[];
}

React Hooks

GeoProvider

Wrap your component tree to provide GEO context.

<GeoProvider data={geoContext}>
  <App />
</GeoProvider>

useGeoContext()

Access the full GEO analysis response.

const geoData = useGeoContext();
console.log(geoData?.overallGeoReadiness.score);

useGeoScores()

Get all readiness metrics.

const scores = useGeoScores();
return <div>{scores?.shippingCoverage.score}%</div>;

useProductEnrichment(index)

Get GEO data for a specific product.

const geoData = useProductEnrichment(0);
return <div>{geoData?.shipping.availableToRegion ? 'In Stock' : 'Out of Stock'}</div>;

useOverallScore()

Get the page's overall GEO score.

const overall = useOverallScore();
return <div>Grade: {overall?.grade}</div>;

useRecommendations()

Get actionable improvement recommendations.

const recommendations = useRecommendations();
return (
  <ul>
    {recommendations.map(r => <li key={r.message}>{r.message}</li>)}
  </ul>
);

Vue 3 Composables

import { provideGeoContext, useGeoContext, useProductEnrichment } from '@inceptionai/georacle-sdk/vue';

export default {
  setup() {
    const geoContext = await fetchGeoContext({...});
    provideGeoContext(geoContext);

    const productGeo = useProductEnrichment(0);
    return { productGeo };
  },
};

Schema Utilities

Generate Schema.org JSON-LD for AI discoverability.

import {
  generateArticleSchema,
  generateProductSchema,
  generateFAQSchema,
  injectJsonLd,
} from '@inceptionai/georacle-sdk/schemas';

const schema = generateArticleSchema({
  title: 'My Article',
  description: 'Description',
  publishedAt: '2024-01-15',
  url: 'https://example.com/article',
});

injectJsonLd(schema, 'article-schema');

Error Handling

The SDK gracefully degrades if the GeOracle API is unavailable.

const geoContext = await fetchGeoContext({...});

if (!geoContext) {
  console.log('GeOracle API unavailable - site still works');
  // Render without GEO data
}

Pricing

| Plan | Price | API Calls/Day | |------|-------|---------------| | Free | $0 | 1,000 | | Pro | $49/mo | 100,000 | | Enterprise | Custom | Unlimited |

Each call analyzes a page and up to 100 products.

Support

• 📚 Documentation
• 💬 Discord Community
• 📧 Email Support
• 🐛 Report Issues

License

MIT © GeOracle

Made with ❤️ by the GeOracle team