API Reference

GEO API Reference

AI 검색 최적화를 위한 구조화 데이터 API. Schema.org JSON-LD, 메타태그, FAQ, Citable Block, llms.txt 등 GEO(Generative Engine Optimization) 데이터를 프로그래밍 방식으로 조회하고 웹사이트에 통합할 수 있습니다.

Base URL: https://iwiggnwvvwpxcksqjryz.supabase.co/functions/v1/apiVersion: v1Format: JSON

Quick Start

API 키를 발급받은 후, 아래 명령어 하나로 바로 시작할 수 있습니다. 대시보드에서 API 키를 생성하고 YOUR_API_KEY 부분을 교체하세요.

curl -X GET "https://iwiggnwvvwpxcksqjryz.supabase.co/functions/v1/api/v1/geo-data?url=https://www.example.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "url": "https://www.example.com",
  "schema_types": [
    "Organization",
    "FAQPage",
    "Article"
  ],
  "meta_tags": {
    "title": "Example Institution",
    "description": "Example Institution 공식 웹사이트"
  },
  "faq_count": 24,
  "citable_blocks_count": 15,
  "llms_txt": true,
  "geo_score": 78
}

Authentication

모든 API 요청에는 인증이 필요합니다. 두 가지 방식 중 하나를 선택할 수 있습니다.

방법 1: Authorization Header (권장)

Authorization: Bearer YOUR_API_KEY

방법 2: X-API-Key Header

X-API-Key: YOUR_API_KEY

API 키 보안 유의사항

  • API 키를 클라이언트 사이드 코드(JavaScript, 프론트엔드)에 노출하지 마세요.
  • 서버 사이드에서만 API를 호출하거나, 환경 변수로 관리하세요.
  • 키가 유출된 경우 대시보드에서 즉시 재발급하세요.

Endpoints

GET/v1/status
FreeBasicPremium

API 키 상태 및 사용량을 조회합니다. 현재 티어, 일일 요청 횟수, 잔여 할당량을 확인할 수 있습니다.

Request

curl -X GET "https://iwiggnwvvwpxcksqjryz.supabase.co/functions/v1/api/v1/status" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "status": "active",
  "tier": "basic",
  "usage": {
    "today": 42,
    "limit": 500,
    "remaining": 458
  },
  "key_created_at": "2026-03-15T09:00:00Z",
  "key_expires_at": null
}
GET/v1/geo-data
FreeBasicPremium

지정 URL에 대한 전체 GEO 데이터를 반환합니다. Schema.org JSON-LD, 메타태그, FAQ, Citable Block, llms.txt 등 모든 GEO 최적화 데이터를 한 번에 조회합니다.

Parameters

NameTypeRequiredDescription
urlstringRequired분석 대상 웹사이트 URL (예: https://www.example.com)

Request

curl -X GET "https://iwiggnwvvwpxcksqjryz.supabase.co/functions/v1/api/v1/geo-data?url=https://www.example.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "url": "https://www.example.com",
  "schema_types": [
    "Organization",
    "FAQPage",
    "Article"
  ],
  "meta_tags": {
    "title": "Example Institution",
    "description": "Example Institution 공식 웹사이트"
  },
  "faq_count": 24,
  "citable_blocks_count": 15,
  "llms_txt": true,
  "geo_score": 78,
  "tier_limit": "Basic 이상: 전체 데이터 / Free: schema + meta만"
}
GET/v1/head
FreeBasicPremium

HTML <head>에 삽입할 메타태그와 JSON-LD 스크립트를 반환합니다. json 포맷은 구조화된 객체를, html 포맷은 바로 삽입 가능한 HTML 문자열을 제공합니다.

Parameters

NameTypeRequiredDescription
urlstringRequired대상 웹사이트 URL
formatstringOptional응답 포맷: json (기본값) 또는 html

Request

curl -X GET "https://iwiggnwvvwpxcksqjryz.supabase.co/functions/v1/api/v1/head?url=https://www.example.com&format=html" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "format": "html",
  "html": "<meta name=\"description\" content=\"Example Institution 공식 웹사이트\">\n<script type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"Organization\",\"name\":\"Example Institution\"}</script>",
  "meta_count": 8,
  "jsonld_count": 3
}
GET/v1/body
BasicPremium

