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.snu.ac.kr" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "url": "https://www.snu.ac.kr",
  "schema_types": [
    "CollegeOrUniversity",
    "FAQPage",
    "Course"
  ],
  "meta_tags": {
    "title": "서울대학교",
    "description": "서울대학교 공식 웹사이트"
  },
  "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

Name	Type	Required	Description
url	string	Required	분석 대상 웹사이트 URL (예: https://www.snu.ac.kr)

Request

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

Response

{
  "url": "https://www.snu.ac.kr",
  "schema_types": [
    "CollegeOrUniversity",
    "FAQPage",
    "Course"
  ],
  "meta_tags": {
    "title": "서울대학교",
    "description": "서울대학교 공식 웹사이트"
  },
  "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

Name	Type	Required	Description
url	string	Required	대상 웹사이트 URL
format	string	Optional	응답 포맷: json (기본값) 또는 html

Request

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

Response

{
  "format": "html",
  "html": "<meta name=\"description\" content=\"서울대학교 공식 웹사이트 - 1946년 설립, 대한민국 최고 연구중심대학\">\n<script type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"CollegeOrUniversity\",\"name\":\"서울대학교\"}</script>",
  "meta_count": 8,
  "jsonld_count": 3
}

GET/v1/body

BasicPremium

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

Parameters

Name	Type	Required	Description
url	string	Required	대상 웹사이트 URL

Request

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

Response

{
  "faq_html": "<div itemscope itemtype=\"https://schema.org/FAQPage\">...</div>",
  "citable_blocks": [
    {
      "id": "cb-001",
      "claim": "서울대학교는 1946년에 설립된 대한민국 최초의 국립종합대학교입니다.",
      "source": "https://www.snu.ac.kr/about/history",
      "confidence": 0.95
    }
  ],
  "structured_content_count": 12
}

GET/v1/schema/{type}

FreeBasicPremium

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

Parameters

Name	Type	Required	Description
type	string	Required	Schema.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": "CollegeOrUniversity",
  "name": "서울대학교",
  "alternateName": "Seoul National University",
  "url": "https://www.snu.ac.kr",
  "foundingDate": "1946-10-15",
  "address": {
    "@type": "PostalAddress",
    "streetAddress": "관악로 1",
    "addressLocality": "관악구",
    "addressRegion": "서울특별시",
    "postalCode": "08826",
    "addressCountry": "KR"
  },
  "numberOfStudents": 28000,
  "campusSize": "4109000 m²"
}

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": "서울대학교 입학 전형은 어떤 종류가 있나요?",
      "answer": "서울대학교는 수시모집(일반전형, 기회균형선발, 지역균형선발)과 정시모집을 통해 신입생을 선발합니다. 2026학년도 기준 수시 약 1,739명, 정시 약 1,109명을 모집합니다.",
      "category": "입학",
      "source_url": "https://admission.snu.ac.kr"
    },
    {
      "question": "서울대학교 등록금은 얼마인가요?",
      "answer": "2026학년도 기준 인문사회계열 학기당 약 2,838,000원, 자연과학계열 약 3,210,000원, 공과대학 약 3,440,000원입니다.",
      "category": "학비",
      "source_url": "https://www.snu.ac.kr/tuition"
    }
  ]
}

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": "서울대학교는 1946년 10월 15일에 설립된 대한민국 최초의 국립종합대학교이다.",
      "evidence": "국가기록원 공식 기록 및 서울대학교 연혁 페이지",
      "source_url": "https://www.snu.ac.kr/about/history",
      "category": "기관정보",
      "confidence": 0.97,
      "last_verified": "2026-04-01T00:00:00Z"
    },
    {
      "id": "cb-002",
      "claim": "서울대학교 관악캠퍼스 면적은 약 4,109,000m²로 대한민국 대학 중 최대 규모이다.",
      "evidence": "서울대학교 시설관리 공식 데이터",
      "source_url": "https://www.snu.ac.kr/about/campus",
      "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

# 서울대학교 (Seoul National University)

> 1946년 설립, 대한민국 최고 연구중심 국립종합대학교

## 기본 정보
- 설립연도: 1946년
- 소재지: 서울특별시 관악구 관악로 1
- 학생 수: 약 28,000명
- 캠퍼스: 관악(본), 연건(의대), 평창(농생대), 시흥

## 주요 링크
- [입학안내](https://admission.snu.ac.kr)
- [대학소개](https://www.snu.ac.kr/about)
- [연구성과](https://www.snu.ac.kr/research)

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

# 서울대학교 (Seoul National University) — 상세 정보

> 1946년 설립, 대한민국 최고 연구중심 국립종합대학교

## 기본 정보
- 설립연도: 1946년 10월 15일
- 유형: 국립종합대학교
- 총장: 유홍림
- 소재지: 서울특별시 관악구 관악로 1 (08826)
- 학생 수: 학부 16,000명 / 대학원 12,000명
- 교원 수: 전임교원 2,200명

## 단과대학 (16개)
- 인문대학, 사회과학대학, 자연과학대학, 간호대학 ...
- 공과대학, 농업생명과학대학, 미술대학, 사범대학 ...

## 입학 전형 (2026학년도)
- 수시: 일반전형, 기회균형, 지역균형 (총 1,739명)
- 정시: 일반전형 (총 1,109명)
- 편입학: 일반편입, 학사편입

## 등록금 (2026학년도, 학기당)
- 인문사회: 2,838,000원
- 자연과학: 3,210,000원
- 공과대학: 3,440,000원
- 의과대학: 3,760,000원

Tier Comparison

Endpoint	Free	Basic	Premium
/v1/status	10 req/day	500 req/day	Unlimited
/v1/geo-data	schema + meta only	Full	Full
/v1/head	json only	json + html	json + html
/v1/body	--	Full	Full
/v1/schema/{type}	CollegeOrUniversity	All types	All types
/v1/faq	--	Full	Full
/v1/citable-blocks	--	Top 10	All
/v1/llms-txt	Full	Full	Full
/v1/llms-full-txt	--	Full	Full

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

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

Error Response Format

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