API 목록으로 돌아가기
독립형 Google Maps 데이터

Google Maps API

공개 장소를 찾고, 이미 알고 있는 Maps URL의 정규화된 상세 정보를 가져오고, 출처가 연결된 장소·작성자 정보와 함께 공개 리뷰를 수집합니다.

사용할 수 있는 Google Maps API

검색어와 위치로 찾는 탐색에는 Search, 이미 알고 있는 Maps URL에는 Place Details, 범위가 정해진 공개 리뷰 수집에는 Reviews를 사용합니다.

어떤 Google Maps 데이터를 가져올 수 있나요?

SocQ는 위치 리서치, 비즈니스 탐색, 데이터 보강, 특정 시점의 시장 스냅샷에 쓸 수 있도록 정규화된 공개 PlaceItem 레코드를 반환합니다.

장소 식별 정보

제공되는 장소 ID, 이름, 카테고리, 출처 URL, 레코드 유형, 수집 타임스탬프를 가져옵니다.

주소와 지리 정보

제공되는 전체 주소, 위치 라벨, 도시, 지역, 국가, 위도, 경도를 그대로 유지합니다.

공개 연락처

검색 결과에 노출된 경우 공개 전화번호와 웹사이트를 수집합니다.

평점과 리뷰 수

원본에서 제공하는 평점과 리뷰 수를 그대로 보존하며, 없는 값을 추정하지 않습니다.

설명과 카테고리

제공되는 요약 텍스트와 카테고리 라벨로 장소 결과를 분류하고 후보를 추립니다.

작업·페이지네이션 메타데이터

작업 상태와 result_count를 확인하고, next_cursor와 has_more로 저장된 PlaceItem 레코드를 페이지 단위로 읽습니다.

위치 텍스트와 좌표 정보

Google Maps Search에는 항상 query와 location이 필요합니다. 현재 런타임 사양에서 좌표는 location을 대체하지 않고 선택적으로 더하는 보조 정보입니다.

입력 방식런타임 동작사용하기 좋은 경우
location만 지정위치 텍스트가 query와 결합되어 탐색에 사용됩니다도시, 지구, 랜드마크, 주소 중심의 검색
location과 좌표 2개location은 계속 필수이며 좌표는 lat과 long으로 전달됩니다확인된 지리적 중심이 있을 때
location과 좌표 1개지정한 좌표만 개별적으로 전달됩니다일부 지리 정보만 쓰려는 의도가 분명할 때만 사용
country와 zoom_level선택 정보가 검색 행과 함께 전달됩니다국가 힌트나 0부터 21까지의 명시적 줌이 필요할 때

Google Maps API 작동 방식

범위가 정해진 장소 검색을 제출하고, 비동기 수집이 끝나기를 기다린 뒤, 작업에 저장된 정규화 레코드를 페이지 단위로 읽습니다.

  1. 1. 장소 검색 정의

    구체적인 query와 필수 location을 정하고, 필요한 만큼만 확인된 선택적 지리 정보를 추가합니다.

  2. 2. 작업 제출과 추적

    요청을 POST하고 task_id를 저장한 뒤, 처리가 성공하거나 실패할 때까지 /v1/tasks/{task_id}를 폴링합니다.

  3. 3. 정규화된 장소 읽기

    data.results.items를 처리하고, has_more가 true인 동안 next_cursor를 따라갑니다.

공개 장소 검색

query와 location을 작은 결과 상한과 함께 제출한 뒤, 공통 작업 엔드포인트에서 정규화된 PlaceItem 결과를 읽습니다.

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 API 주요 활용 사례

지역 비즈니스 탐색

도시, 지구, 랜드마크, 주소를 기준으로 특정 카테고리나 서비스에 맞는 공개 비즈니스를 찾습니다.

장소 데이터 보강

기존 장소 후보에 제공되는 연락처, 주소, 카테고리, 평점, 리뷰 수, URL, 좌표 필드를 추가합니다.

지역별 시장 스냅샷

각각 제출한 지역마다 범위가 정해진 결과 세트를 수집하고, 특정 수집 시점의 공개 장소 분포를 비교합니다.

검증 대기열

공개 식별 정보, 연락처, 평점, 지리 필드로 후보 목록을 만들어 이후 검토나 별도의 상세 조회 과정에 넘깁니다.

제한 사항과 공개 데이터 정책