본문 영역에 삽입할 구조화 콘텐츠를 반환합니다. FAQ 아코디언, Citable Block, 구조화 데이터 마크업 등이 포함됩니다.

Parameters

NameTypeRequiredDescription
urlstringRequired대상 웹사이트 URL

Request

curl -X GET "https://iwiggnwvvwpxcksqjryz.supabase.co/functions/v1/api/v1/body?url=https://www.example.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "faq_html": "<div itemscope itemtype=\"https://schema.org/FAQPage\">...</div>",
  "citable_blocks": [
    {
      "id": "cb-001",
      "claim": "Example Institution은 공식 웹사이트에서 핵심 서비스와 지원 정보를 제공합니다.",
      "source": "https://www.example.com/about",
      "confidence": 0.95
    }
  ],
  "structured_content_count": 12
}
GET/v1/schema/{type}
FreeBasicPremium

특정 Schema.org 유형의 JSON-LD를 반환합니다. Free 티어는 CollegeOrUniversity 유형만 조회 가능하며, Basic 이상은 모든 유형을 사용할 수 있습니다.

Parameters

NameTypeRequiredDescription
typestringRequiredSchema.org 유형: CollegeOrUniversity, FAQPage, Course, Event, BreadcrumbList, Organization

Request

curl -X GET "https://iwiggnwvvwpxcksqjryz.supabase.co/functions/v1/api/v1/schema/CollegeOrUniversity" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "Example Institution",
  "alternateName": "Example Org",
  "url": "https://www.example.com",
  "foundingDate": "2000-01-01",
  "address": {
    "@type": "PostalAddress",
    "streetAddress": "Example Road 1",
    "addressLocality": "Example City",
    "addressRegion": "Example Region",
    "postalCode": "00000",
    "addressCountry": "KR"
  },
  "sameAs": [
    "https://www.example.com/about",
    "https://www.example.com/contact"
  ]
}
GET/v1/faq
BasicPremium

AI 검색 최적화된 FAQ 목록을 반환합니다. 각 FAQ는 Schema.org FAQPage 규격에 맞게 구조화되어 있으며, AI 엔진이 직접 인용할 수 있는 형태입니다.

Request

curl -X GET "https://iwiggnwvvwpxcksqjryz.supabase.co/functions/v1/api/v1/faq" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "total": 24,
  "items": [
    {
      "question": "Example Institution의 주요 서비스는 무엇인가요?",
      "answer": "Example Institution은 공식 웹사이트에서 주요 서비스, 신청 방법, 문의 채널을 구조화된 정보로 제공합니다.",
      "category": "서비스",
      "source_url": "https://www.example.com/services"
    },
    {
      "question": "상담이나 신청은 어디에서 진행하나요?",
      "answer": "상담과 신청은 공식 문의 페이지 또는 전용 신청 페이지에서 진행할 수 있습니다.",
      "category": "문의",
      "source_url": "https://admissions.example.com/apply"
    }
  ]
}
GET/v1/citable-blocks
BasicPremium

AI 검색 엔진이 직접 인용할 수 있는 팩트 블록 목록을 반환합니다. 각 블록은 출처, 신뢰도 점수, 카테고리가 포함되어 있습니다. Basic 티어는 상위 10개, Premium은 전체를 반환합니다.

Request

curl -X GET "https://iwiggnwvvwpxcksqjryz.supabase.co/functions/v1/api/v1/citable-blocks" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "total": 28,
  "returned": 10,
  "tier_note": "Basic: 상위 10개 / Premium: 전체",
  "blocks": [
    {
      "id": "cb-001",
      "claim": "Example Institution은 공식 웹사이트에서 기관 소개와 서비스 정보를 제공합니다.",
      "evidence": "Example Institution 공식 소개 페이지",
      "source_url": "https://www.example.com/about",
      "category": "기관정보",
      "confidence": 0.97,
      "last_verified": "2026-04-01T00:00:00Z"
    },
    {
      "id": "cb-002",
      "claim": "Example Institution은 공식 문의 페이지를 통해 상담 채널을 안내합니다.",
      "evidence": "Example Institution 공식 문의 페이지",
      "source_url": "https://www.example.com/contact",
      "category": "문의",
      "confidence": 0.94,
      "last_verified": "2026-04-01T00:00:00Z"
    }
  ]
}
GET/v1/llms-txt
FreeBasicPremium

