v1 API

GeoCites API

Check AI citation visibility programmatically. Build monitoring, reports, and integrations for SEO teams and AI agents.

Quick Start

Run a free scan with a single request. No payment required for open-source models.

bash

curl -X POST https://geocites.dev/api/v1/scan \
  -H "Authorization: Bearer gc_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"domain":"progevita.com","keyword":"longevity clinic","location":"Valencia, Spain"}'

Response includes overall score, per-model citation data, geographic radius analysis, and competitor rankings.

Authentication

All API requests require a valid API key sent via the Authorization header.

http

Authorization: Bearer gc_sk_your_key

API keys use the prefix gc_sk_. Keep your key secret -- do not expose it in client-side code.

API keys will be self-service from the dashboard soon. For now, contact us to get a key.

Endpoints

POST/api/v1/scan

Run a new AI citation scan. Returns full results synchronously (v1 -- async polling coming in v2).

Request Body

json

{
  "domain": "progevita.com",
  "keyword": "longevity clinic",
  "location": "Valencia, Spain",
  "models": ["gpt-5.4", "claude-opus", "gemini-pro"],
  "keywordsPerRing": 10,
  "queriesPerKeyword": 1
}

Response 200

json

{
  "scanId": "a1b2c3d4-...",
  "status": "complete",
  "cost": "$0.85",
  "result": {
    "domain": "progevita.com",
    "keyword": "longevity clinic",
    "overallScore": 42,
    "models": [
      {
        "model": "gpt-5.4",
        "modelLabel": "GPT-5.4",
        "cited": true,
        "score": 72,
        "prominence": "secondary"
      }
    ],
    "radius": {
      "rings": [...],
      "topCompetitors": [...]
    }
  }
}

GET/api/v1/scan/:id

Retrieve a previously completed scan by ID.

Response 200

json

{
  "scanId": "a1b2c3d4-...",
  "status": "complete",
  "result": { ... }
}

GET/api/v1/models

List available AI models with their costs. No authentication required.

Response 200

json

{
  "free": [
    { "id": "llama", "name": "Llama 3.3 70B", "costPerQuery": 0 },
    { "id": "hermes", "name": "Hermes 3 405B", "costPerQuery": 0 },
    { "id": "gemma", "name": "Gemma 3 27B", "costPerQuery": 0 }
  ],
  "pro": [
    { "id": "gpt-5.4", "name": "GPT-5.4", "costPerQuery": 0.008 },
    { "id": "claude", "name": "Claude Sonnet 4", "costPerQuery": 0.012 },
    { "id": "gemini", "name": "Gemini 2.5 Pro", "costPerQuery": 0.007 }
  ]
}

Scan Parameters

Parameter	Type	Required	Description
`domain`	string	Yes	Website domain to check (e.g. progevita.com)
`keyword`	string	Yes	Target keyword or topic
`location`	string	No	Location for geographic radius (e.g. Valencia, Spain)
`models`	string[]	No	Pro models to use. Defaults to free models if omitted
`keywordsPerRing`	number	No	Keywords per geographic ring (3-15, default: 3 free / 10 pro)
`queriesPerKeyword`	number	No	Queries per keyword (1-3, default: 1)

Available Models

Free Models (open-source)

Llama 3.3 70Bllama

Hermes 3 405Bhermes

Gemma 3 27Bgemma

Mistral Small 24Bmistral

Nemotron 120Bnemotron

Pro Models (paid)

GPT-5.4

$0.015/qgpt-5.4

GPT-5.4

$0.015/qgpt-5

Claude Sonnet 4

$0.012/qclaude

Claude Opus 4.6

$0.020/qclaude-opus

Gemini 2.5 Pro

$0.007/qgemini

Perplexity Pro

$0.012/qperplexity

Grok 3

$0.012/qgrok

Code Examples

bash

curl -X POST https://geocites.dev/api/v1/scan \
  -H "Authorization: Bearer gc_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "progevita.com",
    "keyword": "longevity clinic",
    "location": "Valencia, Spain"
  }'

Rate Limits

Free scans

10 / hour

Per API key

Pro scans

60 / hour

Per API key

Burst

5 concurrent

Max parallel requests

Rate limit headers (X-RateLimit-Remaining, X-RateLimit-Reset) are included in responses. Exceeding limits returns 429 Too Many Requests.

Pricing

Plan	Price	Includes
Free scans	$0	5 open-source models, basic radius, 3 keywords/ring
Pro scan	From $0.45	Choose models, up to 15 keywords/ring, full geographic radius
100 credit pack	$15 (15% off)	1 credit = 1 standard pro scan (3 models, 10 kw/ring)
Enterprise	Custom	Volume pricing, dedicated support, SLA

Credit packs and payment integration coming soon. Free scans are available now.

Error Codes

Status	Meaning
`200`	Success
`400`	Bad request -- missing or invalid parameters
`401`	Unauthorized -- invalid or missing API key
`404`	Not found -- scan ID does not exist
`429`	Rate limited -- too many requests
`500`	Server error -- something went wrong

Questions? Need an API key?

Try GeoCites Free