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 方法在公开价格表中的位置。

查看价格

查看集成规则

通过入门文档确认身份验证、版本管理、重试以及模拟环境与正式环境的差异。

打开文档

常见问题

团队在实现前常问的问题

借助这些解答，判断此 API 方法是否适合您的工作流、版本选择和上线计划。

此 Google API 方法返回哪些数据？

该方法针对地图执行“按查询获取场所”操作。下方的简明响应示例展示了确切的字段结构。

应该选择 V1 还是 V2？

新集成请选择 V2，因为它提供规范化的结构。仅在兼容已使用平台原生格式的客户端时使用 V1。

第一个请求需要准备什么？

创建 API 密钥，在请求头中发送它，并提供表格中的必填参数。代码示例中已包含正确的路径和请求结构。