# 구글 지도 장소 검색 키워드의 구글 지도 장소 검색 결과(상호·주소·전화·평점·리뷰 수·영업시간·좌표)를 최대 20곳 조회합니다. 인증: Authorization: Bearer $APICK_API_KEY 본문 있는 REST 요청: multipart/form-data. GET 본문 및 MCP JSON-RPC 규격은 해당 명세를 따릅니다. 인증키는 서버에 보관하세요. 모든 예제는 정적 자료입니다. ## POST /rest/google_maps_search 응답 필드 - `data` (object): 조회 데이터. 실패하면 error 에 안내 문구가 담깁니다. - `data.keyword` (string): 요청한 검색어 - `data.count` (integer): items 개수 - `data.items` (array): 장소 목록 (최대 20곳) - `data.items[].rank` (integer): 결과 내 순서 - `data.items[].name` (string): 상호 - `data.items[].address` (string): 주소 - `data.items[].phone` (string): 전화번호. 없으면 빈 문자열 - `data.items[].categories` (array): 업종 목록 - `data.items[].rating` (number): 평점. 없으면 null null 허용. - `data.items[].reviews` (integer): 리뷰 수. 없으면 null null 허용. - `data.items[].price_range` (string): 가격대 표기. 없으면 빈 문자열 - `data.items[].open_status` (string): 영업 상태 표기 - `data.items[].open_hours` (object): 요일별 영업시간 - `data.items[].open_hours.월요일` (string): 아래 하위 항목을 확인하세요. - `data.items[].website` (string): 웹사이트 주소. 없으면 빈 문자열 - `data.items[].latitude` (number): 위도 - `data.items[].longitude` (number): 경도 - `data.items[].place_id` (string): 구글 지도 장소 ID - `data.items[].map_link` (string): 구글 지도 주소 - `data.items[].thumbnail` (string): 대표 사진 주소 - `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_maps_search ### 입력 - `keyword` (string, 필수): 장소 검색어 (예: 강남역 카페, 1~200자) ### 응답 명세 ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "keyword": { "type": "string", "description": "요청한 검색어" }, "count": { "type": "integer", "description": "items 개수" }, "items": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer", "description": "결과 내 순서" }, "name": { "type": "string", "description": "상호" }, "address": { "type": "string", "description": "주소" }, "phone": { "type": "string", "description": "전화번호. 없으면 빈 문자열" }, "categories": { "type": "array", "items": { "type": "string" }, "description": "업종 목록" }, "rating": { "type": "number", "description": "평점. 없으면 null", "nullable": true }, "reviews": { "type": "integer", "description": "리뷰 수. 없으면 null", "nullable": true }, "price_range": { "type": "string", "description": "가격대 표기. 없으면 빈 문자열" }, "open_status": { "type": "string", "description": "영업 상태 표기" }, "open_hours": { "type": "object", "properties": { "월요일": { "type": "string" } }, "description": "요일별 영업시간" }, "website": { "type": "string", "description": "웹사이트 주소. 없으면 빈 문자열" }, "latitude": { "type": "number", "description": "위도" }, "longitude": { "type": "number", "description": "경도" }, "place_id": { "type": "string", "description": "구글 지도 장소 ID" }, "map_link": { "type": "string", "description": "구글 지도 주소" }, "thumbnail": { "type": "string", "description": "대표 사진 주소" } } }, "description": "장소 목록 (최대 20곳)" } }, "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": "강남역 카페", "count": 1, "items": [ { "rank": 1, "name": "셀렉티드닉스 강남역점", "address": "대한민국 서울특별시 강남구 테헤란로4길 37", "phone": "+821000000000", "categories": [ "카페", "커피숍/커피 전문점" ], "rating": 4.9, "reviews": 1693, "price_range": "₩10,000~20,000", "open_status": "영업 중 · 오전 12:00에 영업 종료", "open_hours": { "월요일": "오전 8:00~오전 12:00" }, "website": "https://www.instagram.com/sltdnicks/", "latitude": 37.4961927, "longitude": 127.0308697, "place_id": "ChIJU6CqMS6hfDURoNmZ0I2bQOs", "map_link": "https://www.google.com/maps/place/data=!3m1!4b1!4m2!3m1!1s0x357ca12e31aaa053:0xeb409b8dd099d9a0", "thumbnail": "https://lh3.googleusercontent.com/..." } ] }, "api": { "success": true, "cost": 10, "pl_id": 1595635, "ms": 33120 } } ``` ### curl ```curl curl --fail-with-body --request POST 'https://apick.app/rest/google_maps_search' \ --header "Authorization: Bearer $APICK_API_KEY" \ --form-string 'keyword=강남역 카페' ``` ### Node.js (서버 ESM) ```javascript const form = new FormData(); form.append("keyword", "강남역 카페"); const response = await fetch("https://apick.app/rest/google_maps_search", { 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, "강남역 카페")), ] response = requests.request("POST", "https://apick.app/rest/google_maps_search", headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]}, files=parts, timeout=(10, 120)) response.raise_for_status() result = response.json() print(result) ``` ### php ```php '강남역 카페', ]; $curl = curl_init('https://apick.app/rest/google_maps_search'); 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_maps_search 지역명과 업종을 함께 넣으면 정확도가 높아집니다 (예: 성수동 카페). 처리에 보통 30~60초가 걸립니다. 클라이언트 타임아웃을 90초 이상으로 설정해 주세요. 실패한 호출(입력 오류, 시간 초과, 대상 없음)은 과금하지 않습니다. 같은 요청은 최대 10분 동안 같은 결과가 반환될 수 있습니다. API 호출 요청 요청하기 Key Value keyword 응답 ## 상세 요청 Header 이름 필수 설명 Authorization O Bearer 인증키 ## 상세 응답 Body 이름 타입 설명 data Object 조회 데이터. 실패하면 error 에 안내 문구가 담깁니다. keyword String 요청한 검색어 count Integer items 개수 items Array 장소 목록 (최대 20곳) rank Integer 결과 내 순서 name String 상호 address String 주소 phone String 전화번호. 없으면 빈 문자열 categories Array 업종 목록 rating Number 평점. 없으면 null reviews Integer 리뷰 수. 없으면 null price_range String 가격대 표기. 없으면 빈 문자열 open_status String 영업 상태 표기 open_hours Object 요일별 영업시간 website String 웹사이트 주소. 없으면 빈 문자열 latitude Number 위도 longitude Number 경도 place_id String 구글 지도 장소 ID map_link String 구글 지도 주소 thumbnail String 대표 사진 주소 api Object API 호출 공통 데이터 success Boolean API 서버 정상 응답 여부 cost Integer 차감된 포인트. 실패한 응답은 0 ms Integer API 응답 시간(밀리초) pl_id Integer API 결제 로그 ID ## 상세 예제 요청 예시 form-data 전체 예제 보기 응답 예시 { "data": { "keyword": "강남역 카페", "count": 1, "items": [ { "rank": 1, "name": "셀렉티드닉스 강남역점", "address": "대한민국 서울특별시 강남구 테헤란로4길 37", "phone": "+821000000000", "categories": [ "카페", "커피숍/커피 전문점" ], "rating": 4.9, "reviews": 1693, "price_range": "₩10,000~20,000", "open_status": "영업 중 · 오전 12:00에 영업 종료", "open_hours": { "월요일": "오전 8:00~오전 12:00" }, "website": "https://www.instagram.com/sltdnicks/", "latitude": 37.4961927, "longitude": 127.0308697, "place_id": "ChIJU6CqMS6hfDURoNmZ0I2bQOs", "map_link": "https://www.google.com/maps/place/data=!3m1!4b1!4m2!3m1!1s0x357ca12e31aaa053:0xeb409b8dd099d9a0", "thumbnail": "https://lh3.googleusercontent.com/..." } ] }, "api": { "success": true, "cost": 10, "pl_id": 1595635, "ms": 33120 } }