google-maps/
search

검색어와 위치로 공개 Google Maps 장소를 검색하여, 정규화된 이름, 카테고리, 주소, 연락처, 평점, 리뷰 수, URL, 좌표를 반환합니다.

Google Maps Search API

검색어와 위치 입력
선택 지리 정보
요청 결과 1~2,000건
정규화된 장소 레코드
결과당 0.15 크레딧
준비됨
준비됨

매개변수를 입력하고 요청을 전송하세요. 작업 상태와 정규화된 결과가 여기에 표시됩니다.

README

SocQ 작성 · 업데이트

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 사용 방법

검색어와 위치를 제출하고, 비동기 작업을 추적한 뒤, 정규화된 장소 레코드를 커서 페이지네이션으로 읽습니다.

  1. 비어 있지 않은 query와 location을 준비하고, 필요하면 country, 좌표, zoom_level, 1 이상 2,000 이하의 results_limit을 추가합니다.
  2. 요청을 /v1/google-maps/search로 POST하고, 반환된 task_id를 저장합니다.
  3. 작업이 성공하거나 실패를 보고할 때까지 /v1/tasks/{task_id}를 폴링합니다.
  4. 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 true

Google 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을 보관하세요.

Google Maps Search API 외에 Google Maps의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.

다른 플랫폼 둘러보기

Google Maps 데이터를 지원되는 다른 소셜 플랫폼의 공개 데이터와 함께 활용하세요.

Google Maps Search API — 자주 묻는 질문

Google Maps Search API는 필수 검색어와 위치로 공개 장소를 찾는 비동기 인터페이스입니다. 확인 가능한 식별 정보, 카테고리, 주소, 연락처, 평점, 리뷰 수, URL, 지리 필드를 담은, 제공처와 무관한 PlaceItem 레코드를 반환합니다.

query와 location은 둘 다 비어 있지 않은 문자열이어야 하는 필수 값입니다. country, latitude, longitude, zoom_level, results_limit은 선택 값입니다.

네. 현재 요청 사양은 좌표를 쌍으로만 받습니다. 둘 다 생략하면 location이 query와 결합되고, 지정하려면 -90 이상 90 이하의 latitude와 -180 이상 180 이하의 longitude를 함께 제공하세요.

results_limit은 수집 최대치일 뿐 보장되는 값이 아닙니다. 원본에서 일치하는 공개 장소가 더 적게 반환될 수 있고, 노출된 식별 정보가 같은 레코드는 작업당 한 번만 저장됩니다.

공개 장소 결과에는 설명, 카테고리, 주소, 전화번호, 웹사이트, 평점, 리뷰 수, URL 또는 일부 위치 필드가 없을 수 있습니다. 클라이언트는 null 값을 작업 실패로 간주하지 말고 처리해야 합니다.

저장된 장소 레코드 1건당 0.15 SocQ 크레딧이 차감됩니다. 선차감은 results_limit(생략하면 100)을 기준으로 하며, 성공 후에는 실제로 저장된 결과 수에 맞춰 정산되고 결과가 비어 있으면 결과 요금이 없습니다.