Google API: 지도 — 검색어별 장소

이 엔드포인트가 하는 일

이 API 메서드로 만들 수 있는 것

먼저 결과와 일반적인 워크플로를 확인한 다음 매개변수와 작동하는 요청 예제로 넘어가세요.

이 엔드포인트가 도움이 되는 일

응답에는 일치하는 지도, 공개 컨텍스트, 결과가 더 있을 경우 페이지네이션 데이터가 포함됩니다.

적합한 사용 시점

객체의 정확한 ID를 모르고 먼저 관련 후보를 찾아야 할 때 "검색어별 장소"을 사용하세요.

주요 사용 사례

제품 내 검색

고객용 및 내부 화면에 Google 데이터 검색을 추가하세요.

카탈로그 구축

검색어로 후보를 찾고 관련 객체를 저장해 나중에 보강하세요.

시장 조사

주제, 크리에이터, 경쟁 분석을 위한 결과 집합을 수집하세요.

사용 가능한 버전

응답 버전

두 버전 모두 같은 작업을 해결하며 같은 매개변수를 받습니다. 전환기로 응답 구조를 비교하고 클라이언트가 기대하는 버전을 선택하세요.

응답 버전 V2

이 페이지에서 버전을 전환하면 같은 문서 URL에서 응답 구조를 비교할 수 있습니다.

V1 사용 불가

동일하게 유지되는 것

인증, 필수 매개변수, 요청 형태는 V1과 V2에서 같습니다. 실제로는 엔드포인트 경로를 구성할 때와 응답을 읽을 때 버전을 선택합니다.

버전 간에 달라지는 것

주요 차이는 응답 봉투입니다. 새 연동에는 V2를 사용하고, 기존 클라이언트 계약과의 호환성이 필요한 경우에만 V1을 유지하세요.

사용 방법

메서드 호출 방법

두 버전 모두 같은 API 키 헤더와 같은 쿼리 매개변수를 사용합니다. 이 문서는 먼저 공통 매개변수를 보여 준 다음 각 버전의 경로와 코드 스니펫을 보여 줍니다.

입력 매개변수

공통 매개변수

매개변수	필수	유형	예시	설명
`query`	예	`str`	`coffee shops`	사용자가 입력한 검색어.
`coordinates`	아니요	`str \| None`	`@37.7749,-122.4194`	Optional map coordinates in Google Maps center format. Example: @37.7749,-122.4194.
`country_code`	아니요	`str`	`US`	Two-letter country code used for geo-localized Google results. Example: US.
`cursor`	아니요	`str \| None`	`eyJmaW5nZXJwcmludCI6Ii4uLiJ9.signature`	이전 응답에서 받은 다음 페이지 커서. 첫 페이지에서는 생략합니다.
`language`	아니요	`str \| None`	`en`	Optional Google interface language code used for localized text fields. Example: en.
`radius_meters`	아니요	`float \| None`	`5000`	Optional search radius in meters for Google Maps places search. Example: 5000.

버전별 요청 경로

V2

정확한 엔드포인트 경로, 예시 URL, 코드 스니펫을 복사할 때 버전을 선택하세요. 위의 매개변수 목록은 바뀌지 않습니다.

GET /api/v2/google.com/maps/places-by-query

정규화된 형식

요청 미리보기

기본 URL https://www.scrapestorm.net

엔드포인트 /api/v2/google.com/maps/places-by-query

필수 매개변수

query

선택 매개변수

coordinates country_code cursor language radius_meters

예시 URL

https://www.scrapestorm.net/api/v2/google.com/maps/places-by-query?query=coffee+shops

코드 예제

