AEO Scanner API Documentation — Free REST API

Base URL: https://aeo.codecity.com.tw

Authentication: None required — all endpoints are free and open.

Response Format: JSON (all endpoints return application/json)

Endpoints

POST /api/scan

Scan a website and calculate its AEO (Answer Engine Optimization) score across 8 metrics. Returns the overall score, individual metric scores, generated code snippets, and improvement suggestions.

Request Body

Parameter	Type	Required	Description
`url`	string	Yes	The full URL to scan (e.g. `https://example.com`)

Example Request

curl -X POST https://aeo.codecity.com.tw/api/scan \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

Example Response

{
  "score": 72,
  "metrics": {
    "meta": 85,
    "og": 60,
    "content": 80,
    "jsonLd": 70,
    "image": 65,
    "faq": 50,
    "contact": 90,
    "llmsTxt": 0,
    "social": 75
  },
  "snippets": {
    "jsonLd": "<script type=\"application/ld+json\">...</script>",
    "og": "<meta property=\"og:title\" ...>",
    "faq": "<script type=\"application/ld+json\">...</script>"
  },
  "suggestions": [
    "Add JSON-LD structured data",
    "Create an llms.txt file",
    "Add FAQ schema markup"
  ]
}

GET /api/sites

Retrieve a paginated list of all scanned sites with their AEO scores.

Parameter	Type	Default	Description
`page`	number	1	Page number
`limit`	number	20	Results per page (max 100)
`search`	string	—	Filter by keyword in URL or site name

Example Request

curl "https://aeo.codecity.com.tw/api/sites?page=1&limit=20&search=example"

Example Response

{
  "sites": [
    {
      "id": 1,
      "url": "https://example.com",
      "name": "Example Site",
      "score": 72,
      "scanned_at": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 150,
  "page": 1,
  "limit": 20
}

GET /api/stats

Get global statistics including total sites scanned, total scan count, and visitor count.

Example Request

curl "https://aeo.codecity.com.tw/api/stats"

Example Response

{
  "totalSites": 1250,
  "totalScans": 4800,
  "visitors": 32000
}

GET /api/crawlers/activity

Get recent AI crawler activity — shows which AI bots have visited and what pages they accessed.

Example Request

curl "https://aeo.codecity.com.tw/api/crawlers/activity"

Example Response

{
  "activity": [
    {
      "bot": "ChatGPT-User",
      "path": "/en/blog/what-is-aeo",
      "accessed_at": "2025-01-15T08:22:00Z",
      "ip": "***"
    }
  ]
}

GET /api/crawlers/public

Get public AI crawler statistics — bot names, total visit counts, and when they were last seen.

Example Request

curl "https://aeo.codecity.com.tw/api/crawlers/public"

Example Response

{
  "crawlers": [
    {
      "bot_name": "ChatGPT-User",
      "visits": 342,
      "last_seen": "2025-01-15T08:22:00Z"
    },
    {
      "bot_name": "ClaudeBot",
      "visits": 218,
      "last_seen": "2025-01-15T07:45:00Z"
    }
  ]
}

GET /api/meta

Get site metadata including total site count and last updated timestamp.

Example Request

curl "https://aeo.codecity.com.tw/api/meta"

Example Response

{
  "siteCount": 1250,
  "lastUpdated": "2025-01-15T10:30:00Z"
}