GeOracle SDK for integrating custom websites with GeOracle AI platform - Pull-based GEO analysis API
npm install @inceptionai/georacle-sdkOfficial 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).
---
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
// }
`
---
#### 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 (
function ProductCard({ product, index }) {
const geoData = useProductEnrichment(index);
return (
$3
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)$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
pnpm add @inceptionai/georacle-sdk
or
yarn add @inceptionai/georacle-sdk
`---
Quick Start
$3
1. Go to GeOracle Dashboard
2. Navigate to Settings → Integrations
3. Generate an API key (starts with
geo_sk_)$3
`bash
.env.local
GEORACLE_API_KEY=geo_sk_your_key_here
GEORACLE_TEAM_ID=your_team_id
`$3
`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 (
);
}
`$3
`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 (
{product.title}
${product.price}
{/ Show shipping info if available /}
{geoData?.shipping.availableToRegion && (
✓ Ships in {geoData.shipping.estimatedDays?.min}-{geoData.shipping.estimatedDays?.max} days
)} {/ Show tax estimate /}
{geoData?.pricing.taxInfo?.totalTax && (
+${geoData.pricing.taxInfo.totalTax.estimated.toFixed(2)} tax
)}
{/ Show compliance badges /}
{geoData?.compliance.certifications?.map(cert => (
{cert}
))}
);
}
`---
API Reference
$3
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:
`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 {scores?.shippingCoverage.score}%;
`####
useProductEnrichment(index)
Get GEO data for a specific product.`tsx
const geoData = useProductEnrichment(0);
return {geoData?.shipping.availableToRegion ? 'In Stock' : 'Out of Stock'};
`####
useOverallScore()
Get the page's overall GEO score.`tsx
const overall = useOverallScore();
return Grade: {overall?.grade};
`####
useRecommendations()
Get actionable improvement recommendations.`tsx
const recommendations = useRecommendations();
return (
{recommendations.map(r => - {r.message}
)}
);
`$3
`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
}
``---
| 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.
---
- 📚 Documentation
- 💬 Discord Community
- 📧 Email Support
- 🐛 Report Issues
---
MIT © GeOracle
---
Made with ❤️ by the GeOracle team