curl --request GET \
  --url "https://www.scrapestorm.net/api/v2/google.com/maps/places-by-query" \
  --header "X-API-Key: 00000000-0000-4000-8000-000000000000" \
  --get --data-urlencode 'query=coffee shops' \
  # Optional parameters:
  # --data-urlencode '[email protected],-122.4194'
  # --data-urlencode 'country_code=US'
  # --data-urlencode 'cursor=eyJmaW5nZXJwcmludCI6Ii4uLiJ9.signature'
  # --data-urlencode 'language=en'
  # --data-urlencode 'radius_meters=5000'

from urllib.parse import urljoin

import requests

BASE_URL = "https://www.scrapestorm.net"
ENDPOINT = "/api/v2/google.com/maps/places-by-query"
HEADERS = {"Accept": "application/json", "X-API-Key": "00000000-0000-4000-8000-000000000000"}

params = {
    "query": "coffee shops",
}

# Optional parameters
# params["coordinates"] = "@37.7749,-122.4194"
# params["country_code"] = "US"
# params["cursor"] = "eyJmaW5nZXJwcmludCI6Ii4uLiJ9.signature"
# params["language"] = "en"
# params["radius_meters"] = "5000"

with requests.Session() as session:
    response = session.request(
        method="GET",
        url=urljoin(BASE_URL, ENDPOINT),
        headers=HEADERS,
        params=params,
        timeout=30,
    )
    response.raise_for_status()
    payload = response.json()

print(payload)

const BASE_URL = "https://www.scrapestorm.net";
const endpoint = "/api/v2/google.com/maps/places-by-query";

const params = new URLSearchParams({
  query: "coffee shops",
});

// Optional parameters
// params.set("coordinates", "@37.7749,-122.4194");
// params.set("country_code", "US");
// params.set("cursor", "eyJmaW5nZXJwcmludCI6Ii4uLiJ9.signature");
// params.set("language", "en");
// params.set("radius_meters", "5000");

const response = await fetch(`${BASE_URL}${endpoint}?${params.toString()}`, {
  method: "GET",
  headers: {
    Accept: "application/json",
    "X-API-Key": "00000000-0000-4000-8000-000000000000",
  },
});

if (!response.ok) {
  throw new Error(`Request failed: ${response.status} ${response.statusText}`);
}

const payload = await response.json();
console.log(payload);

import axios from "axios";

const client = axios.create({
  baseURL: "https://www.scrapestorm.net",
  timeout: 30000,
  headers: {
    Accept: "application/json",
    "X-API-Key": "00000000-0000-4000-8000-000000000000",
  },
});

const params = {
  query: "coffee shops",
};

// Optional parameters
// params.coordinates = "@37.7749,-122.4194";
// params.country_code = "US";
// params.cursor = "eyJmaW5nZXJwcmludCI6Ii4uLiJ9.signature";
// params.language = "en";
// params.radius_meters = "5000";

const { data: payload } = await client.request({
  method: "GET",
  url: endpoint,
  params,
});

console.log(payload);

<?php

declare(strict_types=1);

use GuzzleHttp\Client;
use GuzzleHttp\Exception\GuzzleException;

$client = new Client([
    'base_uri' => "https://www.scrapestorm.net",
    'timeout' => 30.0,
    'headers' => [
        'Accept' => 'application/json',
        'X-API-Key' => "00000000-0000-4000-8000-000000000000",
    ],
]);

$query = [
    "query" => "coffee shops",
];

// Optional parameters
// $query["coordinates"] = "@37.7749,-122.4194";
// $query["country_code"] = "US";
// $query["cursor"] = "eyJmaW5nZXJwcmludCI6Ii4uLiJ9.signature";
// $query["language"] = "en";
// $query["radius_meters"] = "5000";

try {
    $response = $client->request("GET", "/api/v2/google.com/maps/places-by-query", [
        'query' => $query,
    ]);

    $payload = json_decode(
        (string) $response->getBody(),
        true,
        512,
        JSON_THROW_ON_ERROR
    );

    var_dump($payload);
} catch (GuzzleException $e) {
    throw $e;
}

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
    "net/url"
    "time"
)

