# 구글 지도 장소 상세·리뷰 조회 구글 지도 장소의 평점·리뷰 수·별점 분포(1~5점)·대표 리뷰·영업시간·시간대별 혼잡도·비슷한 장소·사진을 조회합니다. 인증: Authorization: Bearer $APICK_API_KEY 본문 있는 REST 요청: multipart/form-data. GET 본문 및 MCP JSON-RPC 규격은 해당 명세를 따릅니다. 인증키는 서버에 보관하세요. 모든 예제는 정적 자료입니다. ## POST /rest/google_maps_place/jobs 응답 필드 - `data` (object): 아래 하위 항목을 확인하세요. - `data.job_id` (string): 아래 하위 항목을 확인하세요. - `data.product` (string): 아래 하위 항목을 확인하세요. - `data.status` (string): 아래 하위 항목을 확인하세요. - `data.max_results` (integer): 아래 하위 항목을 확인하세요. - `data.unit_point` (integer): 아래 하위 항목을 확인하세요. - `data.reserved_point` (integer): 아래 하위 항목을 확인하세요. - `data.charged_point` (integer): 아래 하위 항목을 확인하세요. - `data.result_count` (integer): 아래 하위 항목을 확인하세요. - `data.created_at` (string): 아래 하위 항목을 확인하세요. - `data.completed_at` (string): 아래 하위 항목을 확인하세요. null 허용. - `data.result_expires_at` (string): 아래 하위 항목을 확인하세요. - `data.items` (array): 아래 하위 항목을 확인하세요. - `data.items[].name` (string): 아래 하위 항목을 확인하세요. - `data.items[].category` (string): 아래 하위 항목을 확인하세요. - `data.items[].categories` (array): 아래 하위 항목을 확인하세요. - `data.items[].address` (string): 아래 하위 항목을 확인하세요. - `data.items[].country_code` (string): 아래 하위 항목을 확인하세요. - `data.items[].phone` (string): 아래 하위 항목을 확인하세요. - `data.items[].website` (string): 아래 하위 항목을 확인하세요. - `data.items[].description` (string): 아래 하위 항목을 확인하세요. - `data.items[].rating` (number): 아래 하위 항목을 확인하세요. - `data.items[].reviews_count` (integer): 아래 하위 항목을 확인하세요. - `data.items[].rating_distribution` (object): 아래 하위 항목을 확인하세요. - `data.items[].rating_distribution.1` (integer): 아래 하위 항목을 확인하세요. - `data.items[].rating_distribution.2` (integer): 아래 하위 항목을 확인하세요. - `data.items[].rating_distribution.3` (integer): 아래 하위 항목을 확인하세요. - `data.items[].rating_distribution.4` (integer): 아래 하위 항목을 확인하세요. - `data.items[].rating_distribution.5` (integer): 아래 하위 항목을 확인하세요. - `data.items[].top_reviews` (array): 아래 하위 항목을 확인하세요. - `data.items[].top_reviews[].reviewer_name` (string): 아래 하위 항목을 확인하세요. - `data.items[].top_reviews[].rating` (integer): 아래 하위 항목을 확인하세요. - `data.items[].top_reviews[].posted_at` (string): 아래 하위 항목을 확인하세요. - `data.items[].top_reviews[].text` (string): 아래 하위 항목을 확인하세요. - `data.items[].open_hours` (object): 아래 하위 항목을 확인하세요. - `data.items[].open_hours.Monday` (string): 아래 하위 항목을 확인하세요. - `data.items[].open_hours.Sunday` (string): 아래 하위 항목을 확인하세요. - `data.items[].popular_times` (array): 아래 하위 항목을 확인하세요. - `data.items[].popular_times[].day` (integer): 아래 하위 항목을 확인하세요. - `data.items[].popular_times[].hours` (array): 아래 하위 항목을 확인하세요. - `data.items[].popular_times[].hours[].hour` (string): 아래 하위 항목을 확인하세요. - `data.items[].popular_times[].hours[].busy_percent` (integer): 아래 하위 항목을 확인하세요. - `data.items[].similar_places` (array): 아래 하위 항목을 확인하세요. - `data.items[].similar_places[].name` (string): 아래 하위 항목을 확인하세요. - `data.items[].similar_places[].category` (string): 아래 하위 항목을 확인하세요. - `data.items[].similar_places[].rating` (number): 아래 하위 항목을 확인하세요. - `data.items[].similar_places[].reviews_count` (integer): 아래 하위 항목을 확인하세요. - `data.items[].photo_urls` (array): 아래 하위 항목을 확인하세요. - `data.items[].main_image_url` (string): 아래 하위 항목을 확인하세요. - `data.items[].is_claimed` (boolean): 아래 하위 항목을 확인하세요. - `data.items[].permanently_closed` (boolean): 아래 하위 항목을 확인하세요. - `data.items[].temporarily_closed` (boolean): 아래 하위 항목을 확인하세요. - `data.items[].latitude` (number): 아래 하위 항목을 확인하세요. - `data.items[].longitude` (number): 아래 하위 항목을 확인하세요. - `data.items[].place_id` (string): 아래 하위 항목을 확인하세요. - `data.items[].map_url` (string): 아래 하위 항목을 확인하세요. - `data.result_expired` (boolean): 아래 하위 항목을 확인하세요. - `api` (object): 아래 하위 항목을 확인하세요. - `api.success` (boolean): 아래 하위 항목을 확인하세요. - `api.cost` (integer): 아래 하위 항목을 확인하세요. ## 작업 접수: POST /rest/google_maps_place/jobs ### 입력 - `place_id` (string, 선택): 구글 장소 ID (google_maps_search 결과의 place_id, ChIJ 로 시작. place_id 또는 url 중 하나 필수) - `url` (string, 선택): 구글 지도 장소 주소 (google_maps_search 결과의 map_link, 또는 cid= 가 들어 있는 지도 주소) - `idempotency_key` (string, 선택): 응답을 못 받아 다시 보낼 때 같은 접수로 처리할 키(8~128자, 영문·숫자·_.:-) ### 응답 명세 ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "job_id": { "type": "string" }, "product": { "type": "string" }, "status": { "type": "string" }, "max_results": { "type": "integer" }, "unit_point": { "type": "integer" }, "reserved_point": { "type": "integer" }, "charged_point": { "type": "integer" }, "result_count": { "type": "integer" }, "created_at": { "type": "string" }, "completed_at": { "type": "string", "nullable": true }, "result_expires_at": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "category": { "type": "string" }, "categories": { "type": "array", "items": { "type": "string" } }, "address": { "type": "string" }, "country_code": { "type": "string" }, "phone": { "type": "string" }, "website": { "type": "string" }, "description": { "type": "string" }, "rating": { "type": "number" }, "reviews_count": { "type": "integer" }, "rating_distribution": { "type": "object", "properties": { "1": { "type": "integer" }, "2": { "type": "integer" }, "3": { "type": "integer" }, "4": { "type": "integer" }, "5": { "type": "integer" } } }, "top_reviews": { "type": "array", "items": { "type": "object", "properties": { "reviewer_name": { "type": "string" }, "rating": { "type": "integer" }, "posted_at": { "type": "string" }, "text": { "type": "string" } } } }, "open_hours": { "type": "object", "properties": { "Monday": { "type": "string" }, "Sunday": { "type": "string" } } }, "popular_times": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "integer" }, "hours": { "type": "array", "items": { "type": "object", "properties": { "hour": { "type": "string" }, "busy_percent": { "type": "integer" } } } } } } }, "similar_places": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "category": { "type": "string" }, "rating": { "type": "number" }, "reviews_count": { "type": "integer" } } } }, "photo_urls": { "type": "array", "items": { "type": "string" } }, "main_image_url": { "type": "string" }, "is_claimed": { "type": "boolean" }, "permanently_closed": { "type": "boolean" }, "temporarily_closed": { "type": "boolean" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "place_id": { "type": "string" }, "map_url": { "type": "string" } } } }, "result_expired": { "type": "boolean" } } }, "api": { "type": "object", "properties": { "success": { "type": "boolean" }, "cost": { "type": "integer" } } } } } ``` ### 정적 응답 예시 ```json { "data": { "job_id": "5f0c2a9e7b1d4c3a8e6f90a1b2c3d4e5", "product": "google_maps_place", "status": "processing", "max_results": 1, "unit_point": 20, "reserved_point": 20, "charged_point": 0, "result_count": 0, "created_at": "2026-10-06T10:00:00.000Z", "completed_at": null }, "api": { "success": true, "cost": 20 } } ``` ### 정적 응답 예시 ```json { "data": { "job_id": "5f0c2a9e7b1d4c3a8e6f90a1b2c3d4e5", "product": "google_maps_place", "status": "completed", "max_results": 1, "unit_point": 20, "reserved_point": 0, "charged_point": 20, "result_count": 1, "created_at": "2026-10-06T10:00:00.000Z", "completed_at": "2026-10-06T10:01:12.000Z", "result_expires_at": "2026-10-09T10:01:12.000Z", "items": [ { "name": "Starbucks Reserve Gangnam", "category": "Coffee shop", "categories": [ "Coffee shop", "Cafe" ], "address": "390 Gangnam-daero, Gangnam District, Seoul, South Korea", "country_code": "KR", "phone": "+82 1522-3232", "website": "http://www.starbucks.co.kr/", "description": "Welcoming coffeehouse with handcrafted coffee, espresso & tea, plus breakfast, lunch & pastries.", "rating": 4.3, "reviews_count": 1687, "rating_distribution": { "1": 35, "2": 34, "3": 212, "4": 554, "5": 852 }, "top_reviews": [ { "reviewer_name": "Example Reviewer", "rating": 5, "posted_at": "2024-10-10T10:29:41.348Z", "text": "Starbucks located in front of Exit 1 of Gangnam Station. It is always crowded ..." } ], "open_hours": { "Monday": "7 AM–10 PM", "Sunday": "8 AM–10 PM" }, "popular_times": [ { "day": 1, "hours": [ { "hour": "8 AM", "busy_percent": 17 }, { "hour": "9 AM", "busy_percent": 28 } ] } ], "similar_places": [ { "name": "Starbucks Gangnam-daero", "category": "Coffee shop", "rating": 4.1, "reviews_count": 1075 } ], "photo_urls": [ "https://lh3.googleusercontent.com/..." ], "main_image_url": "https://lh3.googleusercontent.com/...", "is_claimed": true, "permanently_closed": false, "temporarily_closed": false, "latitude": 37.497853, "longitude": 127.028587, "place_id": "ChIJobb671mhfDURrcE4SebLfyw", "map_url": "https://www.google.com/maps/place/Starbucks+Reserve+Gangnam/..." } ], "result_expired": false }, "api": { "success": true, "cost": 0 } } ``` ### curl ```curl curl --fail-with-body --request POST 'https://apick.app/rest/google_maps_place/jobs' \ --header "Authorization: Bearer $APICK_API_KEY" \ --form-string 'place_id=ChIJobb671mhfDURrcE4SebLfyw' ``` ### Node.js (서버 ESM) ```javascript const form = new FormData(); form.append("place_id", "ChIJobb671mhfDURrcE4SebLfyw"); const response = await fetch("https://apick.app/rest/google_maps_place/jobs", { 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 = [ ("place_id", (None, "ChIJobb671mhfDURrcE4SebLfyw")), ] response = requests.request("POST", "https://apick.app/rest/google_maps_place/jobs", headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]}, files=parts, timeout=(10, 120)) response.raise_for_status() result = response.json() print(result) ``` ### php ```php 'ChIJobb671mhfDURrcE4SebLfyw', ]; $curl = curl_init('https://apick.app/rest/google_maps_place/jobs'); 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); ``` ## GET /rest/scrape_jobs/5f0c2a9e7b1d4c3a8e6f90a1b2c3d4e5 응답 필드 - `data` (object): 아래 하위 항목을 확인하세요. - `data.job_id` (string): 아래 하위 항목을 확인하세요. - `data.product` (string): 아래 하위 항목을 확인하세요. - `data.status` (string): 아래 하위 항목을 확인하세요. - `data.max_results` (integer): 아래 하위 항목을 확인하세요. - `data.unit_point` (integer): 아래 하위 항목을 확인하세요. - `data.reserved_point` (integer): 아래 하위 항목을 확인하세요. - `data.charged_point` (integer): 아래 하위 항목을 확인하세요. - `data.result_count` (integer): 아래 하위 항목을 확인하세요. - `data.created_at` (string): 아래 하위 항목을 확인하세요. - `data.completed_at` (string): 아래 하위 항목을 확인하세요. null 허용. - `data.result_expires_at` (string): 아래 하위 항목을 확인하세요. - `data.items` (array): 아래 하위 항목을 확인하세요. - `data.items[].name` (string): 아래 하위 항목을 확인하세요. - `data.items[].category` (string): 아래 하위 항목을 확인하세요. - `data.items[].categories` (array): 아래 하위 항목을 확인하세요. - `data.items[].address` (string): 아래 하위 항목을 확인하세요. - `data.items[].country_code` (string): 아래 하위 항목을 확인하세요. - `data.items[].phone` (string): 아래 하위 항목을 확인하세요. - `data.items[].website` (string): 아래 하위 항목을 확인하세요. - `data.items[].description` (string): 아래 하위 항목을 확인하세요. - `data.items[].rating` (number): 아래 하위 항목을 확인하세요. - `data.items[].reviews_count` (integer): 아래 하위 항목을 확인하세요. - `data.items[].rating_distribution` (object): 아래 하위 항목을 확인하세요. - `data.items[].rating_distribution.1` (integer): 아래 하위 항목을 확인하세요. - `data.items[].rating_distribution.2` (integer): 아래 하위 항목을 확인하세요. - `data.items[].rating_distribution.3` (integer): 아래 하위 항목을 확인하세요. - `data.items[].rating_distribution.4` (integer): 아래 하위 항목을 확인하세요. - `data.items[].rating_distribution.5` (integer): 아래 하위 항목을 확인하세요. - `data.items[].top_reviews` (array): 아래 하위 항목을 확인하세요. - `data.items[].top_reviews[].reviewer_name` (string): 아래 하위 항목을 확인하세요. - `data.items[].top_reviews[].rating` (integer): 아래 하위 항목을 확인하세요. - `data.items[].top_reviews[].posted_at` (string): 아래 하위 항목을 확인하세요. - `data.items[].top_reviews[].text` (string): 아래 하위 항목을 확인하세요. - `data.items[].open_hours` (object): 아래 하위 항목을 확인하세요. - `data.items[].open_hours.Monday` (string): 아래 하위 항목을 확인하세요. - `data.items[].open_hours.Sunday` (string): 아래 하위 항목을 확인하세요. - `data.items[].popular_times` (array): 아래 하위 항목을 확인하세요. - `data.items[].popular_times[].day` (integer): 아래 하위 항목을 확인하세요. - `data.items[].popular_times[].hours` (array): 아래 하위 항목을 확인하세요. - `data.items[].popular_times[].hours[].hour` (string): 아래 하위 항목을 확인하세요. - `data.items[].popular_times[].hours[].busy_percent` (integer): 아래 하위 항목을 확인하세요. - `data.items[].similar_places` (array): 아래 하위 항목을 확인하세요. - `data.items[].similar_places[].name` (string): 아래 하위 항목을 확인하세요. - `data.items[].similar_places[].category` (string): 아래 하위 항목을 확인하세요. - `data.items[].similar_places[].rating` (number): 아래 하위 항목을 확인하세요. - `data.items[].similar_places[].reviews_count` (integer): 아래 하위 항목을 확인하세요. - `data.items[].photo_urls` (array): 아래 하위 항목을 확인하세요. - `data.items[].main_image_url` (string): 아래 하위 항목을 확인하세요. - `data.items[].is_claimed` (boolean): 아래 하위 항목을 확인하세요. - `data.items[].permanently_closed` (boolean): 아래 하위 항목을 확인하세요. - `data.items[].temporarily_closed` (boolean): 아래 하위 항목을 확인하세요. - `data.items[].latitude` (number): 아래 하위 항목을 확인하세요. - `data.items[].longitude` (number): 아래 하위 항목을 확인하세요. - `data.items[].place_id` (string): 아래 하위 항목을 확인하세요. - `data.items[].map_url` (string): 아래 하위 항목을 확인하세요. - `data.result_expired` (boolean): 아래 하위 항목을 확인하세요. - `api` (object): 아래 하위 항목을 확인하세요. - `api.success` (boolean): 아래 하위 항목을 확인하세요. - `api.cost` (integer): 아래 하위 항목을 확인하세요. ## 상태·목록 조회: GET /rest/scrape_jobs/5f0c2a9e7b1d4c3a8e6f90a1b2c3d4e5 ### 입력 ### 응답 명세 ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "job_id": { "type": "string" }, "product": { "type": "string" }, "status": { "type": "string" }, "max_results": { "type": "integer" }, "unit_point": { "type": "integer" }, "reserved_point": { "type": "integer" }, "charged_point": { "type": "integer" }, "result_count": { "type": "integer" }, "created_at": { "type": "string" }, "completed_at": { "type": "string", "nullable": true }, "result_expires_at": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "category": { "type": "string" }, "categories": { "type": "array", "items": { "type": "string" } }, "address": { "type": "string" }, "country_code": { "type": "string" }, "phone": { "type": "string" }, "website": { "type": "string" }, "description": { "type": "string" }, "rating": { "type": "number" }, "reviews_count": { "type": "integer" }, "rating_distribution": { "type": "object", "properties": { "1": { "type": "integer" }, "2": { "type": "integer" }, "3": { "type": "integer" }, "4": { "type": "integer" }, "5": { "type": "integer" } } }, "top_reviews": { "type": "array", "items": { "type": "object", "properties": { "reviewer_name": { "type": "string" }, "rating": { "type": "integer" }, "posted_at": { "type": "string" }, "text": { "type": "string" } } } }, "open_hours": { "type": "object", "properties": { "Monday": { "type": "string" }, "Sunday": { "type": "string" } } }, "popular_times": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "integer" }, "hours": { "type": "array", "items": { "type": "object", "properties": { "hour": { "type": "string" }, "busy_percent": { "type": "integer" } } } } } } }, "similar_places": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "category": { "type": "string" }, "rating": { "type": "number" }, "reviews_count": { "type": "integer" } } } }, "photo_urls": { "type": "array", "items": { "type": "string" } }, "main_image_url": { "type": "string" }, "is_claimed": { "type": "boolean" }, "permanently_closed": { "type": "boolean" }, "temporarily_closed": { "type": "boolean" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "place_id": { "type": "string" }, "map_url": { "type": "string" } } } }, "result_expired": { "type": "boolean" } } }, "api": { "type": "object", "properties": { "success": { "type": "boolean" }, "cost": { "type": "integer" } } } } } ``` ### 정적 응답 예시 ```json { "data": { "job_id": "5f0c2a9e7b1d4c3a8e6f90a1b2c3d4e5", "product": "google_maps_place", "status": "processing", "max_results": 1, "unit_point": 20, "reserved_point": 20, "charged_point": 0, "result_count": 0, "created_at": "2026-10-06T10:00:00.000Z", "completed_at": null }, "api": { "success": true, "cost": 20 } } ``` ### 정적 응답 예시 ```json { "data": { "job_id": "5f0c2a9e7b1d4c3a8e6f90a1b2c3d4e5", "product": "google_maps_place", "status": "completed", "max_results": 1, "unit_point": 20, "reserved_point": 0, "charged_point": 20, "result_count": 1, "created_at": "2026-10-06T10:00:00.000Z", "completed_at": "2026-10-06T10:01:12.000Z", "result_expires_at": "2026-10-09T10:01:12.000Z", "items": [ { "name": "Starbucks Reserve Gangnam", "category": "Coffee shop", "categories": [ "Coffee shop", "Cafe" ], "address": "390 Gangnam-daero, Gangnam District, Seoul, South Korea", "country_code": "KR", "phone": "+82 1522-3232", "website": "http://www.starbucks.co.kr/", "description": "Welcoming coffeehouse with handcrafted coffee, espresso & tea, plus breakfast, lunch & pastries.", "rating": 4.3, "reviews_count": 1687, "rating_distribution": { "1": 35, "2": 34, "3": 212, "4": 554, "5": 852 }, "top_reviews": [ { "reviewer_name": "Example Reviewer", "rating": 5, "posted_at": "2024-10-10T10:29:41.348Z", "text": "Starbucks located in front of Exit 1 of Gangnam Station. It is always crowded ..." } ], "open_hours": { "Monday": "7 AM–10 PM", "Sunday": "8 AM–10 PM" }, "popular_times": [ { "day": 1, "hours": [ { "hour": "8 AM", "busy_percent": 17 }, { "hour": "9 AM", "busy_percent": 28 } ] } ], "similar_places": [ { "name": "Starbucks Gangnam-daero", "category": "Coffee shop", "rating": 4.1, "reviews_count": 1075 } ], "photo_urls": [ "https://lh3.googleusercontent.com/..." ], "main_image_url": "https://lh3.googleusercontent.com/...", "is_claimed": true, "permanently_closed": false, "temporarily_closed": false, "latitude": 37.497853, "longitude": 127.028587, "place_id": "ChIJobb671mhfDURrcE4SebLfyw", "map_url": "https://www.google.com/maps/place/Starbucks+Reserve+Gangnam/..." } ], "result_expired": false }, "api": { "success": true, "cost": 0 } } ``` ### curl ```curl curl --fail-with-body --request GET 'https://apick.app/rest/scrape_jobs/5f0c2a9e7b1d4c3a8e6f90a1b2c3d4e5' \ --header "Authorization: Bearer $APICK_API_KEY" ``` ### Node.js (서버 ESM) ```javascript const response = await fetch("https://apick.app/rest/scrape_jobs/5f0c2a9e7b1d4c3a8e6f90a1b2c3d4e5", { method: "GET", headers: { Authorization: "Bearer " + process.env.APICK_API_KEY }, 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 response = requests.request("GET", "https://apick.app/rest/scrape_jobs/5f0c2a9e7b1d4c3a8e6f90a1b2c3d4e5", headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]}, timeout=(10, 120)) response.raise_for_status() result = response.json() print(result) ``` ### php ```php 'GET', CURLOPT_HTTPHEADER => $headers, 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); ``` ## GET /rest/scrape_jobs/:job_id 응답 필드 - `data` (object): 아래 하위 항목을 확인하세요. - `data.job_id` (string): 아래 하위 항목을 확인하세요. - `data.product` (string): 아래 하위 항목을 확인하세요. - `data.status` (string): 아래 하위 항목을 확인하세요. - `data.max_results` (integer): 아래 하위 항목을 확인하세요. - `data.unit_point` (integer): 아래 하위 항목을 확인하세요. - `data.reserved_point` (integer): 아래 하위 항목을 확인하세요. - `data.charged_point` (integer): 아래 하위 항목을 확인하세요. - `data.result_count` (integer): 아래 하위 항목을 확인하세요. - `data.created_at` (string): 아래 하위 항목을 확인하세요. - `data.completed_at` (string): 아래 하위 항목을 확인하세요. null 허용. - `data.result_expires_at` (string): 아래 하위 항목을 확인하세요. - `data.items` (array): 아래 하위 항목을 확인하세요. - `data.items[].name` (string): 아래 하위 항목을 확인하세요. - `data.items[].category` (string): 아래 하위 항목을 확인하세요. - `data.items[].categories` (array): 아래 하위 항목을 확인하세요. - `data.items[].address` (string): 아래 하위 항목을 확인하세요. - `data.items[].country_code` (string): 아래 하위 항목을 확인하세요. - `data.items[].phone` (string): 아래 하위 항목을 확인하세요. - `data.items[].website` (string): 아래 하위 항목을 확인하세요. - `data.items[].description` (string): 아래 하위 항목을 확인하세요. - `data.items[].rating` (number): 아래 하위 항목을 확인하세요. - `data.items[].reviews_count` (integer): 아래 하위 항목을 확인하세요. - `data.items[].rating_distribution` (object): 아래 하위 항목을 확인하세요. - `data.items[].rating_distribution.1` (integer): 아래 하위 항목을 확인하세요. - `data.items[].rating_distribution.2` (integer): 아래 하위 항목을 확인하세요. - `data.items[].rating_distribution.3` (integer): 아래 하위 항목을 확인하세요. - `data.items[].rating_distribution.4` (integer): 아래 하위 항목을 확인하세요. - `data.items[].rating_distribution.5` (integer): 아래 하위 항목을 확인하세요. - `data.items[].top_reviews` (array): 아래 하위 항목을 확인하세요. - `data.items[].top_reviews[].reviewer_name` (string): 아래 하위 항목을 확인하세요. - `data.items[].top_reviews[].rating` (integer): 아래 하위 항목을 확인하세요. - `data.items[].top_reviews[].posted_at` (string): 아래 하위 항목을 확인하세요. - `data.items[].top_reviews[].text` (string): 아래 하위 항목을 확인하세요. - `data.items[].open_hours` (object): 아래 하위 항목을 확인하세요. - `data.items[].open_hours.Monday` (string): 아래 하위 항목을 확인하세요. - `data.items[].open_hours.Sunday` (string): 아래 하위 항목을 확인하세요. - `data.items[].popular_times` (array): 아래 하위 항목을 확인하세요. - `data.items[].popular_times[].day` (integer): 아래 하위 항목을 확인하세요. - `data.items[].popular_times[].hours` (array): 아래 하위 항목을 확인하세요. - `data.items[].popular_times[].hours[].hour` (string): 아래 하위 항목을 확인하세요. - `data.items[].popular_times[].hours[].busy_percent` (integer): 아래 하위 항목을 확인하세요. - `data.items[].similar_places` (array): 아래 하위 항목을 확인하세요. - `data.items[].similar_places[].name` (string): 아래 하위 항목을 확인하세요. - `data.items[].similar_places[].category` (string): 아래 하위 항목을 확인하세요. - `data.items[].similar_places[].rating` (number): 아래 하위 항목을 확인하세요. - `data.items[].similar_places[].reviews_count` (integer): 아래 하위 항목을 확인하세요. - `data.items[].photo_urls` (array): 아래 하위 항목을 확인하세요. - `data.items[].main_image_url` (string): 아래 하위 항목을 확인하세요. - `data.items[].is_claimed` (boolean): 아래 하위 항목을 확인하세요. - `data.items[].permanently_closed` (boolean): 아래 하위 항목을 확인하세요. - `data.items[].temporarily_closed` (boolean): 아래 하위 항목을 확인하세요. - `data.items[].latitude` (number): 아래 하위 항목을 확인하세요. - `data.items[].longitude` (number): 아래 하위 항목을 확인하세요. - `data.items[].place_id` (string): 아래 하위 항목을 확인하세요. - `data.items[].map_url` (string): 아래 하위 항목을 확인하세요. - `data.result_expired` (boolean): 아래 하위 항목을 확인하세요. - `api` (object): 아래 하위 항목을 확인하세요. - `api.success` (boolean): 아래 하위 항목을 확인하세요. - `api.cost` (integer): 아래 하위 항목을 확인하세요. ## 상태·목록 조회: GET /rest/scrape_jobs/:job_id ### 입력 ### 응답 명세 ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "job_id": { "type": "string" }, "product": { "type": "string" }, "status": { "type": "string" }, "max_results": { "type": "integer" }, "unit_point": { "type": "integer" }, "reserved_point": { "type": "integer" }, "charged_point": { "type": "integer" }, "result_count": { "type": "integer" }, "created_at": { "type": "string" }, "completed_at": { "type": "string", "nullable": true }, "result_expires_at": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "category": { "type": "string" }, "categories": { "type": "array", "items": { "type": "string" } }, "address": { "type": "string" }, "country_code": { "type": "string" }, "phone": { "type": "string" }, "website": { "type": "string" }, "description": { "type": "string" }, "rating": { "type": "number" }, "reviews_count": { "type": "integer" }, "rating_distribution": { "type": "object", "properties": { "1": { "type": "integer" }, "2": { "type": "integer" }, "3": { "type": "integer" }, "4": { "type": "integer" }, "5": { "type": "integer" } } }, "top_reviews": { "type": "array", "items": { "type": "object", "properties": { "reviewer_name": { "type": "string" }, "rating": { "type": "integer" }, "posted_at": { "type": "string" }, "text": { "type": "string" } } } }, "open_hours": { "type": "object", "properties": { "Monday": { "type": "string" }, "Sunday": { "type": "string" } } }, "popular_times": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "integer" }, "hours": { "type": "array", "items": { "type": "object", "properties": { "hour": { "type": "string" }, "busy_percent": { "type": "integer" } } } } } } }, "similar_places": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "category": { "type": "string" }, "rating": { "type": "number" }, "reviews_count": { "type": "integer" } } } }, "photo_urls": { "type": "array", "items": { "type": "string" } }, "main_image_url": { "type": "string" }, "is_claimed": { "type": "boolean" }, "permanently_closed": { "type": "boolean" }, "temporarily_closed": { "type": "boolean" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "place_id": { "type": "string" }, "map_url": { "type": "string" } } } }, "result_expired": { "type": "boolean" } } }, "api": { "type": "object", "properties": { "success": { "type": "boolean" }, "cost": { "type": "integer" } } } } } ``` ### 정적 응답 예시 ```json { "data": { "job_id": "5f0c2a9e7b1d4c3a8e6f90a1b2c3d4e5", "product": "google_maps_place", "status": "processing", "max_results": 1, "unit_point": 20, "reserved_point": 20, "charged_point": 0, "result_count": 0, "created_at": "2026-10-06T10:00:00.000Z", "completed_at": null }, "api": { "success": true, "cost": 20 } } ``` ### 정적 응답 예시 ```json { "data": { "job_id": "5f0c2a9e7b1d4c3a8e6f90a1b2c3d4e5", "product": "google_maps_place", "status": "completed", "max_results": 1, "unit_point": 20, "reserved_point": 0, "charged_point": 20, "result_count": 1, "created_at": "2026-10-06T10:00:00.000Z", "completed_at": "2026-10-06T10:01:12.000Z", "result_expires_at": "2026-10-09T10:01:12.000Z", "items": [ { "name": "Starbucks Reserve Gangnam", "category": "Coffee shop", "categories": [ "Coffee shop", "Cafe" ], "address": "390 Gangnam-daero, Gangnam District, Seoul, South Korea", "country_code": "KR", "phone": "+82 1522-3232", "website": "http://www.starbucks.co.kr/", "description": "Welcoming coffeehouse with handcrafted coffee, espresso & tea, plus breakfast, lunch & pastries.", "rating": 4.3, "reviews_count": 1687, "rating_distribution": { "1": 35, "2": 34, "3": 212, "4": 554, "5": 852 }, "top_reviews": [ { "reviewer_name": "Example Reviewer", "rating": 5, "posted_at": "2024-10-10T10:29:41.348Z", "text": "Starbucks located in front of Exit 1 of Gangnam Station. It is always crowded ..." } ], "open_hours": { "Monday": "7 AM–10 PM", "Sunday": "8 AM–10 PM" }, "popular_times": [ { "day": 1, "hours": [ { "hour": "8 AM", "busy_percent": 17 }, { "hour": "9 AM", "busy_percent": 28 } ] } ], "similar_places": [ { "name": "Starbucks Gangnam-daero", "category": "Coffee shop", "rating": 4.1, "reviews_count": 1075 } ], "photo_urls": [ "https://lh3.googleusercontent.com/..." ], "main_image_url": "https://lh3.googleusercontent.com/...", "is_claimed": true, "permanently_closed": false, "temporarily_closed": false, "latitude": 37.497853, "longitude": 127.028587, "place_id": "ChIJobb671mhfDURrcE4SebLfyw", "map_url": "https://www.google.com/maps/place/Starbucks+Reserve+Gangnam/..." } ], "result_expired": false }, "api": { "success": true, "cost": 0 } } ``` ### curl ```curl curl --fail-with-body --request GET "https://apick.app/rest/scrape_jobs/${APICK_JOB_ID}" \ --header "Authorization: Bearer $APICK_API_KEY" ``` ### Node.js (서버 ESM) ```javascript const response = await fetch(`https://apick.app/rest/scrape_jobs/${encodeURIComponent(process.env.APICK_JOB_ID)}`, { method: "GET", headers: { Authorization: "Bearer " + process.env.APICK_API_KEY }, 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 from urllib.parse import quote response = requests.request("GET", "https://apick.app" + "/rest/scrape_jobs/{job_id}".format(job_id=quote(os.environ["APICK_JOB_ID"], safe="")), headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]}, timeout=(10, 120)) response.raise_for_status() result = response.json() print(result) ``` ### php ```php 'GET', CURLOPT_HTTPHEADER => $headers, 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); ``` ## 코드·오류 ## 상세 기능·요금 지원 API 요약 수집 작업은 접수한 뒤 상태를 조회해 결과를 받는 흐름입니다. 접수할 때 max_results 만큼 포인트를 예약하고, 완료되면 실제로 받은 결과 건수만큼만 차감한 뒤 나머지를 바로 돌려드립니다. 대상을 찾지 못하거나 실패하면 예약한 포인트를 모두 돌려드립니다. Method API entry point 기능 성공 결과 POST /rest/google_maps_place/jobs 수집 작업 접수 HTTP 202와 job_id GET /rest/scrape_jobs/{job_id} 작업 상태·결과 조회(무료) HTTP 200과 현재 상태·결과 1. 작업 접수 Header 이름 필수 설명 Authorization O Bearer 인증키 요청 항목 · multipart/form-data 이름 타입 필수 설명 place_id String △ 구글 장소 ID. 구글 지도 장소 검색 결과의 place_id (ChIJ 로 시작, place_id 또는 url 중 하나 필수) url String △ 구글 지도 장소 주소. 구글 지도 장소 검색 결과의 map_link, 또는 cid= 가 들어 있는 지도 주소 idempotency_key String X 응답을 못 받아 다시 보낼 때 같은 접수로 처리할 키. 영문·숫자·_.:-, 8~128자 진행 중인 작업은 계정당 최대 5개입니다. 장소 이름·주소·리뷰 같은 텍스트는 영어로 제공합니다. 리뷰 본문은 대표 리뷰 최대 10건이며, 작성자는 공개 표시 이름만 제공합니다. 구글 지도 장소 검색으로 장소를 찾은 뒤 결과의 place_id 를 그대로 넣으면 됩니다. 결과 items 에 장소 1건이 담깁니다. ## 상세 코드·정책 2. 상태·결과 조회 GET /rest/scrape_jobs/{job_id} 를 5~10초 간격으로 호출해 status 가 completed 또는 failed 가 될 때까지 확인합니다. 보통 1~3분 안에 끝납니다. 조회는 무료이며, 완료되면 이 조회에서 정산이 끝납니다. Body (data) 이름 타입 설명 job_id String 작업 ID (32자리). 상태·결과 조회에 씁니다 product String 수집 상품 이름 status String waiting · processing · completed · failed max_results Integer 요청한 최대 결과 수 unit_point Integer 결과 1건당 포인트(이 작업에 적용된 단가) reserved_point Integer 현재 예약 중인 포인트. 완료·실패하면 0 charged_point Integer 최종 차감 포인트(완료 시 결과 건수 × 단가) result_count Integer 받은 결과 수 created_at String 접수 시각 (ISO 8601) completed_at String 완료 시각. 진행 중이면 null items Array 수집 결과(완료 시). 각 항목의 필드는 아래 표 name String 장소 이름 category String 대표 업종 categories Array 업종 목록 address String 주소 country_code String 국가 코드 phone String 전화번호 website String 웹사이트 description String 장소 소개 rating Number 평균 별점 reviews_count Integer 리뷰 수 rating_distribution Object 별점별 리뷰 수 { "1"~"5" } top_reviews Array 대표 리뷰 [{ reviewer_name, rating, posted_at, text }] open_hours Object 요일별 영업시간 popular_times Array 요일별 시간대 혼잡도 [{ day(1=월~7=일), hours: [{ hour, busy_percent }] }] similar_places Array 비슷한 장소 [{ name, category, rating, reviews_count }] photo_urls Array 사진 주소(최대 10개) main_image_url String 대표 이미지 is_claimed Boolean 업주 인증 여부 permanently_closed Boolean 폐업 여부 temporarily_closed Boolean 임시 휴업 여부 latitude Number 위도 longitude Number 경도 place_id String 구글 장소 ID map_url String 구글 지도 주소 result_expires_at String 결과 보관 기한(완료 후 72시간) result_expired Boolean 보관 기한이 지나 결과를 지웠으면 true error Object 실패 시 { code, message } 오류 코드 HTTP error_code 설명 400 SCRAPE_INPUT_INVALID 입력 형식 또는 max_results 범위 오류. 상류를 호출하지 않으며 포인트는 차감되지 않습니다 402 SCRAPE_POINTS_INSUFFICIENT max_results 만큼의 포인트가 부족합니다 403 SCRAPE_PAYMENT_REQUIRED 충전 이력이 있는 계정만 이용할 수 있습니다 404 SCRAPE_JOB_NOT_FOUND 작업이 없거나 다른 계정의 작업입니다 409 SCRAPE_IDEMPOTENCY_CONFLICT 같은 idempotency_key 로 다른 내용을 접수했습니다 429 SCRAPE_TOO_MANY_JOBS 진행 중인 작업이 5개입니다. 끝난 뒤 다시 접수해 주세요 503 SCRAPE_TEMPORARILY_UNAVAILABLE 일시적으로 접수하지 못했습니다. 포인트는 차감되지 않습니다 작업 실패 TARGET_NOT_FOUND · TARGET_PRIVATE · SCRAPE_TIMEOUT · SCRAPE_FAILED 상태 조회의 error.code. 예약한 포인트는 모두 돌려드립니다 ## 상세 예제 접수 요청 form-data 전체 예제 보기 접수 응답 (HTTP 202) { "data": { "job_id": "5f0c2a9e7b1d4c3a8e6f90a1b2c3d4e5", "product": "google_maps_place", "status": "processing", "max_results": 1, "unit_point": 20, "reserved_point": 20, "charged_point": 0, "result_count": 0, "created_at": "2026-10-06T10:00:00.000Z", "completed_at": null }, "api": { "success": true, "cost": 20 } } 상태 조회 form-data 전체 예제 보기 완료 응답 (HTTP 200) { "data": { "job_id": "5f0c2a9e7b1d4c3a8e6f90a1b2c3d4e5", "product": "google_maps_place", "status": "completed", "max_results": 1, "unit_point": 20, "reserved_point": 0, "charged_point": 20, "result_count": 1, "created_at": "2026-10-06T10:00:00.000Z", "completed_at": "2026-10-06T10:01:12.000Z", "result_expires_at": "2026-10-09T10:01:12.000Z", "items": [ { "name": "Starbucks Reserve Gangnam", "category": "Coffee shop", "categories": [ "Coffee shop", "Cafe" ], "address": "390 Gangnam-daero, Gangnam District, Seoul, South Korea", "country_code": "KR", "phone": "+82 1522-3232", "website": "http://www.starbucks.co.kr/", "description": "Welcoming coffeehouse with handcrafted coffee, espresso & tea, plus breakfast, lunch & pastries.", "rating": 4.3, "reviews_count": 1687, "rating_distribution": { "1": 35, "2": 34, "3": 212, "4": 554, "5": 852 }, "top_reviews": [ { "reviewer_name": "Example Reviewer", "rating": 5, "posted_at": "2024-10-10T10:29:41.348Z", "text": "Starbucks located in front of Exit 1 of Gangnam Station. It is always crowded ..." } ], "open_hours": { "Monday": "7 AM–10 PM", "Sunday": "8 AM–10 PM" }, "popular_times": [ { "day": 1, "hours": [ { "hour": "8 AM", "busy_percent": 17 }, { "hour": "9 AM", "busy_percent": 28 } ] } ], "similar_places": [ { "name": "Starbucks Gangnam-daero", "category": "Coffee shop", "rating": 4.1, "reviews_count": 1075 } ], "photo_urls": [ "https://lh3.googleusercontent.com/..." ], "main_image_url": "https://lh3.googleusercontent.com/...", "is_claimed": true, "permanently_closed": false, "temporarily_closed": false, "latitude": 37.497853, "longitude": 127.028587, "place_id": "ChIJobb671mhfDURrcE4SebLfyw", "map_url": "https://www.google.com/maps/place/Starbucks+Reserve+Gangnam/..." } ], "result_expired": false }, "api": { "success": true, "cost": 0 } }