AI 크롤러(GPTBot, Google-Extended 등)를 위한 llms.txt 요약 파일을 반환합니다. 기관의 핵심 정보를 AI가 소화하기 쉬운 구조화 텍스트로 제공합니다.

Request

curl -X GET "https://iwiggnwvvwpxcksqjryz.supabase.co/functions/v1/api/v1/llms-txt" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

# Example Institution

> 공식 웹사이트의 핵심 정보를 AI 크롤러가 이해하기 쉽게 정리한 예시입니다.

## 기본 정보
- 유형: 예시 기관
- 공식 웹사이트: https://www.example.com
- 문의 채널: https://www.example.com/contact
- 주요 서비스: 상담, 신청, 고객 지원

## 주요 링크
- [서비스 안내](https://www.example.com/services)
- [기관 소개](https://www.example.com/about)
- [문의](https://www.example.com/contact)
GET/v1/llms-full-txt
BasicPremium

AI 크롤러를 위한 상세 버전 llms-full.txt를 반환합니다. llms.txt의 확장 버전으로, 학과 목록, 연구 분야, 입학 요건, 시설 정보 등 상세 데이터를 포함합니다.

Request

curl -X GET "https://iwiggnwvvwpxcksqjryz.supabase.co/functions/v1/api/v1/llms-full-txt" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

# Example Institution — 상세 정보

> 공식 웹사이트의 상세 정보를 AI 크롤러가 이해하기 쉽게 정리한 예시입니다.

## 기본 정보
- 유형: 예시 기관
- 공식 웹사이트: https://www.example.com
- 대표 문의: https://www.example.com/contact
- 운영 지역: Example Region

## 주요 서비스
- 서비스 소개
- 신청 안내
- 고객 지원
- 자료실

## 신청 안내
- 온라인 신청: https://admissions.example.com/apply
- 상담 예약: https://www.example.com/contact
- FAQ: https://www.example.com/faq

## 운영 증거
- 게시 상태: published
- 마지막 검증일: 2026-04-01
- 관리 범위: head.html, body.html, FAQ, Citable Block

Tier Comparison

EndpointFreeBasicPremium
/v1/status10 req/day500 req/dayUnlimited
/v1/geo-dataschema + meta onlyFullFull
/v1/headjson onlyjson + htmljson + html
/v1/body--FullFull
/v1/schema/{type}CollegeOrUniversityAll typesAll types
/v1/faq--FullFull
/v1/citable-blocks--Top 10All
/v1/llms-txtFullFullFull
/v1/llms-full-txt--FullFull
FreeFree
  • 10 requests / day
  • Schema: CollegeOrUniversity only
  • Head: JSON format only
  • llms.txt access
BasicBasic
  • 500 requests / day
  • All schema types
  • FAQ + Body + llms-full-txt
  • Citable Blocks: Top 10
PremiumPremium
  • Unlimited requests
  • All endpoints, full access
  • All Citable Blocks
  • Priority support

Error Codes

CodeStatusDescription
200OK요청 성공. 응답 본문에 데이터가 포함됩니다.
400Bad Request필수 파라미터가 누락되었거나 잘못된 값이 전달되었습니다.
401UnauthorizedAPI 키가 누락되었거나 유효하지 않습니다. Authorization 헤더를 확인하세요.
403Forbidden현재 티어에서 접근할 수 없는 엔드포인트입니다. 상위 티어로 업그레이드하세요.
404Not Found요청한 리소스를 찾을 수 없습니다. URL 또는 엔드포인트 경로를 확인하세요.
429Too Many Requests일일 요청 한도를 초과했습니다. 자정(KST) 이후 재시도하거나 상위 티어로 업그레이드하세요.
500Internal Server Error서버 내부 오류가 발생했습니다. 지속되면 support@100gom.com으로 문의하세요.

Error Response Format

{
  "error": {
    "code": 401,
    "status": "Unauthorized",
    "message": "Invalid or missing API key. Please check your Authorization header."
  }
}