{"openapi":"3.0.3","info":{"title":"APICK 구글 검색 순위 확인","version":"1.0.0","description":"키워드로 구글을 검색했을 때 지정한 도메인이 1~100위 중 몇 위에 노출되는지 확인합니다."},"servers":[{"url":"https://apick.app"}],"paths":{"/rest/google_rank_check":{"post":{"summary":"구글 검색 순위 확인","description":"키워드로 구글을 검색했을 때 지정한 도메인이 1~100위 중 몇 위에 노출되는지 확인합니다.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"서비스별 성공·처리 상태 응답","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"keyword":{"type":"string","description":"검색에 쓴 검색어입니다."},"domain":{"type":"string","description":"실제로 비교한 도메인입니다(소문자, www. 제거)."},"found":{"type":"boolean","description":"1~100위 안에 노출되면 true입니다."},"rank":{"type":"integer","nullable":true,"description":"가장 높은 순위(1~100)입니다. 노출되지 않으면 null입니다."},"matches":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"rank":{"type":"integer"},"title":{"type":"string"},"link":{"type":"string"}}},{}],"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":"순위 확정에 필요한 구간을 모두 확인했는지 여부입니다. 성공 응답에서는 항상 true입니다."},"unchecked_ranks":{"type":"array","items":{},"description":"확인하지 못한 순위 구간입니다. 성공 응답에서는 항상 빈 배열입니다."},"success":{"type":"integer","description":"1이면 정상 처리되어 과금된 응답입니다."},"error":{"type":"string","description":"실패 사유입니다. 이 필드가 있으면 과금되지 않습니다."}}},"api":{"type":"object","properties":{"success":{"type":"boolean"},"cost":{"type":"integer","description":"차감된 포인트입니다. 실패하면 0입니다."},"ms":{"type":"integer"},"pl_id":{"type":"integer","description":"결제 기록 번호입니다."}}}}}}}},"default":{"description":"HTTP 상태 및 서비스 오류코드 확인","content":{"application/json":{"schema":{"type":"object"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"keyword":{"type":"string","description":"검색할 키워드입니다. 1~200자까지 보낼 수 있으며, 여러 단어는 공백으로 구분합니다. 특수문자는 검색 결과에 영향을 줄 수 있습니다. (string)","example":"주소 검색 API"},"domain":{"type":"string","description":"순위를 확인할 도메인 (예: apick.app). 하위 도메인도 함께 찾습니다 (string)","example":"apick.app"}},"required":["keyword","domain"]}}}}}}},"x-code-tables":[{"title":"오류 코드","columns":["data.error","HTTP","대처"],"rows":[["입력 항목이 잘못됐습니다. keyword(검색어, 1~200자)를 입력해 주세요.","400","keyword가 비었거나 200자를 넘었습니다."],["입력 항목이 잘못됐습니다. domain(예: apick.app)을 입력해 주세요.","400","domain이 비었거나 도메인 형식이 아닙니다. example.com 형식으로 보냅니다."],["처리 시간 초과로 실패했습니다. 잠시 후 다시 시도해 주세요.","408","순위를 확정하지 못했습니다. 잠시 뒤 같은 요청을 다시 보냅니다."],["외부 검색 처리에 실패했습니다. 잠시 후 다시 시도해 주세요.","424","순위를 확정하지 못했습니다. 잠시 뒤 다시 요청합니다."]]}],"x-service-errors":[],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}}}