Rankscale REST API
Rankscale은 AI 브랜드 가시성 추적 도구입니다. 사용자가 추적하는 검색어를 다양한 AI 모델(ChatGPT, Gemini, Claude, Perplexity 등)에 제시하고, 응답을 분석하여 추적된 브랜드가 얼마나 자주, 어디서, 얼마나 호의적으로 언급되는지 보고합니다.
이 스킬은 REST API를 직접 호출하여 사용자(개발자가 아닌 SEO 전문가)가 대시보드를 거치지 않고도 데이터를 보고서, 차트, 맞춤 분석에 활용할 수 있도록 합니다.
설정
- API 키: 환경 변수
RANKSCALE_API_KEY에서 읽습니다. 키 형식은rk_<hash>_<workspaceId>입니다. 접미사는 브랜드 ID가 아닌 워크스페이스 식별자이므로, 하나의 키로 해당 워크스페이스의 모든 브랜드에 접근할 수 있습니다(특이사항 §15). 설정되지 않은 경우, 사용자에게 한 번 설정하도록 요청하세요. PowerShell:setx RANKSCALE_API_KEY "rk_..."(적용을 위해 새 셸 필요) 또는 세션별로$env:RANKSCALE_API_KEY = "rk_..."로 전달합니다. 키를 응답에 출력하거나 파일에 절대 기록하지 마세요. - 기본 URL:
https://rankscale.ai(참고:/api접두사 없음 — 경로는 마케팅 도메인에 직접/v1/...형태입니다). - 인증 헤더:
Authorization: Bearer $RANKSCALE_API_KEY. - 속도 제한: API 키당 분당 200개 요청. 응답에는
X-RateLimit-Limit,X-RateLimit-Remaining,X-RateLimit-Reset(윈도우가 재설정될 때까지 초)이 포함됩니다. 일괄 작업 시curl -i로 읽으세요. 가능하면 보고 응답을 5-10분 동안 캐시하세요. - 사용 가능한 도구: 요청에는
curl. JSON 파싱에는 환경이 제공하는 도구(node -e "...",jq,python -m json.tool)를 사용하세요. PATH에 있는지 확인하고 하나에 의존하지 마세요. - 셸 구문: 아래 예제는 bash 스타일 변수 확장(
$RANKSCALE_API_KEY)을 사용합니다. Windows PowerShell에서는$env:RANKSCALE_API_KEY가 됩니다. 호출하는 셸 도구에 따라 선택하세요. 둘 다 작동하지만 구문에 유의하세요.
호출 패턴
모든 엔드포인트는 성공 시 {success: true, data: {...}}를, 실패 시 {success: false, error: {code, message, details}}를 반환합니다. .data를 읽기 전에 항상 .success를 확인하세요.
warnings도 확인하세요. 성공적인 응답에는 API가 인식하지 못하고 무시한 요청 필드를 나열하는 warnings[]라는 세 번째 최상위 키가 있을 수 있습니다. 종종 '혹시 이걸 찾으셨나요?' 힌트를 포함합니다("Ignored unrecognized field 'startDate'. Did you mean 'isoStartDate'? …"). 요청이 깨끗하면 없으므로 if (json.warnings)는 안정적인 가드입니다. 경고는 숫자가 요청한 것과 다른 질문에 대한 답변임을 의미합니다. API는 드롭된 필드에 기본값을 사용합니다. 경고를 숨기지 말고 사용자에게 표시하세요. 이것은 camelCase 함정(특이사항 §1)을 잡을 수 있는 가장 저렴한 방법입니다.
원시 JSON 응답은 사용자 작업 파일(일반적으로 Rankscale/<endpoint>_<context>.json) 옆에 저장하여 API를 다시 호출하지 않고도 재분석할 수 있도록 하세요. 사용자에게는 원시 JSON이 아닌 깔끔한 요약을 보여주세요. 사용자가 요청한 경우는 예외입니다.
토큰 효율성 — 가장 강력한 레버. 대량 작업(다중 토픽, 다중 엔진, 전체 기록 또는 includeAnswerTexts가 포함된 /search-terms-report)의 경우, 응답을 -o로 직접 디스크에 쓰고 node -e로 필요한 값만 추출하세요. 전체 /report 페이로드를 컨텍스트로 읽지 마세요. 필터링된 보고서 하나는 약 40-50KB이고 7개 토픽 스윕은 약 300KB입니다. 클라이언트 측에서 스칼라/시리즈를 추출하면 컨텍스트 사용량을 줄일 수 있으며, 대량 풀에서는 페이로드를 인라인으로 읽는 것보다 토큰 사용량을 약 절반으로 줄일 수 있습니다. (단일 좁은 메트릭의 경우 오버헤드가 가치가 없으므로 작은 응답을 그냥 읽으세요.)
페이로드 크기는 매우 불균일합니다. 이에 맞게 계획하세요. 단일 브랜드에서 측정:
| 엔드포인트 | 기간 | 크기 |
|---|---|---|
/report (필터링됨) | 30일 | ~40-50 KB |
/report (필터링됨) | 1개월 | ~105-110 KB |
/citations | 3개월 | ~3.9 MB |
/citations uncapped: true | 1개월 | ~4.4-5.7 MB |
/sentiment | 30일 | ~9 MB |
/sentiment | 3개월 | ~17 MB |
크기는 기간 길이에 비례하지 않습니다. uncapped: true가 훨씬 더 중요합니다. 한도가 없는 한 달이 제한된 3개월 풀보다 더 크게 반환되었으므로 3개월 행에서 1개월 크기를 추정하지 마세요.
/sentiment와 /citations는 인라인으로 읽기에 절대 안전하지 않습니다. 항상 파일로 -o하고 추출하세요. 이렇게 무거운 호출에서는 HTTP 상태도 캡처하세요(curl -w '%{http_code}'). 일시적인 502는 깨진 경로처럼 보이지만 재시도만 필요한 HTML 본문으로 도착합니다(특이사항 §6).
# Bash (Git Bash / WSL / macOS / Linux)
curl -s -H "Authorization: Bearer $RANKSCALE_API_KEY" \
"https://rankscale.ai/v1/metrics/brands" \
-o brands.json
curl -s -X POST -H "Authorization: Bearer $RANKSCALE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"brandId":"<id>"}' \
"https://rankscale.ai/v1/metrics/report" \
-o report.json
# PowerShell 동일
curl.exe -s -H "Authorization: Bearer $env:RANKSCALE_API_KEY" `
"https://rankscale.ai/v1/metrics/brands" `
-o brands.json
curl.exe -s -X POST -H "Authorization: Bearer $env:RANKSCALE_API_KEY" `
-H "Content-Type: application/json" `
-d '{\"brandId\":\"<id>\"}' `
"https://rankscale.ai/v1/metrics/report" `
-o report.json
PowerShell 참고: curl.exe를 사용하세요(curl 별칭은 Invoke-WebRequest를 가리키며 동작이 다릅니다). -d JSON 본문에서 내부 따옴표를 \"로 이스케이프하고, 줄 연속에는 백틱 `을 사용하세요. Invoke-RestMethod도 작동하며 JSON을 자동으로 파싱하지만, curl 형식은 셸 전반에 걸쳐 응답을 일관되게 유지합니다.
완전한 엔드포인트 목록과 요청 형태는 references/endpoints.md에 있습니다. 확실하지 않은 호출 전에 읽어보세요. 놀라움과 함정은 references/quirks.md에 있습니다. 사용자에게 메트릭을 보고하기 전에 읽어보세요. 여러 항목이 숫자를 해석하는 방식에 영향을 미치기 때문입니다.
범위 밖: 공유 링크 API. Rankscale은 공개 대시보드 공유 링크를 위한 두 번째 REST API를 게시합니다. 다른 키(Settings → Integrations가 아닌 Settings → Sharing)를 사용하므로 RANKSCALE_API_KEY로는 인증할 수 없습니다. 사용자가 공유 링크를 만들거나 취소하도록 요청하면 이것은 이 스킬이 다루지 않는 별도 API라고 말하세요. 경로를 추측하지 마세요.
작업 흐름 레시피
1. 브랜드 식별
대부분의 보고 엔드포인트에는 brandId가 필요합니다. 사용자가 브랜드 이름을 지정하면("Acme의 메트릭 보여줘") 먼저 ID를 확인하세요:
- 사용자 작업 디렉토리에
Rankscale/brands.json이 있으면 읽습니다. - 그렇지 않으면
GET /v1/metrics/brands를 호출하고 결과를 저장합니다. - 사용자의 브랜드 이름을
brands[].name(대소문자 구분 없음) 및brands[].brandInfo.names(별칭)와 일치시킵니다. 여러 개 일치하면 사용자에게 명확히 하도록 요청하세요.
2. 브랜드의 기간별 메트릭 가져오기
사용자는 거의 항상 시간 창을 요청합니다. timeFrame(camelCase, 대문자 F — API는 다른 철자를 자동으로 무시합니다)을 다음 문서화된 사전 설정 중 하나와 함께 사용하세요: 24h, 7d, 30d, 3m, 1y. 버킷 크기를 위해 aggregation(hourly, daily, weekly 또는 monthly)과 쌍을 이루세요. 사용자 정의 창의 경우 isoStartDate + isoEndDate(쌍을 이루는 ISO 날짜 문자열)를 사용하세요. 이것들은 timeFrame을 재정의합니다.
{
"brandId": "<id>",
"timeFrame": "30d",
"aggregation": "daily",
"includeNotFoundExecutions": true
}
선택적 보고 필터(모두 단일 문자열, OR-within-field의 경우 배열, 또는 필터 없음의 경우 "all"을 허용하며, 필터는 필드 간 AND로 결합):
selectedTopic— 토픽 ID, 토픽 이름,_orphaned또는 배열selectedTags— 태그,__UNTAGGED__또는 배열selectedEngine— 엔진 ID(선호 — 카탈로그는references/endpoints.md참조) 또는 친근한 이름selectedQuery— 정확한 검색어 쿼리 문자열 또는 배열searchTermId— 단일 검색어 IDperiodOffset— 정수, 사전 설정 창을 N 기간 뒤로 이동(0 = 현재, 1 = 이전, …)userTimezone— 사용자 로컬 일 경계를 위한Europe/Berlin과 같은 IANA 표준 시간대includeNotFoundExecutions— 부울, "답변에서 브랜드를 찾을 수 없음" 실행이 메트릭에 포함될지 여부 제어(특이사항.md 참조)
data.ownBrandMetrics.historicalData.<aggregation>(예: aggregation: "daily"를 요청한 경우 .daily)에서 응답을 읽으세요. 각 버킷 배열 — visibilityScore, sentiment, mentions, sources, citations, citationCounts, avgPosition, detectionRate, top3, brandNotFound — 은 timestamps와 병렬로 실행됩니다.
세 개의 병렬 시계열이 그 옆에 있습니다:
data.ownBrandMetrics.topicMetricsData.<aggregation>— 토픽별data.ownBrandMetrics.engineMetricsData.<aggregation>— 엔진별; 업스트림에서 문서화되지 않음, 일반적으로 창 집계가 평평해 보일 때 가장 가치 있는 컷입니다. 엔진 수준 이동이 전체에서 서로 상쇄되기 때문입니다(특이사항 §25)data.competitorTimeSeriesData.<aggregation>— 경쟁사별, 자사 브랜드 제외(특이사항 §16)
brandNotFound[]는 신호가 아닙니다 — 100% 미만 감지율의 브랜드에 대해 기본적으로 true를 읽습니다. detectionRate를 대신 사용하고 플래그에서 "브랜드를 찾을 수 없음"을 보고하지 마세요(특이사항 §2).
다음 열이 있는 메트릭 테이블을 제시하세요: 날짜, 가시성, 감성, 언급 수, 인용 수, 평균 위치, 감지율 %, 상위 3% %. 그 위에 요약 스냅샷(ownBrandMetrics의 현재 스냅샷 값 + trends 델타)을 표시하세요.
브랜드 순위 (가시성별) — 경쟁사 대비. data.competitorMetrics[](자사 브랜드 포함, isOwnBrand: true 플래그)에서 계산: 순위 = 1 + (엄격히 더 큰 visibilityScore를 가진 항목 수). 동점은 브랜드를 낮추지 않습니다. 이것은 대시보드의 순위를 재현합니다. 응답에는 항목당 latestRank/avgRank도 포함됩니다. 이것들은 순위가 아닙니다. 2026-08-07 확인: 계산된 순위가 1인 브랜드에 대해 정수가 아닌 값(latestRank: 2.7, avgRank: 2.9)을 반환하므로 위치와 유사한 것을 추적하지만 서수는 아닙니다. 무시하세요. MCP의 동등한 own_brand_rank도 마찬가지로 항상 1(디스플레이 핀)입니다. 위의 가시성 정렬 계산은 테스트에서 대시보드와 일치하는 방법입니다. 공유 필터(selectedEngine, selectedTopic, selectedTags, selectedQuery)는 컷별로 작동하므로 필터링을 다시 실행하여 단일 엔진, 토픽, 태그 또는 쿼리 내에서 순위를 매길 수 있습니다. competitorMetrics 항목은 자사 브랜드와 다른 validMetricsCount를 가질 수 있습니다(경쟁사 기준은 더 넓은 창을 사용함). 그러나 순서는 여전히 UI와 일치합니다. 전체 레시피 — 시간 경과에 따른 일일 순위 및 주의 사항 포함 — 아래 레시피 §6에 있습니다.
3. 인용 분석
/v1/metrics/citations는 AI 모델이 사용자의 검색어에 답할 때 인용하는 출처(사이트, 기사)를 반환합니다. 브랜드에 대한 AI 답변에 영향을 미치는 타사 도메인을 이해하는 데 유용합니다.
주요 필드: data.totalCitations, data.uniqueCitations(고유 URL), data.uniqueDomains, data.citationsByDomain[](모든 도메인). 각 도메인 항목에서 occurrences는 개수입니다. citations 필드는 숫자가 아닌 URL 배열입니다. 따라서 인용 점유율 = occurrences / totalCitations, 상위 URL은 각 도메인의 URL 배열을 평탄화하고 occurrences별로 정렬하여 나옵니다.
각 URL 객체는 {url, normalizedUrl, occurrences, engineAppearances: {<engineId>: count}, firstSeenAt, lastSeenAt, category, searchTerms[]}입니다. engineAppearances는 API에서 유일한 엔진별 인용 분석입니다. 도메인의 URL에서 합산하여 "어떤 엔진이 우리 사이트를 인용하는지"에 답하세요. firstSeenAt/lastSeenAt은 실제로 얻은 창의 유일한 반영입니다. 페이지 수준 분석 전에 normalizedUrl을 더 정규화하세요(www./후행 슬래시/쿼리 변형을 구별된 상태로 둡니다). category: "owned"는 "회사 자체 사이트"를 의미하며, 추적된 브랜드가 소유한 것이 아닙니다. 경쟁사도 이것을 가지고 있습니다. 특이사항.md §13b를 참조하세요. data.domainSummary에는 사전 컷된 보기(topDomainsOverall, topDomainsByEngine, topDomainsByQuery, topDomainsByOwnBrandCitations, topDomainsByCompetitor)가 있습니다. 그러나 이것들은 제한되어 있으며(약 20/10개 항목), topDomainsByCompetitor는 경쟁사가 언급된 도메인을 나열합니다(Reddit/Booking과 같은 중립적인 타사 사이트 포함). 따라서 경쟁사 소유 사이트를 식별하는 데 사용하지 마세요. 특이사항.md §13b를 참조하세요.
목록을 완전하다고 부르기 전에 제한 사항을 확인하세요. 응답은 기본적으로 5,000개의 고유 URL 및 50개 브랜드로 제한됩니다. data.paginationInfo는 진실을 보고합니다 — citationsCapped, brandsCapped, responseTrimmed, capBypassed, maxCitations, maxBrands, totalCount vs returnedCount. URL 제한을 해제하려면 uncapped: true(본문 또는 쿼리 매개변수)를 전달하세요. 50개 브랜드 제한이나 응답 크기 가드는 해제하지 않습니다. deduplicated: true는 응답 경로를 중복 제거하고 data.searchTermsById를 추가합니다. 캡 플래그가 true이면 사용자에게 알리고 잘린 목록을 전체 그림으로 제시하는 대신 창을 좁히거나 필터링하세요. 특이사항.md §13c를 참조하세요.
4. 감성
/v1/metrics/sentiment는 추적된 브랜드와 모든 경쟁사에 대한 기간 수준 감성 집계와 키워드 클라우드를 반환합니다. 시계열이 아닙니다(시간에 따른 감성은 /report의 historicalData.<agg>.sentiment[]를 사용하세요). 동일한 공유 필터에 deduplicated: true가 추가됩니다.
범위가 다른 두 배열: data.brandSentiments[]는 추적된 브랜드만 해당합니다. data.companySentiments[]는 자사 브랜드를 포함한 모든 감지된 브랜드입니다(isOwnBrand: true). 경쟁사 비교에는 이것을 사용하세요. brandSentimentsBySearchTerm[] / companySentimentsBySearchTerm[]은 검색어별로 동일한 컷을 제공합니다.
항목별: avgSentiment(0–100 척도, = totalSentimentScore / sentimentCount), sentimentCount, executionCount, positiveCount / neutralCount / negativeCount. 감성은 소스별로 분할됩니다. webGrounding*(웹 기반 엔진) vs trainingData* 블록, hasWebGrounding / hasTrainingData 부울로 게이트되며, webGroundingSentimentByEngine[<engineId>] = {sum, count, avg}는 엔진별 점수를 제공합니다.
두 가지 함정 — 이것을 보고하기 전에 특이사항.md §19를 읽으세요. (1) po... (트렁크화됨)
5. 검색어 보고서
/v1/metrics/search-terms-report는 각 검색어에 대한 세부 메트릭을 반환합니다...
6. 시간 경과에 따른 일일 브랜드 순위
...
참고 자료
references/endpoints.md— 전체 엔드포인트 목록 및 요청 형태references/quirks.md— 알려진 특이사항 및 해석 지침