AI Search Visibility API

import { WebScore } from 'webscore-sdk'

const client = new WebScore('waa_your_key')
const result = await client.geo('https://your-site.com')

console.log(result.geo.mentionRate)    // 0.67 → 67% of answers mention you
console.log(result.geo.citationRate)   // 0.33 → 33% include a link back
console.log(result.geo.sentiment)      // "positive" | "neutral" | "negative"
console.log(result.missedQuestions)    // questions where you weren't mentioned

import { useState } from 'react'

function useGeoScan() {
  const [data, setData]       = useState(null)
  const [loading, setLoading] = useState(false)
  const [error, setError]     = useState(null)

  const run = async (url) => {
    setLoading(true); setError(null)
    try {
      const res = await fetch('/api/audit?action=api-scan', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${process.env.NEXT_PUBLIC_WAA_KEY}`,
        },
        body: JSON.stringify({ url }),
      })
      const json = await res.json()
      if (!res.ok) throw new Error(json.error)
      setData(json)
    } catch (e) { setError(e.message) }
    finally { setLoading(false) }
  }

  return { data, loading, error, run }
}

// Usage in a component
export default function GeoCard() {
  const { data, loading, error, run } = useGeoScan()

  return (
    <div>
      <button onClick={() => run('https://your-site.com')} disabled={loading}>
        {loading ? 'Scanning…' : 'Run GEO Scan'}
      </button>
      {data && <p>Mention rate: {Math.round(data.geo.mentionRate * 100)}%</p>}
      {error && <p style={{ color: 'red' }}>{error}</p>}
    </div>
  )
}

curl -X POST https://www.webscore.dev/api/audit?action=api-scan \
  -H "Authorization: Bearer waa_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-site.com"}'

const { winner, site1, site2 } = await client.compare(
  'https://your-site.com',
  'https://competitor.com'
)

console.log(winner)               // "site1" | "site2" | "tie"
console.log(site1.mentionRate)    // 0.72
console.log(site2.mentionRate)    // 0.45

function useCompare() {
  const [result, setResult] = useState(null)
  const [loading, setLoading] = useState(false)

  const run = async (url1, url2) => {
    setLoading(true)
    const res = await fetch('/api/audit?action=api-geo-compare', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${process.env.NEXT_PUBLIC_WAA_KEY}`,
      },
      body: JSON.stringify({ url1, url2 }),
    })
    setResult(await res.json())
    setLoading(false)
  }

  return { result, loading, run }
}

// Usage
const { result, loading, run } = useCompare()
run('https://your-site.com', 'https://competitor.com')
// result.winner → "site1"

curl -X POST https://www.webscore.dev/api/audit?action=api-geo-compare \
  -H "Authorization: Bearer waa_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url1":"https://your-site.com","url2":"https://competitor.com"}'

// Step 1: run GEO scan
const geo = await client.geo('https://your-site.com')

// Step 2: get recommendations (passes missedQuestions — no extra GEO unit used)
const { recommendations } = await client.recommend('https://your-site.com', {
  brand:           geo.brand,
  mentionRate:     geo.geo.mentionRate,
  missedQuestions: geo.missedQuestions,
})

recommendations.forEach(r => {
  console.log(`[${r.impact}] ${r.title}`)
  console.log(`Page: ${r.page}`)
  console.log(r.description)
})

function useGeoRecommend() {
  const [recs, setRecs]       = useState([])
  const [loading, setLoading] = useState(false)

  const run = async (url, { brand, mentionRate, missedQuestions }) => {
    setLoading(true)
    const res = await fetch('/api/audit?action=api-geo-recommend', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${process.env.NEXT_PUBLIC_WAA_KEY}`,
      },
      body: JSON.stringify({ url, brand, mentionRate, missedQuestions }),
    })
    const data = await res.json()
    setRecs(data.recommendations ?? [])
    setLoading(false)
  }

  return { recs, loading, run }
}

curl -X POST https://www.webscore.dev/api/audit?action=api-geo-recommend \
  -H "Authorization: Bearer waa_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-site.com",
    "brand": "Your Brand",
    "mentionRate": 0.33,
    "missedQuestions": ["What are the best tools for X?"]
  }'

const { score, summary, issues } = await client.aeo('https://your-site.com')

console.log(score)          // 0–100
console.log(summary)        // AI-generated diagnosis
issues.forEach(i => console.log(`[${i.severity}] ${i.title}: ${i.fix}`))

function useAeoAudit() {
  const [result, setResult]     = useState(null)
  const [progress, setProgress] = useState('')
  const [loading, setLoading]   = useState(false)

  const run = async (url) => {
    setLoading(true); setResult(null)
    const res = await fetch('/api/aeo', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${process.env.NEXT_PUBLIC_WAA_KEY}`,
      },
      body: JSON.stringify({ url }),
    })
    const text  = await res.text()
    const lines = text.split('\n').filter(l => l.startsWith('data:'))
    for (const line of lines) {
      try {
        const d = JSON.parse(line.slice(5))
        if (d.type === 'progress') setProgress(d.message)
        if (d.type === 'result')   setResult(d.data)
      } catch {}
    }
    setLoading(false)
  }

  return { result, progress, loading, run }
}

// Usage
const { result, progress, loading, run } = useAeoAudit()
// result.score → 74, result.issues → [...]

curl -X POST https://www.webscore.dev/api/aeo \
  -H "Authorization: Bearer waa_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-site.com"}'

# Response streams as Server-Sent Events:
# data: {"type":"progress","message":"Fetching page…"}
# data: {"type":"result","data":{"score":74,"issues":[…]}}