기본 주소와 인증
기본 주소는 https://storelift.net/v1입니다. 설정 → API에서 키를 만드세요. 키는 한 번만 표시되고 해시로만 저장되므로, 잃어버린 키는 복구되지 않고 새로 발급합니다.
키는 x-api-key로 보내거나, 클라이언트가 Authorization 헤더만 지원한다면 bearer 토큰으로 보냅니다.
curl -s https://storelift.net/v1/apps \
-H "x-api-key: sl_live_..."27개 엔드포인트
| 엔드포인트 | 반환하는 내용 |
|---|---|
GET /v1/apps | 이 계정이 추적하는 앱 목록입니다. 다른 모든 호출은 여기서 시작하며, id도 이 호출에서 얻습니다. |
GET | 앱 하나와 가장 최근 측정의 스냅샷입니다. |
GET | 한 스토어프런트에서 추적 중인 키워드별 현재 순위와 함께, 측정 상태와 검색한 깊이를 반환합니다. |
GET | 내 앱보다 위에 있는 앱들과, 각 앱이 나를 앞서는 검색어 및 양쪽의 순위를 반환합니다. |
GET | AI 어시스턴트가 내 카테고리에서 내 앱을 언급하는지와 저장된 시계열입니다. Pro, Studio 또는 Enterprise 플랜이 필요합니다. |
GET | 키워드별 순위 시계열로, 플랜의 기록 기간에 맞춰 잘립니다. |
GET | 스토어가 실제로 보여 주는 내 스토어 페이지(두 플랫폼 모두)와, 그 페이지에서 감지된 날짜별 변경 사항입니다. |
GET | 최근 리뷰와 별점 요약, 이번 측정에서 새로 들어온 리뷰 수, 그리고 측정된 경우 Play 쪽 데이터입니다. /reviews/search는 전체 아카이브를 텍스트·별점·버전·날짜로 검색하고, /reviews/stats는 분포, 일별 추이, 버전별 내역을 제공합니다. |
GET | 날짜별 스토어 등록 정보 변경 — 버전, 스크린샷, 이벤트, 피처드, 키워드 필드 수정 — 과 각 변경 전후의 키워드 순위 변동. |
GET | 국가별 에디토리얼 카드, 앱 내 이벤트, Apple의 '좋아할 만한 다른 앱' 선반. 피처드와 새 이벤트의 날짜별 기록 포함. |
GET | 앱의 장르와 스토어프런트 기준 인기 차트 순위와 그 시계열입니다. |
GET | 연결된 소스에서 가져온 앱의 매출과 다운로드입니다. App Store Connect 판매 단위, Google Play 설치 수, RevenueCat MRR, 구독과 체험을 담습니다. 연결된 소스가 없으면 connected:false를 반환합니다. 스코프 revenue:read. |
GET | RevenueCat / Adapty 웹훅에서 받은 구독 이벤트 수를 일별, 국가별, 월간 코호트별로 반환합니다. 스코프 revenue:read. |
GET | App Store 노출 → 제품 페이지 조회 → 다운로드. App Store Connect 분석에서 가져온 오늘의 값과 일별 기록입니다. 스코프 revenue:read. |
GET | RevenueCat / Adapty 웹훅에서 가져온 제품·국가별 현재 가격, 고정 가격 기간별 체험·유료 시작·매출, 그리고 오퍼 코드. 스코프 revenue:read. |
GET | 이 앱을 홍보하는 Apple Ads 캠페인(App Store id로 매칭)의 지출, 탭, 설치, 예산, 상태와 함께 상위 키워드 및 검색어를 반환합니다. 스코프 ads:read. |
/apps/{id} 아래의 엔드포인트는 country(us 같은 스토어프런트 코드, 기본값은 앱의 첫 번째 스토어프런트)를 받으며, 두 스토어가 모두 측정되는 경우 platform=ios|android도 받습니다.
세 가지 측정 상태는 API에서도 그대로 유지됩니다
연동을 작성하기 전에 꼭 읽어 둘 부분입니다. 순위 필드는 숫자일 수 있지만, 숫자가 없다는 것은 서로 다른 두 가지를 뜻하며 API는 이 둘을 구분해서 전달합니다.
measured: true,rank: 7— 앱이 7위에서 발견되었습니다.measured: true,rank: null— 검색은 실행되었지만,searchDepth까지의 결과에 앱이 없었습니다.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를 값이 아니라 시계열의 빈 구간으로 처리하세요.
계정, 사용량, 검색
키 자체와 계정의 기록에 관한 엔드포인트 4개입니다. 앞의 두 개는 크레딧이 들지 않으므로, 스크립트가 시작하기 전에 무엇을 읽을 수 있고 얼마나 남았는지 확인할 수 있습니다. search와 fetch는 ChatGPT가 딥 리서치 커넥터에 기대하는 형태를 따릅니다. 검색어를 보내면 id가 돌아오고, id를 보내면 레코드가 돌아옵니다.
| 엔드포인트 | 반환하는 내용 |
|---|---|
GET /v1/account | 키의 소유자 정보입니다. 플랜, 인증 방식, 스코프, 읽을 수 있는 앱, 크레딧 잔액. 크레딧 0. |
GET /v1/usage | 모든 할당량의 사용량 / 한도 / 초기화 시점, 오늘의 Hive 허용량, 초당 요청 한도. 크레딧 0. |
GET | 내 앱, 추적 키워드, 경쟁 앱을 검색하고 /v1/fetch에 쓸 id를 반환합니다(ChatGPT 딥 리서치 형태). |
GET | 검색 id에 해당하는 전체 레코드입니다. 앱 카드, 기록이 포함된 키워드 하나, 또는 나를 앞서는 검색어가 포함된 경쟁 앱 하나. |
Hive: 모든 앱, 모든 시장
위의 엔드포인트는 내가 추적하는 앱을 읽습니다. Hive 엔드포인트는 네트워크 전체가 측정한 데이터를 읽습니다. 차트, 모든 앱의 일일 측정값, 키워드 검색 결과 목록, 경쟁 앱의 키워드, 모든 앱의 매출과 다운로드입니다. 키에 별도 스코프가 필요하고 호출당 크레딧이 더 들며, 플랜마다 일일 Hive 허용량이 있어 한 달 치 크레딧이 한 달 동안 유지됩니다.
| 엔드포인트 | 반환하는 내용 | 스코프 |
|---|---|---|
GET | 최신일 기준 스토어프런트의 Top Free, Top Grossing 또는 iPad 차트(100위까지). | hive:read |
GET | 모든 앱의 최신 일일 측정값입니다. 평가 수, 평점, 버전, 가격, 별점 분포, 카테고리 배지와 함께 지원 언어, 예정된 인앱 이벤트, 프로모션 텍스트, 추천 인앱 구매. | hive:read |
GET | 키워드에서 어떤 앱이 몇 위였는지를 일별로(호출당 1,000행). | hive:read |
GET | 경쟁 앱이 순위에 오른 키워드입니다. 대시보드와 같은 개인정보 필터와 월간 스파이 허용량이 적용됩니다. | hive:spy |
GET | 모든 App Store 앱의 전 세계 월간 매출과 다운로드입니다(첫 측정이 진행 중일 때는 202). | hive:estimate |
GET | 한 인기 차트에서 N일 전 같은 차트와 비교해 오른 앱, 떨어진 앱, 새로 들어온 앱, 빠진 앱입니다. 모든 변화량은 측정된 두 날 사이에서 계산되며, 응답에 그 두 날짜가 함께 표시됩니다. | hive:read |
GET | 인기 차트에 처음 등장한 앱을 최신순으로 반환합니다. 응답에는 그 기간 중 인덱스가 다룬 일수가 함께 담기므로, 모든 첫 등장 날짜는 실제로 인덱싱한 날입니다. | hive:read |
GET | 측정하는 차트 전체에서 앱을 찾습니다. 카테고리, 스토어프런트, 차트(Top Grossing, Top Free, Top Paid, Top iPad), 순위 구간, 첫 등장 날짜, 이름, 퍼블리셔로 필터링할 수 있습니다. 모든 행에 그 앱의 매출과 다운로드가 붙습니다. | hive:read |
GET | 최대 다섯 개 앱의 키워드 갭을 나란히 보여 줍니다. 각 앱이 어떤 검색어에서 순위에 오르고 어떤 검색어를 놓치는지. Hive Explorer. 스파이와 같은 개인정보 필터가 적용되고, 앱마다 자체 측정 상태가 붙어 표의 모든 칸이 측정된 사실입니다. | hive:spy |
GET | Hive가 본 한 퍼블리셔의 모든 앱과, 각 앱이 처음 차트에 오른 날짜입니다. | hive:read |
GET | 이름, 개발사, 스토어 링크, App Store ID, 패키지 이름으로 아무 앱의 ID를 찾습니다. 이름은 해당 스토어의 App Store 검색을 거칩니다. | hive:read |
GET | 아무 앱에 대한 스토어의 비슷한 앱 선반. 선반 순서대로 각 앱의 카테고리와 이름, 읽은 날짜 포함. | hive:read |
GET | 아무 앱의 한 스토어 최신 리뷰와 별점 분포. 작성자 이름은 제외합니다. | hive:read |
개인 정보는 이 경계를 넘지 않습니다. 리뷰 작성자는 표시되지 않으며, 경쟁 앱의 키워드는 다른 계정이 두 개 이상 추적하거나 내가 추적할 때만 보입니다.
키 없이 써 보기
모든 경로는 키 없이 /v1/sandbox/ 아래에서도 사용할 수 있습니다. 응답 형태는 같고, 고정된 앱 두 개의 데이터셋에 날짜는 어제를 기준으로 움직입니다. 응답에는 x-sandbox: true가 붙습니다. CI용으로는 설정에서 테스트 키(sl_test_)를 만들 수 있습니다. 테스트 키는 샌드박스에서만 응답하고 크레딧을 쓰지 않으며 모든 플랜에서 작동하므로, 유출되더라도 드러나는 데이터가 없습니다.
curl -s https://storelift.net/v1/sandbox/apps
curl -s 'https://storelift.net/v1/sandbox/hive/keywords/sleep%20sounds/ranks?country=us&days=3&top=10'쓰기와 스코프가 작동하는 방식
- 모든 쓰기는 먼저 미리 봅니다. 읽기는
GET입니다.POST /v1/actions는 아무것도 바꾸지 않고 변경 전후 비교, 크레딧 비용, 일회용 토큰을 반환하며,POST /v1/actions/confirm이 이를 적용합니다. 토큰은 작업, 인수, 미리 보기 시점의 대상 상태에 묶여 있으므로, 그 사이에 대상이 바뀌면 확인 요청은 새 비교와 함께confirm_token_mismatch를 반환하고 아무것도 쓰지 않습니다. 작업은 키워드, 경쟁 앱, 앱, 공유 링크, 리뷰 답글(Pro부터), 그리고 Studio에서는 편집 가능한 App Store 버전의 스토어 페이지 텍스트와 Apple Ads 일시 중지·재개·일일 예산을 다룹니다. 전체 목록은 레퍼런스에 있습니다. - 쓰기 스코프는 직접 켭니다. 쓰기마다 해당 스코프(
track:write,reports:write,reviews:write,ads:write,listing:write)가 필요하며, 키를 만들 때는 모두 꺼진 상태로 시작합니다. 테스트 키는 샌드박스에서 응답하고 내 데이터는 그대로 둡니다. 결제는 계정 설정에서 관리합니다. - 관측 날짜와 상태를 확인하세요. 응답에는 저장된 측정값, 확인된 데이터 부재, 대기 중인 작업 또는 오류가 포함될 수 있습니다. 요청을 반복해도 과거 관측의 날짜가 새로워지지는 않습니다.
- 매출 레이어는 별도 스코프 뒤에 있습니다. 성장 엔드포인트 10개(
revenue,subscriptions,funnel,pricing,change-impact,campaigns,ads-keywords,ads-search-terms,ads-commands,search-popularity)는 민감 스코프revenue:read/ads:read로 만든 키에 응답하므로, 매출 데이터는 내가 선택했을 때만 키로 열립니다. GA4는 대시보드에서 봅니다. - 기록 기간은 플랜을 따릅니다.
history와charts모두 플랜의 기간을 사용하므로, 같은 키는 어느 엔드포인트로든 정확히 같은 과거까지 닿습니다.
오류
| 상태 | error | 발생 조건 |
|---|---|---|
| 401 | missing_api_key | 요청에 키가 없습니다. |
| 401 | invalid_api_key | 알 수 없는 키이거나 폐기된 키입니다. |
| 401 | account_deleted | 키에 연결된 계정이 삭제되었습니다. |
| 403 | plan_required | 플랜에 API 사용 권한이 없습니다. 응답에 현재 플랜이 포함됩니다. |
| 405 | method_not_allowed | 읽기는 GET이며, POST는 /v1/actions, /v1, /v1에서 받습니다(초안은 본문으로 보냅니다). |
| 400 | unknown_action | 작업 이름이 카탈로그에 없습니다. 응답에 사용할 수 있는 작업 목록이 포함됩니다. |
| 400 | invalid_arguments | 인수가 빠졌거나 형식이 잘못되었습니다. 응답에 해당 필드가 표시됩니다. |
| 409 | confirm_token_expired | 토큰이 발급된 지 10분이 지났습니다. 다시 미리 보세요. |
| 409 | confirm_token_mismatch | 미리 보기 이후 대상이 바뀌었습니다. 응답에 새 비교가 포함됩니다. |
| 403 | write_limit_reached | 쓰기가 안전 한도(예산 변경 폭, 일일 작업 횟수)를 벗어났습니다. |
| 403 | test_key_read_only | 쓰기는 라이브 키로 실행합니다. 테스트 키는 샌드박스에서 응답합니다. |
| 404 | job_not_found | 이 워크스페이스에 해당 id의 작업이 없습니다. |
| 403 | workspace_suspended | 워크스페이스가 정지되었습니다. 사유는 지원팀에 문의하세요. |
| 403 | ip_list_required | 이 워크스페이스는 모든 키에 IP 허용 목록을 요구합니다. |
| 404 | not_found | 해당 앱 id가 이 계정에 없습니다. |
| 404 | unknown_endpoint | /v1 아래에 그런 경로가 없습니다. |
| 402 | credits_exhausted | 이번 달 크레딧을 모두 사용했습니다. 응답에 크레딧 팩 링크가 포함됩니다. |
| 429 | rate_limited | 이 키의 요청이 너무 많습니다. Retry-After에 표시된 초만큼 기다리세요. |
| 429 | daily_hive_limit | 플랜의 오늘 Hive 허용량을 모두 사용했습니다. 00:00 UTC에 초기화됩니다. |
| 404 | not_measured | 요청한 앱, 키워드 또는 범위에 대해 검증된 관측값이 없습니다. 누락된 데이터는 0이 아닙니다. 요청 매개변수와 연결된 문서에서 가능한 작업을 확인하세요. |
| 400 | bad_query | /v1/search에는 1–120자의 q가 필요합니다. |
| 400 | bad_id | /v1/fetch에는 /v1/search가 반환한 그대로의 id가 필요합니다. |
| 403 | asc_required | update_listing에는 연결된 App Store Connect 키가 필요합니다. |
| 403 | asc_role | 메타데이터를 편집하려면 App Store Connect 키에 Admin 또는 App Manager 역할이 필요합니다. |
| 409 | no_editable_version | 편집 가능한 App Store 버전이 없습니다. 응답에 현재 버전 상태가 나열됩니다. |
| 404 | locale_not_found | 해당 스토어프런트 언어가 이 버전에 없습니다. 응답에 있는 언어 목록이 포함됩니다. |
| 409 | changed_since_preview | 미리 보기 이후 App Store Connect에서 스토어 페이지가 바뀌었습니다. 아무것도 쓰지 않았습니다. |
| 422 | asc_rejected | App Store Connect가 변경을 거부했습니다. 원래 메시지는 detail에 있습니다. |
| 409 | in_progress | 같은 대상에 대한 쓰기가 아직 진행 중입니다. |
| 403 | ip_not_allowed | 키에 IP 허용 목록이 있는데 이 요청은 목록 밖에서 왔습니다. |
| 401 | key_leaked | 키가 공개 저장소에서 발견되어 자동으로 폐기되었습니다. 새 키를 만드세요. |
모든 오류는 error 필드가 있는 JSON입니다. plan_required는 plan도 함께 반환하므로, 클라이언트가 추측하지 않고 키가 어떤 플랜에 있는지 알려 줄 수 있습니다.
자주 묻는 질문
요청 횟수 제한이 있나요?
네, 키마다 있습니다. 플랜별 초당 요청 수(초과 시 Retry-After와 함께 429), x-credits-* 헤더에 표시되는 월간 크레딧 허용량, 그리고 일일 Hive 허용량입니다. 호출할 때마다 키의 사용 카운터도 갱신되므로, 오래된 키가 아직 쓰이는지 설정에서 확인할 수 있습니다.
무료 플랜에서도 쓸 수 있나요?
API용 라이브 키는 Pro부터입니다. 키 없는 샌드박스와 테스트 키는 모든 플랜에서 작동하고, 원격 MCP 서버도 Pro부터이며, 이 사이트의 무료 도구는 계정 없이 쓸 수 있고, 무료 플랜은 앱 하나를 매일 측정합니다.
API와 MCP 서버 중 무엇을 써야 하나요?
스크립트에는 API가 맞습니다. 응답 형태가 고정돼 있고, 호출 한 번이면 되며, 중간에 모델이 끼지 않습니다. AI 어시스턴트에는 MCP 서버가 맞습니다. 도구마다 자체 설명이 있어 연동 코드를 직접 짜지 않아도 알맞은 호출을 고를 수 있기 때문입니다. 둘 다 같은 측정값으로 일하고, 둘 다 같은 '미리 보기 후 확인' 단계를 거쳐 씁니다.
내 앱으로 직접 확인해 보세요
스토어 링크를 붙여넣고 키워드를 추가하세요. 순위, 내 위에 있는 앱, 수요를 매일 측정합니다.
무료 플랜: 앱 1개, 스토어프런트 2곳에서 각각 키워드 10개, 14일 기록. 카드 불필요, 기간 제한 없음. Pro는 월 $29.
무료로 시작하기 →
