# GeoCites

> GeoCites is a micro-SaaS for GEO citation analysis: "See if AI knows you exist."

GeoCites helps brands, local businesses, agencies, and agents measure whether large language models mention, cite, or recommend a domain for a given topic and location.

Canonical site: https://geo-cites.com
API docs: https://geo-cites.com/api-docs
Contact: contact@geo-cites.com
Builder: https://djinnfoundry.com

## What GeoCites Does

GeoCites runs controlled prompts across multiple LLMs, checks whether a target domain is cited or recommended, scores visibility, and compares the target against competitors that models mention instead.

Core outputs include:

- Overall AI citation visibility score.
- Per-model citation status and prominence.
- Recommendation context for the target domain.
- Competitor mentions and rankings.
- Geographic radius analysis for local intent.
- AI accessibility audit signals such as robots.txt, noai hints, paywalls, and llms.txt quality.

## How It Works

1. A caller provides a domain, keyword or topic, and optionally a location.
2. GeoCites builds recommendation-style prompts for the selected LLM models.
3. The system queries models through OpenRouter.
4. Responses are parsed for domain mentions, citations, recommendation prominence, and competing entities.
5. Scores are normalized into a result that can be read by humans, dashboards, or agents.

Production persistence uses Cloudflare Workers KV. Local development uses better-sqlite3 when available and can fall back to in-memory storage for tests.

## Why This Is Different From Generic SEO Or GEO Audits

Traditional SEO tools infer visibility from search rankings, crawl data, backlinks, and keyword volume. Generic GEO audits often check whether content is "AI friendly" in the abstract.

GeoCites measures the actual outcome: whether AI systems mention you when asked for recommendations. It is closer to a citation visibility test than a checklist audit.

GeoCites is useful when the product question is:

- Do AI models know this business exists?
- Which models cite it and which ignore it?
- Which competitors do models recommend instead?
- Does visibility change by city, region, or search intent?
- Can an agent programmatically buy and retrieve scans?

## Main Human API Endpoints

Base URL: https://geo-cites.com

- GET /api/v1/models
  Lists BYOK model aliases with OpenRouter model IDs and estimated costs. No authentication required.

- POST /api/v1/scan
  Runs a synchronous AI citation scan for a domain and keyword. Requires a GeoCites API key and caller-provided OpenRouter key.

- GET /api/v1/scan/:id
  Retrieves a previously completed scan by ID.

- POST /api/v1/audit
  Audits a URL for AI citability and crawler accessibility signals.

- POST /api/v1/queries
  Generates or evaluates query sets used for citation scans.

## Agent-Paid A2A Endpoints

GeoCites also exposes an agent-paid surface under /api/a2a using x402 payment flows.

Discovery:

- GET /api/a2a/manifest
- GET /api/a2a/llms.txt
- GET /.well-known/a2a.json
- GET /.well-known/llms.txt

Operations:

- POST /api/a2a/scan
  Paid AI citation scan.

- POST /api/a2a/watch
  Paid streaming scan over Server-Sent Events. Emits progress events and terminal payment status.

- POST /api/a2a/radius
  Paid geographic citation radius analysis.

- POST /api/a2a/audit
  Paid AI citability audit for an HTML page.

- POST /api/a2a/full
  Paid combined scan, radius, and audit bundle.

- GET /api/a2a/scan/:id
  Retrieves a previously purchased scan.

- POST /api/a2a/my-receipts
  Lets an agent retrieve its own purchase history by proving wallet ownership with a verify-only payment authorization.

## BYOK And Free Models Demo

GeoCites API scans are BYOK-only. The caller sends an OpenRouter key in the request body as openRouterApiKey, selects model aliases, and OpenRouter bills the caller directly.

The web UI may offer a constrained free-model demo using the shared community pool. That demo is intentionally limited so public traffic cannot drain shared API capacity.

Common BYOK model aliases include:

- openai-latest
- anthropic-opus-latest
- google-gemini-pro-latest
- perplexity-latest
- xai-latest
- zai-latest

Use GET /api/v1/models for the current model alias list.

## Key Privacy

GeoCites uses caller-provided OpenRouter keys only to run the requested BYOK scan. Keys are not saved in scan results.

Do not expose GeoCites API keys or OpenRouter keys in client-side code. Send them from a server, backend job, or trusted agent runtime.

## Recommended Links For Agents

- Product homepage: https://geo-cites.com
- API documentation: https://geo-cites.com/api-docs
- Model aliases: https://geo-cites.com/api/v1/models
- Agent manifest: https://geo-cites.com/api/a2a/manifest
- Agent llms.txt: https://geo-cites.com/api/a2a/llms.txt
- Contact: mailto:contact@geo-cites.com