Google Maps Search — API 레퍼런스

POST

사용 가능

/google/maps/search

지도 검색

쿼리와 위치로 Google Maps 장소를 찾습니다. 식별된 장소 상세는 별도 엔드포인트를 사용합니다.

type

maps_search

result

places

과금

2 credits

쿼리와 위치로 Google Maps 장소를 찾습니다. 식별된 장소 상세는 별도 엔드포인트를 사용합니다.

파라미터

필드타입제공 조건설명

q

필수

string

필수

검색 쿼리 문자열입니다.

hl

선택

string

선택

언어 코드입니다. 기본값은 en입니다.

gl

선택

string

선택

국가 코드입니다. 기본값은 us입니다.

page

선택

number

선택

1부터 시작하는 페이지 번호입니다. 기본값은 1입니다.

lat

선택

number

선택

지도 중심 위도입니다. lng와 함께 보내야 합니다.

lng

선택

number

선택

지도 중심 경도입니다. lat와 함께 보내야 합니다.

zoom

선택

number

선택

지도 줌 레벨입니다. 1부터 21까지이며 좌표가 있으면 기본값은 14입니다.

location

예시

object

카탈로그 예시. 필수 필드는 API가 검증합니다.

예시: {"location_query":"Seattle, WA"}

query

예시

string

카탈로그 예시. 필수 필드는 API가 검증합니다.

예시: "coffee"

json

{
  "location": {
    "location_query": "Seattle, WA"
  },
  "query": "coffee"
}

Playground에서 실행

응답 필드

필드타입제공 조건설명

query

필수

string

필수

요청에서 정규화된 쿼리입니다.

page

필수

number

필수

현재 페이지 번호입니다. 1부터 시작합니다.

places

선택

MapsPlace[]

지역 장소가 파싱된 경우.

지역 장소 결과.

MapsPlace 결과 항목 구조

필드타입제공 조건설명

position

선택

number

Maps 검색 전용.

지역 결과의 장소 순위.

name

필수

string

필수

장소 이름.

title

필수

string

필수

name의 별칭.

feature_id

필수

string

필수

Google Maps feature ID.

place_id

선택

string

Google이 제공하는 경우.

Google 장소 ID.

data_id

선택

string

feature_id의 별칭.

Maps 데이터 ID.

cid

선택

string

가능하면 feature_id에서 도출.

Google CID 값.

kgmid

선택

string

Maps 데이터에 있는 경우.

지식 그래프 머신 ID.

google_maps_url

선택

string

Google이 Maps URL을 제공하는 경우.

Google Maps URL 주소.

url

선택

string

google_maps_url, 없으면 website.

장소 기본 URL.

rating

선택

number

평점이 있는 경우.

Google 평점.

types

선택

string[]

카테고리가 있는 경우.

장소 유형 라벨.

category

선택

object

카테고리가 파싱된 경우.

구조화된 카테고리 데이터.

address

선택

string

주소가 있는 경우.

서식이 지정된 주소.

address_components

선택

object

주소 구성 요소가 있는 경우.

거리, 도시, 우편번호, 국가 코드.

plus_code

선택

object

Plus Code가 있는 경우.

전역 및 복합 Plus Code.

phone

선택

string

전화번호가 있는 경우.

지역 전화번호.

phone_international

선택

string

있는 경우.

국제 전화번호.

phone_uri

선택

string

있는 경우.

전화 URI.

website

선택

string

웹사이트가 있는 경우.

업체 웹사이트.

website_domain

선택

string

사이트 도메인이 있는 경우.

업체 사이트 도메인.

latitude

선택

number

좌표가 있는 경우.

위도.

longitude

선택

number

좌표가 있는 경우.

경도.

image

선택

string

이미지가 있는 경우.

장소 기본 이미지.

thumbnail

선택

string

이미지가 있으면 image 별칭.

기본 이미지 별칭.

photos

선택

MapsPhoto[]

사진이 파싱된 경우.

사진 ID, URL, 크기 및 선택적 좌표.

hours

선택

Record<string,string>

영업시간이 파싱된 경우.

요일별 영업시간.

open_status

선택

object

영업 상태가 있는 경우.

영업 상태 및 현재 영업시간.

attributes

선택

object[]

속성이 파싱된 경우.

그룹화된 장소 속성.

related_places

선택

object[]

관련 장소가 있는 경우.

Maps 데이터의 관련 장소.

short_description

선택

string

설명 블록이 있는 경우.

짧은 장소 설명.

description

선택

string

설명 블록이 있는 경우.

상세 장소 설명.

snippet

선택

string

short_description, 없으면 description.

정규화된 텍스트 요약.

timezone

선택

string

있는 경우.

장소 시간대.

region

선택

string

있는 경우.

지역 라벨.

country_code

선택

string

있는 경우.

국가 코드.

language

선택

string

있는 경우.

Maps 데이터의 언어 코드.

코드 및 응답 예시

bash

curl -X POST 'https://api.serpbase.dev/google/maps/search' \
  -H "Content-Type: application/json" \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{"location":{"location_query":"Seattle, WA"},"query":"coffee"}'

기존 Google 요청 예시

bash

curl -X POST https://api.serpbase.dev/google/maps/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "q": "coffee",
    "hl": "en",
    "gl": "us",
    "page": 1,
    "lat": 37.7749,
    "lng": -122.4194,
    "zoom": 14
  }'

참고

로컬 탐색, 매장 조회, 지역별 감사.

lat과 lng는 함께 보내야 합니다. zoom은 좌표가 있을 때만 유효하며 기본값은 14입니다.