func main() {
    baseURL := "https://www.scrapestorm.net"
    endpoint := "/api/v2/google.com/maps/places-by-query"

    params := url.Values{}
    params.Set("query", "coffee shops")

    // Optional parameters
    // params.Set("radius_meters", "5000")

    req, err := http.NewRequest(
        "GET",
        fmt.Sprintf("%s%s?%s", baseURL, endpoint, params.Encode()),
        nil,
    )
    if err != nil {
        panic(err)
    }

    req.Header.Set("Accept", "application/json")
    req.Header.Set("X-API-Key", "00000000-0000-4000-8000-000000000000")

    client := &http.Client{Timeout: 30 * time.Second}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    var payload any
    if err := json.NewDecoder(resp.Body).Decode(&payload); err != nil {
        panic(err)
    }

    fmt.Printf("%+v\n", payload)
}

응답 예시

버전별 실제 응답

미리보기에는 주요 필드와 컬렉션의 첫 항목이 포함되어 있어 응답 형태를 빠르게 확인할 수 있습니다. 버전을 바꾸면 JSON 형식이 바뀝니다.

응답 예시

V2 응답 JSON

검증된 예시

이 간결한 JSON 예시는 V2의 최근 성공한 검증 실행에서 가져왔습니다.

{
  "success": true,
  "status": "ok",
  "pagination": {
    "cursor": "QVFB...",
    "has_more": true
  },
  "search_context": {
    "language": "en",
    "country_code": "us",
    "query": "coffee san francisco"
  },
  "data": {
    "places": {
      "count": 20,
      "items": [
        {
          "rank": 1,
          "company_id": "5181132708478222499",
          "name": "The Coffee Berry SF",
          "feature_id": "0x80858135f0db680b:0x47e714bf5f0080a3",
          "place_id": "ChIJC2jb8DWBhYARo4AAX78U50c",
          "rating": 4.9,
          "categories": [
            "Coffee shop"
          ],
          "category_code": "coffee",
          "tags": [
            "Dogs allowed"
          ],
          "formatted_address": "1410 Lombard St, San Francisco, CA 94123",
          "address": {
            "street_address": "1410 Lombard St",
            "locality": "San Francisco",
            "postal_code": "94123",
            "region": "California",
            "country_code": "US"
          },
          "full_address": "The Coffee Berry SF, 1410 Lombard St, San Francisco, CA 94123",
          "address_lines": [
            "1410 Lombard St",
            "San Francisco, CA 94123"
          ],
          "neighborhood": "Marina District",
          "locality": "San Francisco",
          "coordinates": {
            "latitude": 37.8014124,
            "longitude": -122.4249979
          },
          "timezone": "America/Los_Angeles",
          "phone_number": "+1 415-800-7073",
          "website_url": "http://thecoffeeberrysf.com/",
          "website_host": "thecoffeeberrysf.com",
          "google_maps_url": "https://www.google.com/maps/place/?q=place_id:ChIJC2jb8DWBhYARo4AAX78U50c",
          "opening_hours": {
            "open_now_text": "Open",
            "hours_summary": "Open · Closes 6 PM",
            "today_hours": [
              "7 AM–6 PM"
            ]
          },
          "accessibility_features": [
            {
              "code": "/geo/type/establishment_poi/has_wheelchair_accessible_entrance",
              "label": "Wheelchair accessible entrance",
              "available": true
            },
            {
              "code": "/geo/type/establishment_poi/has_wheelchair_accessible_parking",
              "label": "Wheelchair accessible parking lot",
              "available": true
            },
            {
              "_more_items": 3
            }
          ],
          "business_highlights": [
            "LGBTQ+ friendly",
            "Identifies as Latino-owned"
          ],
          "_more_fields": "1 more fields"
        },
        {
          "rank": 2,
          "company_id": "2067360649617373617",
          "name": "The Coffee Movement",
          "feature_id": "0x808580f2dc1b33a1:0x1cb0bd8eb71079b1",
          "place_id": "ChIJoTMb3PKAhYARsXkQt469sBw",
          "rating": 4.7,
          "categories": [
            "Coffee shop"
          ],
          "category_code": "coffee",
          "tags": [
            "Snug, minimalist cafe for artisan brews"
          ],
          "formatted_address": "1030 Washington St, San Francisco, CA 94108",
          "address": {
            "street_address": "1030 Washington St",
            "locality": "San Francisco",
            "postal_code": "94108",
            "region": "California",
            "country_code": "US"
          },
          "full_address": "The Coffee Movement, 1030 Washington St, San Francisco, CA 94108",
          "address_lines": [
            "1030 Washington St",
            "San Francisco, CA 94108"
          ],
          "neighborhood": "Nob Hill",
          "locality": "San Francisco",
          "coordinates": {
            "latitude": 37.7947671,
            "longitude": -122.4102942
          },
          "timezone": "America/Los_Angeles",
          "phone_number": null,
          "website_url": "https://www.thecoffeemovement.com/",
          "website_host": "thecoffeemovement.com",
          "google_maps_url": "https://www.google.com/maps/place/?q=place_id:ChIJoTMb3PKAhYARsXkQt469sBw",
          "opening_hours": {
            "open_now_text": "Open",
            "hours_summary": "Open · Closes 4 PM",
            "today_hours": [
              "7 AM–4 PM"
            ]
          },
          "accessibility_features": [
            {
              "code": "/geo/type/establishment_poi/has_wheelchair_accessible_entrance",
              "label": "Wheelchair accessible entrance",
              "available": true
            },
            {
              "code": "/geo/type/establishment_poi/has_wheelchair_accessible_parking",
              "label": "Wheelchair accessible parking lot",
              "available": false
            },
            {
              "_more_items": 1
            }
          ],
          "business_highlights": null,
          "_more_fields": "1 more fields"
        },
        {
          "_more_items": 18
        }
      ]
    }
  }
}

