@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

$3

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

``bash
npm install @inceptionai/georacle-sdk
`

`typescript
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

$3

#### Mode 1: Content Sync (Legacy)
Sync static/semi-static content to GeOracle for GEO analysis.

`typescript
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.

`typescript
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 (



);
}

function ProductList() {
return (


Each metric returns:
- score (0-100)
- status ('excellent' | 'good' | 'fair' | 'poor')
- details (explanation)
- recommendations (actionable improvements)

$3

| 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

`bash
npm install @inceptionai/georacle-sdk


or

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

$3

`bash


.env.local

`typescript
// 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 (



`typescript
// 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 (


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:
`typescript
{
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[];
}
`

$3

#### GeoProvider
Wrap your component tree to provide GEO context.

`tsx



`

#### useGeoContext()
Access the full GEO analysis response.

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

#### useGeoScores()
Get all readiness metrics.

`tsx
const scores = useGeoScores();
return

#### useProductEnrichment(index)
Get GEO data for a specific product.

`tsx
const geoData = useProductEnrichment(0);
return

#### useOverallScore()
Get the page's overall GEO score.

`tsx
const overall = useOverallScore();
return

#### useRecommendations()
Get actionable improvement recommendations.

`tsx
const recommendations = useRecommendations();
return (


{recommendations.map(r =>
• {r.message}
)}

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

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

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

$3

Generate Schema.org JSON-LD for AI discoverability.

`typescript
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.

`typescript
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