# Storelift API

URL: https://storelift.net/ko/guide/storelift-api/
Language: ko
Updated: 2026-09-20

대시보드에 보이는 모든 것은 JSON 엔드포인트로도 제공됩니다. 모두 9개이고, 전부 GET이며, 모두 내가 추적하는 앱만 대상으로 합니다. 따라서 스크립트, 스프레드시트 작업, CI 단계에서 페이지를 스크래핑하지 않고도 같은 숫자를 읽을 수 있습니다. API는 Pro와 Studio에 포함되며, 같은 데이터를 AI 어시스턴트가 읽는다면 보통 MCP 서버가 더 적합합니다.

## 기본 주소와 인증

기본 주소는 https://storelift.net/v1입니다. 설정 → API에서 키를 만드세요. 키는 한 번만 표시되고 해시로만 저장되므로, 잃어버린 키는 복구되지 않고 새로 발급합니다.

키는 x-api-key로 보내거나, 클라이언트가 Authorization 헤더만 지원한다면 bearer 토큰으로 보냅니다.

curl -s https://storelift.net/v1/apps \
-H "x-api-key: sl_live_..."

NOTE: API는 Pro와 Studio 플랜에서 사용할 수 있습니다 — 월 $20부터, Studio는 $60입니다. 플랜을 다운그레이드하면 키는 작동을 멈추지만 삭제되지는 않으므로, 다시 업그레이드하면 같은 연동이 그대로 살아납니다.

## 9개 엔드포인트

| 엔드포인트 | 반환하는 내용 |
| --- | --- |
| GET /v1/apps | 이 계정이 추적하는 앱 목록입니다. 다른 모든 호출은 여기서 시작하며, id도 이 호출에서 얻습니다. |
| GET /v1/apps/{id} | 앱 하나와 가장 최근 측정의 스냅샷입니다. |
| GET /v1/apps/{id}/keywords | 한 스토어프런트에서 추적 중인 키워드별 현재 순위와 함께, 측정 상태와 검색한 깊이를 반환합니다. |
| GET /v1/apps/{id}/rivals | 내 앱보다 위에 있는 앱들과, 각 앱이 나를 앞서는 검색어 및 양쪽의 순위를 반환합니다. |
| GET /v1/apps/{id}/ai | AI 어시스턴트가 내 카테고리에서 내 앱을 언급하는지와 저장된 시계열입니다. 측정은 Studio에서 이뤄집니다. |
| GET /v1/apps/{id}/history | 키워드별 순위 시계열로, 플랜의 기록 기간에 맞춰 잘립니다. |
| GET /v1/apps/{id}/page | 스토어가 실제로 보여 주는 내 스토어 페이지(두 플랫폼 모두)와, 그 페이지에서 감지된 날짜별 변경 사항입니다. |
| GET /v1/apps/{id}/reviews | 최근 리뷰와 별점 요약, 이번 측정에서 새로 들어온 리뷰 수, 그리고 측정된 경우 Play 쪽 데이터입니다. |
| GET /v1/apps/{id}/charts | 앱의 장르와 스토어프런트 기준 인기 차트 순위와 그 시계열입니다. |

/apps/{id} 아래의 엔드포인트는 country(us 같은 스토어프런트 코드, 기본값은 앱의 첫 번째 스토어프런트)를 받으며, 두 스토어가 모두 측정되는 경우 platform=ios|android도 받습니다.

## 세 가지 측정 상태는 API에서도 그대로 유지됩니다

연동을 작성하기 전에 꼭 읽어 둘 부분입니다. 순위 필드는 숫자일 수 있지만, 숫자가 없다는 것은 서로 다른 두 가지를 뜻하며 API는 이 둘을 구분해서 전달합니다.

- measured: true, rank: 7 — 앱이 7위에서 발견되었습니다.
- measured: true, rank: null — 검색은 실행되었지만, 저희가 읽은 깊이 안의 결과에 앱이 없었습니다.
- measured: false — 그날은 검색을 실행하지 못했습니다. 순위에 대해 알려진 것이 없습니다.

