# 구글 검색 순위 확인 키워드로 구글을 검색했을 때 지정한 도메인이 1~100위 중 몇 위에 노출되는지 확인합니다. 인증: Authorization: Bearer $APICK_API_KEY 본문 있는 REST 요청: multipart/form-data. GET 본문 및 MCP JSON-RPC 규격은 해당 명세를 따릅니다. 인증키는 서버에 보관하세요. 모든 예제는 정적 자료입니다. ## POST /rest/google_rank_check 응답 필드 - `data` (object): 조회 데이터. 실패하면 error 에 안내 문구가 담깁니다. - `data.keyword` (string): 요청한 검색어 - `data.domain` (string): 확인한 도메인 - `data.found` (boolean): 100위 안 노출 여부 - `data.rank` (integer): 가장 높은 순위. 없으면 null null 허용. - `data.matches` (array): 노출된 결과 목록 (최대 10개) - `data.matches[].rank` (integer): 순위 - `data.matches[].title` (string): 검색 결과 제목 - `data.matches[].link` (string): 검색 결과 주소 - `data.checked_results` (integer): 확인한 검색 결과 수 - `data.checked_pages` (integer): 확인한 10위 구간 수 (최대 10) - `data.complete` (boolean): 1~100위를 모두 확인했거나, 앞에서부터 끊김 없이 확인한 구간에서 찾았으면 true - `data.unchecked_ranks` (array): 확인하지 못한 순위 구간 (예: "41-50"). complete 가 true 면 빈 배열 - `api` (object): API 호출 공통 데이터 - `api.success` (boolean): API 서버 정상 응답 여부 - `api.cost` (integer): 차감된 포인트. 실패한 응답은 0 - `api.pl_id` (integer): API 결제 로그 ID - `api.ms` (integer): API 응답 시간(밀리초) ## API 요청: POST /rest/google_rank_check ### 입력 - `keyword` (string, 필수): 검색어 (1~200자) - `domain` (string, 필수): 순위를 확인할 도메인 (예: apick.app). 하위 도메인도 함께 찾습니다 ### 응답 명세 ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "keyword": { "type": "string", "description": "요청한 검색어" }, "domain": { "type": "string", "description": "확인한 도메인" }, "found": { "type": "boolean", "description": "100위 안 노출 여부" }, "rank": { "type": "integer", "description": "가장 높은 순위. 없으면 null", "nullable": true }, "matches": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer", "description": "순위" }, "title": { "type": "string", "description": "검색 결과 제목" }, "link": { "type": "string", "description": "검색 결과 주소" } } }, "description": "노출된 결과 목록 (최대 10개)" }, "checked_results": { "type": "integer", "description": "확인한 검색 결과 수" }, "checked_pages": { "type": "integer", "description": "확인한 10위 구간 수 (최대 10)" }, "complete": { "type": "boolean", "description": "1~100위를 모두 확인했거나, 앞에서부터 끊김 없이 확인한 구간에서 찾았으면 true" }, "unchecked_ranks": { "type": "array", "items": {}, "description": "확인하지 못한 순위 구간 (예: \"41-50\"). complete 가 true 면 빈 배열" } }, "description": "조회 데이터. 실패하면 error 에 안내 문구가 담깁니다." }, "api": { "type": "object", "properties": { "success": { "type": "boolean", "description": "API 서버 정상 응답 여부" }, "cost": { "type": "integer", "description": "차감된 포인트. 실패한 응답은 0" }, "pl_id": { "type": "integer", "description": "API 결제 로그 ID" }, "ms": { "type": "integer", "description": "API 응답 시간(밀리초)" } }, "description": "API 호출 공통 데이터" } } } ``` ### 정적 응답 예시 ```json { "data": { "keyword": "주소 검색 API", "domain": "apick.app", "found": true, "rank": 3, "matches": [ { "rank": 3, "title": "주소 검색 - APICK", "link": "https://apick.app/dev_guide/search_juso" } ], "checked_results": 98, "checked_pages": 10, "complete": true, "unchecked_ranks": [] }, "api": { "success": true, "cost": 50, "pl_id": 1595635, "ms": 9850 } } ``` ### curl ```curl curl --fail-with-body --request POST 'https://apick.app/rest/google_rank_check' \ --header "Authorization: Bearer $APICK_API_KEY" \ --form-string 'keyword=주소 검색 API' \ --form-string 'domain=apick.app' ``` ### Node.js (서버 ESM) ```javascript const form = new FormData(); form.append("keyword", "주소 검색 API"); form.append("domain", "apick.app"); const response = await fetch("https://apick.app/rest/google_rank_check", { method: "POST", headers: { Authorization: "Bearer " + process.env.APICK_API_KEY }, body: form, signal: AbortSignal.timeout(120_000), }); if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`); const result = await response.json(); console.log(result); ``` ### python ```python import os import requests parts = [ ("keyword", (None, "주소 검색 API")), ("domain", (None, "apick.app")), ] response = requests.request("POST", "https://apick.app/rest/google_rank_check", headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]}, files=parts, timeout=(10, 120)) response.raise_for_status() result = response.json() print(result) ``` ### php ```php '주소 검색 API', 'domain' => 'apick.app', ]; $curl = curl_init('https://apick.app/rest/google_rank_check'); curl_setopt_array($curl, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => $headers, CURLOPT_POSTFIELDS => $form, CURLOPT_RETURNTRANSFER => true, CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120, ]); $body = curl_exec($curl); if ($body === false) { throw new RuntimeException(curl_error($curl)); } $status = curl_getinfo($curl, CURLINFO_HTTP_CODE); curl_close($curl); if ($status >= 400) { throw new RuntimeException($body); } $result = json_decode($body, true, 512, JSON_THROW_ON_ERROR); print_r($result); ``` ## 코드·오류 ## 상세 기능·요금 Method URL POST https://apick.app/rest/google_rank_check 구글 검색 결과 1~100위를 확인합니다. 100위 안에 없으면 found 가 false 인 정상 응답이며 과금됩니다. 일부 순위 구간을 확인하지 못하면 complete 가 false 이고 unchecked_ranks 에 그 구간이 담기며, 확인한 구간 비율만큼만 과금됩니다(10위 구간당 정가의 1/10). 확인한 구간이 50위 분량 미만이면 실패로 처리하고 과금하지 않습니다. 한국어·한국 지역 기준 검색 결과입니다. 실패한 호출(입력 오류, 시간 초과, 대상 없음)은 과금하지 않습니다. 같은 요청은 최대 10분 동안 같은 결과가 반환될 수 있습니다. API 호출 요청 요청하기 Key Value keyword domain 응답 ## 상세 요청 Header 이름 필수 설명 Authorization O Bearer 인증키 ## 상세 응답 Body 이름 타입 설명 data Object 조회 데이터. 실패하면 error 에 안내 문구가 담깁니다. keyword String 요청한 검색어 domain String 확인한 도메인 found Boolean 100위 안 노출 여부 rank Integer 가장 높은 순위. 없으면 null matches Array 노출된 결과 목록 (최대 10개) rank Integer 순위 title String 검색 결과 제목 link String 검색 결과 주소 checked_results Integer 확인한 검색 결과 수 checked_pages Integer 확인한 10위 구간 수 (최대 10) complete Boolean 1~100위를 모두 확인했거나, 앞에서부터 끊김 없이 확인한 구간에서 찾았으면 true unchecked_ranks Array 확인하지 못한 순위 구간 (예: "41-50"). complete 가 true 면 빈 배열 api Object API 호출 공통 데이터 success Boolean API 서버 정상 응답 여부 cost Integer 차감된 포인트. 실패한 응답은 0 ms Integer API 응답 시간(밀리초) pl_id Integer API 결제 로그 ID ## 상세 예제 요청 예시 form-data 전체 예제 보기 응답 예시 { "data": { "keyword": "주소 검색 API", "domain": "apick.app", "found": true, "rank": 3, "matches": [ { "rank": 3, "title": "주소 검색 - APICK", "link": "https://apick.app/dev_guide/search_juso" } ], "checked_results": 98, "checked_pages": 10, "complete": true, "unchecked_ranks": [] }, "api": { "success": true, "cost": 50, "pl_id": 1595635, "ms": 9850 } }