문서 / API 레퍼런스

API 레퍼런스

SEOLens REST API의 완전한 레퍼런스.

기본 URL

https://seo-lens.site/api/v1

인증

모든 API 요청에는 API 키가 필요합니다. 대시보드에 로그인하여 무료 API 키를 생성하세요. Authorization 헤더 또는 x-api-key 헤더를 통해 요청에 포함하세요.

Authorization: Bearer YOUR_API_KEY

# or

x-api-key: YOUR_API_KEY

POST

/research

하나 또는 여러 키워드를 리서치하고 검색량, 난이도, CPC 데이터, 관련 키워드 추천을 가져옵니다.

요청 본문

파라미터	타입	필수	설명
keyword	string	Yes*	리서치할 단일 키워드
keywords	string[]	Yes*	키워드 배열 (최대 50개). 다음 대신 사용: `keyword`
countryCode	string	No	국가 코드 (기본값: "US"). 옵션: US, JP, GB, DE, FR, CA, AU, BR, IN, KR, MX, ES, IT, NL, SE, TW, TH, VN, ID, PH
languageCode	string	No	언어 코드 (기본값: "en"). 옵션: en, ja, de, fr, es, pt, it, nl, ko, zh, th, vi, id, sv

* 다음 중 하나를 지정: keyword 또는 keywords (둘 다는 불가).

응답 형식 (단일 키워드)

200 OK

{
  "keyword": "react hooks",
  "metrics": {
    "avgMonthlySearches": 18100,
    "competition": "LOW",
    "cpcLow": 0.15,
    "cpcHigh": 1.85
  },
  "difficulty": "easy",
  "suggestions": [
    {
      "keyword": "react custom hooks",
      "avgMonthlySearches": 6600,
      "competition": "LOW",
      "cpcLow": 0.10,
      "cpcHigh": 0.95
    }
  ]
}

응답 형식 (배치)

200 OK

{
  "results": [
    {
      "keyword": "react hooks",
      "metrics": { ... },
      "difficulty": "easy",
      "suggestions": [ ... ]
    },
    {
      "keyword": "vue composables",
      "metrics": { ... },
      "difficulty": "medium",
      "suggestions": [ ... ]
    }
  ]
}

코드 예시

JavaScript / TypeScript

fetch

const response = await fetch("https://seo-lens.site/api/v1/research", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY",
  },
  body: JSON.stringify({
    keywords: ["nextjs seo"],
    countryCode: "US",
    languageCode: "en",
  }),
});

const data = await response.json();
console.log(data.results);

Python

requests

import requests

response = requests.post(
    "https://seo-lens.site/api/v1/research",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "keywords": ["nextjs seo"],
        "countryCode": "US",
        "languageCode": "en",
    },
)

data = response.json()
print(f"Results: {data['results']}")

cURL

bash

# Single keyword
curl -X POST https://seo-lens.site/api/v1/research \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"keywords": ["nextjs seo"], "countryCode": "US"}'

# Batch keywords
curl -X POST https://seo-lens.site/api/v1/research \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"keywords": ["react hooks", "vue composables"], "countryCode": "US"}'

오류 코드

상태	설명
200	성공 - 키워드 데이터 반환됨
401	인증 실패 - API 키 누락 또는 유효하지 않음
400	잘못된 요청 - 파라미터 누락 또는 유효하지 않음
429	요율 제한 초과 - 요청이 너무 많음
500	내부 서버 오류 - 잠시 후 다시 시도하세요

요율 제한

무료 플랜은 모든 사용자의 공정한 이용을 보장하기 위해 요율 제한이 적용됩니다.

IP 주소당 하루 100회 요청
배치 요청당 50개 키워드
캐시된 결과는 요율 제한에 포함되지 않음