{
"country": "de",
"platform": "ios",
"live": true,
"measuredAt": "2026-09-19T02:14:08.921Z",
"keywords": [
{ "term": "traumdeutung", "measured": true, "rank": 7, "demand": 6, "searchDepth": 200 },
{ "term": "traumsymbole", "measured": true, "rank": null, "demand": 3, "searchDepth": 200 },
{ "term": "traumtagebuch", "measured": false, "rank": null, "demand": null, "searchDepth": null }
]
}

뒤의 두 경우를 0으로 합쳐 버리면 실제로 일어나지 않은 급락을 묘사하게 되고, 그 위에 쌓은 모든 평균이 틀어집니다. 코드에서 숫자 하나가 필요하다면 measured: false를 값이 아니라 시계열의 빈 구간으로 처리하세요.

## 하지 않는 일

- 쓰기를 하지 않습니다. 모든 엔드포인트는 GET이며, 다른 메서드는 method_not_allowed를 반환합니다. API에서 내 스토어 페이지, 추적 키워드, 결제로 이어지는 경로는 없습니다.
- 요청 시 측정하지 않습니다. 엔드포인트는 매일 밤 측정에서 수집된 데이터를 읽습니다. 두 번 요청해도 스토어에 두 번째 쿼리가 가지 않습니다.
- 매출 레이어는 제공하지 않습니다. 연결된 계정(App Store Connect, Apple Ads, RevenueCat, GA4)은 대시보드에만 남습니다. 빠뜨린 것이 아니라 의도적으로 그은 선입니다.
- 기록은 플랜에 따라 잘립니다. history와 charts 모두 플랜의 기간에서 잘리므로, 같은 키로 한 엔드포인트를 통해 다른 엔드포인트보다 더 먼 과거에 접근할 수 없습니다.

## 오류

| 상태 | error | 발생 조건 |
| --- | --- | --- |
| 401 | missing_api_key | 요청에 키가 없습니다. |
| 401 | invalid_api_key | 알 수 없는 키이거나 폐기된 키입니다. |
| 401 | account_deleted | 키에 연결된 계정이 삭제되었습니다. |
| 403 | plan_required | 플랜에 API 사용 권한이 없습니다. 응답에 현재 플랜이 포함됩니다. |
| 405 | method_not_allowed | 모든 엔드포인트는 GET입니다. 쓰기는 없습니다. |
| 404 | not_found | 해당 앱 id가 이 계정에 없습니다. |
| 404 | unknown_endpoint | /v1 아래에 그런 경로가 없습니다. |

모든 오류는 error 필드가 있는 JSON입니다. plan_required는 plan도 함께 반환하므로, 클라이언트가 추측하지 않고 키가 어떤 플랜에 있는지 알려 줄 수 있습니다.

## FAQ

Q: 요청 횟수 제한이 있나요?
A: 키별 할당량은 없습니다. API 앞단의 게이트웨이에 계정 전체 상한이 있고, 호출할 때마다 키의 사용 카운터가 갱신되므로 오래된 키가 아직 쓰이는지 설정에서 확인할 수 있습니다.

Q: 무료 플랜에서도 쓸 수 있나요?
A: 아니요. API는 Pro부터 사용할 수 있습니다. 이 사이트의 무료 도구는 계정 없이 쓸 수 있고, 무료 플랜도 앱 하나를 매일 측정합니다.

Q: API와 MCP 서버 중 무엇을 써야 하나요?
A: 스크립트에는 API가 맞습니다. 응답 형태가 고정돼 있고, 호출 한 번이면 되며, 중간에 모델이 끼지 않습니다. AI 어시스턴트에는 MCP 서버가 맞습니다. 도구마다 자체 설명이 있어 연동 코드를 직접 짜지 않아도 알맞은 호출을 고를 수 있기 때문입니다. 둘 다 같은 측정값을 읽습니다.