GEOmatic AI – REST Integration Guide (Headless)

GEOmatic AI – REST Integration Guide (Headless) #

1) Overview #

WordPress REST base: https://your-site.com/wp-json/

Namespaces exposed by GEOmatic AI:
geomatic/v1, geoai/v1, and geomatic-ai/v1.

Token authentication via the X-Geoai-Token header (token set in the plugin settings). IP rate limit: ~60 requests / 10 minutes. CORS can be enabled via an origin allowlist.

Preflight/OPTIONS is handled automatically if your domain is allowed in the CORS allowlist.

2) Security & Access #

a) API Token (standard, recommended) #

Add your token in the header:
X-Geoai-Token: YOUR_TOKEN

The server applies a soft rate limit (60 req / 10 min / IP). If exceeded, it returns 429.

b) Signed links for certain endpoints #

Some endpoints (e.g., snapshots/chunks) allow access if:

1. a WP admin is logged in, or
2. the “public snapshots” option is enabled, or
3. a valid signature is provided via the sig query param (or X-GeoAI-Signature header).

Recommendation: generate signed URLs inside WordPress (admin/tools) and share them with external consumers. (The signature mechanism is handled by the plugin; on the integration side, you only need to supply the sig value provided by the admin.)

c) CORS #

Add your domain (e.g., https://app.yourdomain.com) to the plugin’s CORS allowlist to permit browser-based requests (Webflow/Ghost front ends, etc.). The API will then return Access-Control-Allow-Origin and allow Content-Type, X-Geoai-Token.

3) Main Endpoints #

Paths below are relative to /wp-json/.

A. geomatic/v1 namespace (token-protected) #

• GET /geomatic/v1/status → status: plugin version, WordPress version, site info, Pro/Lite edition. Auth required.
• GET /geomatic/v1/sitemap → AI Sitemap (XML): basic (Lite) or advanced (Pro). Auth required. Response Content-Type: application/xml.
• GET /geomatic/v1/posts?limit=50 → content list (id, url, score, flags has_schema / has_summary, modified date). Auth required.
• POST /geomatic/v1/optimize/{id} → auto-optimizes a content item (invisible summary if Pro is enabled, recalculates score). Auth required.
• GET /geomatic/v1/bots?limit=100 → recent AI bot visits (name, URL, date). Auth required.
• GET /geomatic/v1/schema → headless JSON-LD: returns decoded JSON ready to inject on the client. Auth required.
• GET /geomatic/v1/image-data/{id} → image AI data (optimized/structured). Public by default (can be restricted in your environment).
• GET /geomatic/v1/ai-data/{id} → AI data extracted from a post (entities/chunks/… if available). Public by default.

B. geomatic-ai/v1 namespace (open) #

• GET /geomatic-ai/v1/score/{id} → AI score for a post.
• GET /geomatic-ai/v1/recommendations/{id} → suggestions to improve the page.

C. geoai/v1 namespace (integration/reporting specific) #

• POST /geoai/v1/perf/hit (param p) → lightweight perf/visit signal (rate-limited). Public.
• GET /geoai/v1/insights → insights snapshot (admin required).
• GET /geoai/v1/snapshot/{id} & GET /geoai/v1/chunks/{id} → Snapshot/Chunks export (ETag + signature or admin, or public option).

Common errors:
401 Unauthorized (missing/incorrect token), 429 (rate limit), 403 (missing/invalid signature on signed endpoints), 404 (content not found).

4) Call Examples #

cURL (status + token) #

curl -X GET "https://your-site.com/wp-json/geomatic/v1/status" \
  -H "X-Geoai-Token: YOUR_TOKEN"

JavaScript (Webflow/Shopify theme front end) #

Make sure to add your domain to the CORS allowlist in GEOmatic AI.

fetch('https://your-site.com/wp-json/geomatic/v1/posts?limit=20', {
  headers: { 'X-Geoai-Token': 'YOUR_TOKEN' },
  credentials: 'omit'
}).then(r => r.json()).then(console.log);

Next.js (server route — recommended to avoid exposing the token) #

// app/api/geomatic/posts/route.js
export async function GET() {
  const r = await fetch('https://your-site.com/wp-json/geomatic/v1/posts?limit=50', {
    headers: { 'X-Geoai-Token': process.env.GEOAI_TOKEN }
  });
  return new Response(await r.text(), { status: r.status });
}

Python (requests) #

import requests
r = requests.get(
  "https://your-site.com/wp-json/geomatic/v1/schema",
  headers={"X-Geoai-Token": "YOUR_TOKEN"}
)
print(r.json())

Ruby (Faraday) #

require 'faraday'
conn = Faraday.new('https://your-site.com')
res = conn.get('/wp-json/geomatic/v1/bots', nil, {'X-Geoai-Token'=>'YOUR_TOKEN'})
puts res.status, res.body

Shopify (App Proxy / your app server) #

On your app server (Node/Express), call the WordPress API with the token, then return the response to your theme via the App Proxy. This avoids exposing the token in the theme and bypasses storefront CORS. (In the plugin, you can still allowlist the domain if you prefer direct calls.)

Ghost / Webflow (front end) #

Use the JavaScript example above and add your domain to the GEOmatic AI CORS allowlist. For Ghost server-side (helpers/custom route), prefer a server-to-server call with the token.

“Snapshot/Chunks” endpoints (signed links) #

Usage:
GET /wp-json/geoai/v1/snapshot/{id}?sig=SIGNATURE

Obtain a signed URL from the admin (or a small internal tool); otherwise, enable public mode if appropriate. ETag and HTTP caching are handled to reduce transfers.

5) Integration Best Practices #

• Do not expose the token on the client side. Whenever possible, make calls server-to-server (Next.js API routes, Shopify app, Cloud Functions, etc.).
• If you must call from a browser (Webflow/landing), allowlist your domain and respect the rate limit.
• For rich exports (snapshots/chunks), use signed links or restrict to admins as needed.
• If you get 404, check the content ID; for 401, check the X-Geoai-Token header; for 429, slow down your calls.

6) Quick Reference (Cheat Sheet) #

7) Go-Live Checklist #

Test GET /geomatic/v1/status (expect 200), then consume the needed endpoints.

Set your API token (store it server-side in your integration).

Add your domain to the CORS allowlist if calling from a browser.

(Optional) Enable/configure signed exports for snapshots/chunks.