Google Maps Place Details
공개된 Google Maps 장소 페이지에는 이름, 카테고리, 설명, 주소, 연락처, 평점, 리뷰 수, 웹사이트, 지리적 맥락이 노출될 수 있습니다. 정규화된 레코드로 만들면 이러한 공개 필드를 위치 목록, 매장 조사, 디렉터리 정보 보강, 특정 시점 모니터링과 쉽게 결합할 수 있습니다.
Google Maps Place Details API 주요 기능
- URL 일괄 상세 수집알고 있는 Google Maps URL을 하나 이상 제출하면, 비어 있지 않은 입력마다 제공처 상세 행이 하나씩 만들어지며 내부적으로 제출한 URL 수까지로 제한됩니다.
- 안정적인 장소 레코드PlaceItem 스키마에 따라 식별 정보, 원본 URL, 이름, 설명, 카테고리, 주소, 전화번호, 웹사이트, 평점, 리뷰 수를 반환합니다.
- 구조화된 지리 정보확인 가능한 위치 이름, 도시, 지역, 국가, 위도, 경도를 화면 표시 텍스트에서 따로 파싱하지 않고 하나로 묶어 유지합니다.
- 결과 기준 과금예상 요금은 제출한 URL당 0.15 크레딧이며, 최종 정산은 성공적으로 반환된 표준 장소 레코드 1건당 0.15 크레딧입니다. 결과가 비어 있으면 요금이 부과되지 않습니다.
Google Maps Place Details API 매개변수
| 매개변수 | 필수 | 설명 |
|---|---|---|
urls | 필수 | 파서가 호스트 이름을 추출할 수 있는 참조 값의 배열로, 비어 있지 않아야 하는 필수 값입니다. 런타임은 호스트 이름이 google.com, goo.gl 또는 그 서브도메인인 값을 받아들이고, 권한(authority) 부분이 있는 모든 스킴과 프로토콜 상대 참조도 허용하며, 특정 경로 형식은 요구하지 않습니다. |
Google Maps Place Details API 사용 방법
알고 있는 Google Maps URL을 제출하고, 비동기 작업을 추적한 뒤, 표준 커서 결과 구조에서 저장된 PlaceItem을 모두 읽습니다.
- 파싱한 호스트 이름이 google.com, goo.gl 또는 둘 중 하나의 서브도메인인 참조 값을 하나 이상 준비합니다.
- urls를 /v1/google-maps/place-details로 POST하고, 반환된 task_id를 저장합니다.
- 작업이 성공하거나 실패할 때까지 /v1/tasks/{task_id}를 폴링합니다.
- data.results.items를 읽고 has_more가 true인 동안 next_cursor를 따라갑니다. 제출 요청 자체에는 results_limit 필드가 없습니다.
curl -X POST "https://api.socq.ai/v1/google-maps/place-details" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://www.google.com/maps/place/Coffee%20Project%20New%20York%20%7C%20East%20Village/data=!4m7!3m6!1s0x89c2599b5a24d7fd:0x9e354f6cf514b9fc!8m2!3d40.7270884!4d-73.9893820!16s%2Fg%2F11c3svpqld!19sChIJ_dckWptZwokR_LkU9WxPNZ4?authuser=0&hl=en&rclk=1"]}'
# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is trueGoogle Maps Place Details API 추천 활용 사례
- 위치 디렉터리 정보 보강: 알고 있는 장소 URL에 정규화된 카테고리, 주소, 전화번호, 웹사이트, 평점, 리뷰 수, 좌표 필드를 추가합니다.
- 매장·지점 점검: 관리하는 URL 목록을 다시 조회하여 정해 둔 수집 시점마다 공개된 식별 정보, 연락처, 평점, 지리 값을 비교합니다.
- 장소 레코드 대조: 반환된 ID, 원본 URL, 이름, 주소, 좌표로 공개 장소를 내부 위치 레코드와 매칭합니다.
Google Maps Place Details API 활용 팁
- 파서가 허용된 호스트 이름을 확인할 수 있도록 스킴이 포함된 완전한 Maps URL을 제출하세요. 스킴이 없는 호스트 이름만으로는 런타임 파서에서 호스트 이름이 추출되지 않습니다.
- Place ID, Google API 키, 필드 마스크, results_limit은 이 SocQ 요청 사양의 필드가 아니므로 추가하지 마세요.
- 제출한 URL마다 상세 조회 후보일 뿐 결과가 보장되는 것은 아닙니다. 확인할 수 없거나 사용할 수 없는 원본 행이 있으면 URL 수보다 항목이 적을 수 있습니다.
- 전화번호, 웹사이트, 평점, 리뷰 수, 설명, 게시 시각, 위치 멤버가 null일 수 있으므로 임의의 대체 값을 채우지 말고 그대로 보존하세요.
- has_more가 true인 동안은 next_cursor를 따라 계속 읽으세요. 제공처의 상한은 URL 수로 정해지지만, 저장된 작업 결과를 읽을 때는 페이지네이션이 적용됩니다.
관련 API
Google Maps Place Details API 외에 Google Maps의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.
- Google Maps Search API — 검색어와 위치로 공개 Google Maps 장소를 검색하며, 정규화된 장소 정보, 주소, 연락처, 평점, 리뷰 수, URL, 좌표 필드를 포함합니다.
- Google Maps Reviews API