지도 작업 계속하기

관련 메서드는 같은 객체를 다른 식별자로 찾거나, 세부 정보를 열거나, 집계 보기로 전환합니다.

다음 단계

평가 계속하기

이 문서를 첫 판단 기준으로 삼고, 반복 사용을 위해 엔드포인트를 연결하기 전에 요금, 플랫폼 지원 범위, 연동 규칙을 확인하세요.

Google 플랫폼 페이지 열기

구현 전에 관련 엔터티, API 메서드 그룹, 관련 문서를 비교하세요.

플랫폼 페이지 열기

API 메서드 요금 비교

사용량을 늘리기 전에 공개 요금표에서 이 메서드의 위치를 확인하세요.

요금 보기

연동 규칙 확인

시작 문서에서 인증, 버전, 재시도, 테스트와 운영의 차이를 확인하세요.

문서 열기

자주 묻는 질문

팀이 구현 전에 묻는 질문

이 답변을 참고하여 이 API 메서드가 워크플로, 버전 선택, 도입 계획에 맞는지 판단하세요.

이 Google API 메서드는 어떤 데이터를 반환하나요?

이 메서드는 지도에 대해 "검색어별 장소"을 실행합니다. 아래의 간결한 응답 예시에서 필드의 정확한 구조를 확인할 수 있습니다.

V1과 V2 중 무엇을 선택해야 하나요?

새 연동에는 정규화된 구조를 제공하는 V2를 선택하세요. V1은 이미 플랫폼 고유 형식을 처리하는 클라이언트와의 호환성을 위해서만 사용하세요.

첫 요청에는 무엇이 필요한가요?

API 키를 만들어 요청 헤더에 넣고 표의 필수 매개변수를 입력하세요. 코드 예제에는 이미 올바른 경로와 요청 구조가 포함되어 있습니다.