Google Maps Search
Google Maps Search는 업체, 카테고리 또는 장소 검색어와 필수 위치를 구조화된 공개 장소 레코드로 바꿔 줍니다. 저장되는 결과는 모두 제공처와 무관한 PlaceItem 스키마를 따르므로, 확인 가능한 식별 정보, 주소, 연락처, 평점, 리뷰 수, 좌표 필드를 원본별 응답 키에 얽매이지 않고 조사 및 정보 보강 시스템으로 넘길 수 있습니다.
Google Maps Search API 주요 기능
- 검색어와 위치 기반 탐색coffee 같은 필수 검색어(비어 있지 않아야 함)와 New York, NY 같은 필수 위치를 조합해 일치하는 공개 장소를 찾습니다.
- 선택 지리 조건검색에 더 명확한 지리적 맥락이 필요하면 국가, 위도·경도 쌍, zoom_level을 추가하세요. 생략한 선택 필드를 임의로 채우지 않습니다.
- 정규화된 장소 식별 및 연락처 데이터ID, 원본 URL, 이름, 카테고리, 주소, 공개 전화번호, 웹사이트, 수집 시각(확인 가능한 경우)을 안정적인 PlaceItem 필드로 받습니다.
- 평점과 지리 좌표확인 가능한 평점, 리뷰 수, 도시, 지역, 국가, 위도, 경도를 장소마다 함께 보관하며, 원본에 없는 필드도 안전하게 처리합니다.
Google Maps Search API 매개변수
| 매개변수 | 필수 | 설명 |
|---|---|---|
query | 필수 | 장소, 업체 또는 카테고리의 검색어로, 비어 있지 않아야 하는 필수 값입니다. |
location | 필수 | 도시, 지역, 주소처럼 사람이 읽을 수 있는 검색 지역으로, 비어 있지 않아야 하는 필수 값입니다. 위도와 경도를 모두 생략하면 탐색 시 검색어와 결합됩니다. |
country | 선택 | 지리적 맥락으로 전달되는 국가 이름 또는 코드로, 비어 있지 않아야 하는 선택 값입니다. |
latitude | 선택 | -90 이상 90 이하의 위도이며, 선택 값입니다. longitude와 함께 지정해야 합니다. |
longitude | 선택 | -180 이상 180 이하의 경도이며, 선택 값입니다. latitude와 함께 지정해야 합니다. |
zoom_level | 선택 | 0 이상 21 이하의 지도 확대 수준 정수이며, 선택 값입니다. |
results_limit | 선택 | 저장할 장소 레코드의 최대 개수입니다. 기본값은 100이며 1 이상 2,000 이하의 정수를 받습니다. |
Google Maps Search API 사용 방법
검색어와 위치를 제출하고, 비동기 작업을 추적한 뒤, 정규화된 장소 레코드를 커서 페이지네이션으로 읽습니다.
- 비어 있지 않은 query와 location을 준비하고, 필요하면 country, 좌표, zoom_level, 1 이상 2,000 이하의 results_limit을 추가합니다.
- 요청을 /v1/google-maps/search로 POST하고, 반환된 task_id를 저장합니다.
- 작업이 성공하거나 실패를 보고할 때까지 /v1/tasks/{task_id}를 폴링합니다.
- data.results.items를 읽고, has_more가 true인 동안 next_cursor를 작업 엔드포인트에 전달합니다.
curl -X POST "https://api.socq.ai/v1/google-maps/search" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"coffee","location":"New York, NY","country":"US","results_limit":3}'
# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is trueGoogle Maps Search API 추천 활용 사례
- 지역 업체 탐색: 지정한 도시, 구역 또는 주소 일대에서 특정 카테고리나 서비스에 해당하는 공개 업체의 제한된 목록을 만듭니다.
- 위치 데이터 정보 보강: CRM이나 조사 대기열에 이미 있는 장소 후보에 확인 가능한 이름, 카테고리, 주소, 전화번호, 웹사이트, 좌표를 추가합니다.
- 시장·커버리지 조사: 각각 따로 제출한 지역 검색 사이에서 수집된 장소 수, 카테고리, 평점, 리뷰량을 비교합니다.
- 장소 후보 목록 준비: 공개 URL, 연락처 필드, 평점 정보, 좌표를 활용해 별도의 검증 또는 상세 조회 워크플로로 넘길 장소를 고릅니다.
Google Maps Search API 활용 팁
- 구체적인 카테고리나 업체 용어를 쓰고, location에는 명확한 도시, 구역 또는 주소를 넣으세요. 모호한 조합은 범위가 넓거나 불분명한 결과를 낼 수 있습니다.
- country, 좌표, zoom_level은 검증된 지리적 맥락일 때만 보내세요. latitude와 longitude는 함께 지정하고, 두 값 모두 문서에 정의된 범위 안에 두어야 합니다.
- results_limit은 필요한 레코드 수에 가깝게 유지하세요. 이 값은 수집 상한을 정하고, 작업 GET의 limit은 응답 페이지마다 반환되는 저장 레코드 수를 정합니다.
- 저장된 결과가 첫 작업 응답 페이지를 넘는 경우에는 has_more가 false가 될 때까지 next_cursor로 계속 읽으세요.
- 설명, 연락처 필드, 평점, 리뷰 수, 좌표는 선택적인 공개 데이터로 취급하고, 특정 시점 비교를 위해 collected_at을 보관하세요.
관련 API
Google Maps Search API 외에 Google Maps의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.