비즈니스 식별 정보 및 위치
비즈니스 이름, 카테고리, 형식화된 주소, 좌표, Maps URL을 사용해 지역 비즈니스 데이터 세트를 구성합니다.
전체 계약 내용은 API 문서를 참조하세요.
curl https://gmapscrawl.com/api/v1/search \
-H "Authorization: Bearer $GMSCRAPER_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: seattle-coffee-search-001" \
-d '{"q":"coffee shops in Seattle","page":1,"extra":false}'예시용 빈 응답입니다. 라이브 검색은 사용 가능한 비즈니스를 반환합니다. API 키는 서버 측에 보관하고, 새 작업에는 새 멱등 키를 사용하고, 변경되지 않은 재시도에는 그대로 유지하세요.
{
"data": {
"total": 0,
"params": {
"q": "coffee shops in Seattle",
"page": 1,
"hl": "en",
"extra": false
},
"businesses": []
},
"request_id": "req_example",
"schema_version": "2026-09-22"
}API는 동일한 응답 안에서 JSON을 반환합니다. 타임아웃 후에는 동일한 Idempotency-Key로 변경되지 않은 본문을 재시도하세요. 테스트 자격 증명은 실제 사용량을 소비하지 않고 시뮬레이션된 데이터를 반환합니다.
구조화된 비즈니스 데이터
응답에서 data.businesses를 읽으세요. 각 비즈니스는 리스팅 필드를 place 아래에 그룹화하며, 필드 가용성은 소스에 따라 달라집니다.
비즈니스 이름, 카테고리, 형식화된 주소, 좌표, Maps URL을 사용해 지역 비즈니스 데이터 세트를 구성합니다.
사용 가능한 전화번호, 웹사이트, 평점, 리뷰 수를 읽으세요. extra를 활성화하면 이메일 및 소셜 연락처 인리치먼트를 요청할 수 있습니다.
리뷰 및 사진 조회를 위해 place.dataId를 보관하세요. place.observedAt과 contactsCheckedAt을 확인해 데이터가 언제 관측됐는지 파악하세요.
사용할 수 없는 필드는 null이거나 비어 있을 수 있고, 인리치먼트는 not_found 또는 failed를 보고할 수 있습니다. 레코드가 있다고 해서 이메일 주소나 웹사이트가 존재함을 보장하지는 않습니다. Maps 세부 정보는 원래 관측 타임스탬프와 함께 최대 730일 동안 재사용될 수 있으므로 레코드를 사용하기 전에 최신성을 평가하세요.
데이터 최신성에 대해 읽기 →집중된 요청
서버 측 API 키를 authorization 헤더에 넣어 JSON 본문을 전송하세요. q만 필수입니다.
| 파라미터 | 요구 사항 | 목적 |
|---|---|---|
| q | 필수 | 시애틀의 커피숍과 같은 비즈니스 키워드와 지역. 2~200자를 사용하세요. |
| page | 기본값: 1 | 1~10의 번호가 매겨진 검색 페이지. 각 요청은 최대 20개의 비즈니스를 반환합니다. |
| ll | 선택 | 검색 위치를 안내하는 @47.6062,-122.3321,12z 형식의 Maps 뷰포트. |
| hl | 기본값: en | 검색에 사용되는 언어 코드. |
| gl | 선택 | 쿼리를 한정하는 두 글자 국가 코드. 엄격한 지리적 필터는 아닙니다. |
| extra | 기본값: false | true로 설정하면 사용 가능한 이메일 및 소셜 연락처 인리치먼트를 요청합니다. 시간이 더 걸릴 수 있습니다. |
응답은 정규화된 파라미터를 data.params에 에코합니다. data.total 값은 Google Maps의 전체 비즈니스 수가 아닌 이 응답의 비즈니스 수를 나타냅니다. 워크플로에 더 많은 결과가 필요하면 명시적으로 다른 페이지를 선택하세요.
첫 통합 구축
Search API는 동기식입니다: HTTP 응답에서 직접 결과를 읽습니다.
API 워크스페이스에서 scrapes:write 권한이 있는 키를 만드세요. 키를 서버 환경에 저장하고 요청과 함께 Authorization: Bearer를 보내세요.
API 키 열기카테고리와 지역을 선택하고, 1페이지를 요청하고, 반환된 리스팅 필드를 검사하세요. 시장 비교의 경우 비교하려는 지역별로 개별 검색을 실행하세요.
일치하는 비즈니스의 place.dataId를 fid로 사용해 리뷰 페이지나 갤러리 페이지를 가져오세요. 이들은 고유한 레코드를 반환하는 별도의 요청입니다.
Reviews API 살펴보기실제 요청 계획
성공한 라이브 검색 페이지는 빈 결과를 포함해 페이지당 하나의 API 요청 단위를 사용합니다. REST와 MCP는 API 사용량을 공유합니다. Online 스크래퍼와 Extension 구독은 별도의 사용량을 가집니다. 속도 제한, 자격 증명, 서비스 용량, 소스 가용성도 계속 적용됩니다.
API 플랜 비교 →HTTP 클라이언트에서 최대 180초를 허용하세요. 타임아웃은 요청 단위가 예약된 상태로 작업이 진행되게 할 수 있습니다. 동일한 본문과 Idempotency-Key를 재사용해 해당 요청을 재시도하세요. 새 시도를 시작하기 전에 오류 세부 정보와 재시도 가능 여부를 확인하세요.
재시도 이해하기 →워크플로 계속하기
feature ID를 사용해 장소의 공개 리뷰 또는 사진 및 동영상 메타데이터를 가져옵니다.
갤러리 데이터 살펴보기호환되는 AI 클라이언트가 API 자격 증명으로 검색, 리뷰, 사진 도구를 검색하게 하세요.
MCP 설정에이전트에 워크플로 지침, 작업 참조, Google Maps 조사용 REST 폴백을 제공하세요.
스킬 살펴보기data.businesses, data.total, 정규화된 data.params, request_id, schema_version이 포함된 JSON 엔벨로프를 반환합니다. 비즈니스에는 이름, 주소, 카테고리, 연락처 정보, 평점, Maps 식별자와 같은 사용 가능한 리스팅 필드가 포함됩니다.
예. 엔드포인트는 JSON 및 Bearer 인증이 있는 표준 HTTP POST 요청을 허용합니다. 위 예시는 Python 표준 라이브러리와 서버 측 JavaScript fetch를 사용합니다. 해당 헤더와 본문을 보낼 수 있는 모든 HTTP 클라이언트가 통합할 수 있습니다.
검색 페이지는 0~20개의 비즈니스를 반환합니다. page 파라미터는 1~10을 허용합니다. 성공한 각 라이브 페이지는 빈 페이지를 포함해 하나의 API 요청 단위를 사용하며, 검색 시 모든 페이지에 20개의 비즈니스가 있다고 보장하지 않습니다.
예. 비즈니스에서 place.dataId를 복사해 별도의 Reviews 또는 Photos API에 fid로 전달하세요. 해당 엔드포인트는 요청당 하나의 제한된 페이지를 반환합니다. API 개요에는 각 엔드포인트의 필드, 예시, 페이지네이션 규칙에 대한 링크가 있습니다.
아니요. extra를 true로 설정해 사용 가능한 연락처 인리치먼트를 요청하세요. 웹사이트, 이메일, 소셜 프로필이 누락될 수 있습니다. enrichmentState와 fieldStates를 검사하고 애플리케이션에서 사용 불가능한 데이터를 명시적으로 유지하세요.
테스트 자격 증명이 있다면 응답이 시뮬레이션되고 라이브 API 사용량을 소비하지 않습니다. 해당 결과를 시뮬레이션으로 표시하세요. 라이브 키에는 활성 API 권한과 사용 가능한 서비스 용량이 필요하며, 성공한 라이브 호출은 요청 단위를 사용합니다.
다음 단계로 이동
API 키를 만들고, 하나의 쿼리와 지역을 선택하고, 동일한 응답에서 구조화된 비즈니스 데이터를 읽어보세요.