결과는 특정 시점의 공개 레코드입니다. 검색 가능 여부와 필드의 완성도는 제출한 요청에 대해 원본이 노출하는 내용에 따라 달라집니다.

  • query와 location은 둘 다 비어 있지 않은 문자열이어야 하며, location을 좌표로 대체할 수 없습니다.
  • country, latitude, longitude, zoom_level은 선택 사항이며, 현재 런타임은 latitude와 longitude를 따로따로 받습니다.
  • zoom_level은 0부터 21까지의 정수여야 하고, results_limit 기본값은 100이며 허용 범위는 1부터 2,000까지입니다.
  • results_limit은 수집 상한이고, 작업 GET의 limit은 저장된 결과를 응답 한 페이지에 몇 건씩 담을지 정합니다.
  • 공개 결과에는 설명, 카테고리, 연락처, 평점, 리뷰 수, URL, 지리 하위 필드가 없을 수 있습니다.
  • 노출된 식별 정보가 중복되면 작업당 한 번만 저장되므로, result_count가 원본에서 확인한 행 수보다 적을 수 있습니다.

Google Maps API 자주 묻는 질문

Google Maps API란 무엇인가요?

Google Maps API는 공개 장소를 비동기로 검색하고, 이미 알고 있는 장소 URL을 확인하고, 공개 리뷰를 정규화된 레코드로 수집합니다. Search는 query와 location을 받아 식별 정보, 주소, 연락처, 평점, 리뷰 수, URL, 좌표 필드가 포함된 PlaceItem 레코드를 반환합니다.

Search에는 무엇이 필요한가요?

Search에는 비어 있지 않은 query와 location 문자열이 필요합니다. country, latitude, longitude, zoom_level, results_limit은 선택 사항입니다.

수집과 응답 페이지네이션은 어떻게 다른가요?

results_limit은 제출한 검색에서 수집할 레코드 수의 상한입니다. 작업이 성공하면 작업 엔드포인트가 저장된 레코드를 별도의 limit과 next_cursor 매개변수로 제어되는 페이지 단위로 반환합니다.

장소 필드가 null인 이유는 무엇인가요?

공개 검색 결과에 연락처, 평점, 리뷰, 설명, URL, 주소, 좌표 필드가 모두 노출되지는 않기 때문입니다. 정규화 스키마는 이런 누락 값을 null로 보존합니다.

Google Maps Search 결과의 요금은 어떻게 되나요?

저장된 장소 1건당 0.15 크레딧입니다. 사전 차감 예상 금액은 results_limit을 기준으로 계산하며 지정하지 않으면 100을 적용하고, 정상 완료되면 실제 저장된 결과 수에 맞춰 정산합니다.

여러 플랫폼의 공개 프로필, 콘텐츠, 참여도 데이터를 하나의 워크플로로 모으면 브랜드, 크리에이터, 주제를 추적하고 플랫폼 간 모니터링과 분석을 더 효율적으로 진행할 수 있습니다.

Google Play API

이미 알고 있는 스토어 URL에서 공개 Google Play 앱 상세 정보, 카테고리 순위, 리뷰를 정규화된 앱·리뷰 레코드로 수집합니다.

Amazon API

지원되는 마켓플레이스에서 공개 Amazon 상품을 검색하고, 정규화된 상품 상세 정보, Best Sellers, 리뷰, 판매자 프로필, 크리에이터 스토어 레코드를 수집합니다.

Apple App Store API

이미 알고 있는 스토어 URL에서 공개 Apple App Store 앱 상세 정보, 카테고리 순위, 리뷰를 정규화된 앱·리뷰 레코드로 수집합니다.

SEO API

실시간 Google 오가닉 검색 결과를 조회하고, 키워드 수요와 순위 난이도를 비교하고, 시드 키워드를 확장하고, 사이트의 검색 노출을 이끄는 키워드와 페이지를 찾고, 검색 의도를 분류하며, Google 뉴스·이미지·자동완성과 Bing, YouTube 결과를 모읍니다. 모든 엔드포인트가 같은 SocQ API 키, 비동기 작업 흐름, 정규화된 결과 형식을 사용합니다.

Telegram API

t.me 링크로 공개 텔레그램 채널을 읽습니다. 구독자 수가 담긴 채널 정보, 조회수와 반응이 담긴 게시물, 개별 게시물, 토론 그룹 댓글, 추천 채널, 전체 기록 검색을 지원합니다.

Link in Bio API

크리에이터가 Instagram, TikTok, YouTube 소개란에 넣는 링크 하나를 표시 이름, 소개, 프로필 사진, 공개된 연락처 이메일, 연결된 SNS 프로필, 각 버튼의 제목과 연결 주소라는 구조화된 데이터로 바꿉니다.