附近搜索(旧版)

欧洲经济区 (EEA) 开发者

通过附近搜索(旧版),您可以搜索指定区域内的地点。您可以通过提供关键字或指定要搜索的地点类型来优化搜索请求。

“附近搜索(旧版)”请求

附近搜索(旧版)请求是采用以下格式的 HTTP 网址:

https://maps.googleapis.com/maps/api/place/nearbysearch/output?parameters

其中 output 可以是以下任一值:

  • json(推荐)表示以 JavaScript 对象表示法 (JSON) 格式输出
  • xml 表示输出为 XML

发起附近搜索(旧版)请求时,必须提供某些参数。依照网址的标准,所有参数都使用“与”符号 (&) 分隔。

必需参数

  • 地理位置

    要检索其周围地点信息的点。此值必须指定为 latitude,longitude。

  • 半径

    定义返回地点结果的距离(以米为单位)。您可以传递 location 和 radius 参数,使结果偏向指定圆形区域。这样做会指示地点服务优先显示该圆形区域内的结果;指定区域以外的结果可能仍会显示。

    半径将根据搜索类型和其他参数自动限制为最大值。

    • 自动补全:50,000 米
    • 附近搜索:
      • 使用 keyword 或 name:50,000 米
      • 不含 keyword 或 name
        • 最大 50,000 米,根据区域密度动态调整,与 rankby 参数无关。
        • 使用 rankby=distance 时,系统不接受 radius 参数,并会返回 INVALID_REQUEST。
    • 查询自动补全:50,000 米
    • 文本搜索:50,000 米

可选参数

  • 关键字

    要搜索的文本字符串,例如“餐馆”或“长安街 123 号”。该参数必须是地点名称、地址或场所类别。任何其他类型的输入都可能产生错误,并且不能保证返回有效结果。Google 地点服务将根据此字符串返回候选匹配结果,并按照其判断的相关性对结果进行排序。

    使用此参数明确添加位置信息可能会与 location、radius 和 rankby 参数冲突,从而导致意外结果。

    如果省略此参数,则不会返回 business_status 为 CLOSED_TEMPORARILY 或 CLOSED_PERMANENTLY 的地点。

  • language

    返回结果时所用的语言。

    • 请参阅支持的语言列表。Google 会经常更新支持的语言,因此该列表可能并非详尽无遗。
    • 如果未提供 language,API 会尝试使用 Accept-Language 标头中指定的首选语言。
    • 该 API 会尽力提供用户和当地人都能看懂的街道地址。为实现此目标,它会以本地语言返回街道地址,并在必要时将其音译为用户可读的文字,同时遵循首选语言。所有其他地址均以首选语言返回。地址组成部分均以同一种语言返回,该语言是从第一个组成部分中选择的。
    • 如果首选语言中没有名称,API 会使用最接近的匹配项。
    • 首选语言对 API 选择返回的结果集以及返回顺序有轻微影响。地理编码器会根据语言以不同的方式解读缩写,例如街道类型的缩写,或可能在一种语言中有效但在另一种语言中无效的同义词。例如,utca 和 tér 在匈牙利语中是“街道”的同义词。
  • maxprice

    将结果限制为仅包含指定范围内的地点。有效值的范围介于 0(最实惠)和 4(最昂贵)之间,包括 0 和 4。特定值表示的确切金额因地区而异。

  • minprice

    将结果限制为仅包含指定范围内的地点。有效值的范围介于 0(最实惠)和 4(最昂贵)之间,包括 0 和 4。特定值所表示的确切金额因地区而异。

  • name

    等同于 keyword。此字段中的值会与 keyword 字段中的值合并,作为同一搜索字符串的一部分进行传递。

  • opennow

    仅返回那些在发送查询时开门营业的地点。如果您在查询中包含此参数,系统不会返回那些未在 Google 地点数据库中指定营业时间的地点。

  • pagetoken

    从之前运行的搜索中返回最多 20 条结果。设置 pagetoken 参数会使用之前使用的相同参数执行搜索,系统会忽略 pagetoken 以外的所有参数。

  • rankby

    指定结果的列出顺序。可能的值包括:

    • prominence(默认)。此选项可根据重要性对结果排序。系统会优先列出指定半径范围内的知名地点,而不是虽然匹配但不那么知名的附近地点。知名度受 Google 索引中的地点排名、全球知名度和其他因素的影响。指定 prominence 时,必须提供 radius 参数。
    • distance。此选项会根据结果与指定位置之间的距离按升序对搜索结果进行偏向。指定 distance 时,必须提供一个或多个 keyword、name 或 type,并且不允许提供 radius。
  • 类型

    将结果限制为与指定类型相匹配的地点。您只能指定一种类型。如果您提供多个类型,则 API 会忽略第一个条目之后的所有类型。

    • type=hospital|pharmacy|doctor 替换为 type=hospital
    • type=hospital,pharmacy,doctor 会被完全忽略

    请参阅支持的类型列表。

    注意:同时添加具有相同值(keyword=cafe&type=cafe 或 keyword=parking&type=parking)的 keyword 和 type 可能会产生 ZERO_RESULTS。

附近搜索(旧版)示例

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/nearbysearch/json?location=-33.8670522%2C151.1957362&radius=1500&type=restaurant&keyword=cruise&key=YOUR_API_KEY'

HTTP

https://maps.googleapis.com/maps/api/place/nearbysearch/json
  ?keyword=cruise
  &location=-33.8670522%2C151.1957362
  &radius=1500
  &type=restaurant
  &key=YOUR_API_KEY

注意:在此示例中,您需要将 key 替换为您自己的 API 密钥,以便请求在您的应用中正常运行。

附近搜索(旧版)响应

以下示例展示了附近搜索(旧版)响应。

JSON

{
  "html_attributions": [],
  "results":
    [
      {
        "business_status": "OPERATIONAL",
        "geometry":
          {
            "location": { "lat": -33.8587323, "lng": 151.2100055 },
            "viewport":
              {
                "northeast":
                  { "lat": -33.85739847010727, "lng": 151.2112436298927 },
                "southwest":
                  { "lat": -33.86009812989271, "lng": 151.2085439701072 },
              },
          },
        "icon": "https://maps.gstatic.com/mapfiles/place_api/icons/v1/png_71/bar-71.png",
        "icon_background_color": "#FF9E67",
        "icon_mask_base_uri": "https://maps.gstatic.com/mapfiles/place_api/icons/v2/bar_pinlet",
        "name": "Cruise Bar",
        "opening_hours": { "open_now": false },
        "photos":
          [
            {
              "height": 608,
              "html_attributions":
                [
                  'A Google User',
                ],
              "photo_reference": "Aap_uECvJIZuXT-uLDYm4DPbrV7gXVPeplbTWUgcOJ6rnfc4bUYCEAwPU_AmXGIaj0PDhWPbmrjQC8hhuXRJQjnA1-iREGEn7I0ZneHg5OP1mDT7lYVpa1hUPoz7cn8iCGBN9MynjOPSUe-UooRrFw2XEXOLgRJ-uKr6tGQUp77CWVocpcoG",
              "width": 1080,
            },
          ],
        "place_id": "ChIJi6C1MxquEmsR9-c-3O48ykI",
        "plus_code":
          {
            "compound_code": "46R6+G2 The Rocks, New South Wales",
            "global_code": "4RRH46R6+G2",
          },
        "price_level": 2,
        "rating": 4,
        "reference": "ChIJi6C1MxquEmsR9-c-3O48ykI",
        "scope": "GOOGLE",
        "types":
          ["bar", "restaurant", "food", "point_of_interest", "establishment"],
        "user_ratings_total": 1269,
        "vicinity": "Level 1, 2 and 3, Overseas Passenger Terminal, Circular Quay W, The Rocks",
      },
      {
        "business_status": "OPERATIONAL",
        "geometry":
          {
            "location": { "lat": -33.8675219, "lng": 151.2016502 },
            "viewport":
              {
                "northeast":
                  { "lat": -33.86614532010728, "lng": 151.2031259298927 },
                "southwest":
                  { "lat": -33.86884497989272, "lng": 151.2004262701072 },
              },
          },
        "icon": "https://maps.gstatic.com/mapfiles/place_api/icons/v1/png_71/generic_business-71.png",
        "icon_background_color": "#7B9EB0",
        "icon_mask_base_uri": "https://maps.gstatic.com/mapfiles/place_api/icons/v2/generic_pinlet",
        "name": "Sydney Harbour Dinner Cruises",
        "opening_hours": { "open_now": true },
        "photos":
          [
            {
              "height": 835,
              "html_attributions":
                [
                  'A Google User',
                ],
              "photo_reference": "Aap_uEBVsYnNcrpRixtrlHBztigZh70CwYkNWZzQnqJ39SjeBo_wvgKf-kXc6tgaMLBdQrRKmxmSKjOezoZrv-sHKVbTX0OI48HBqYYVnQiZQ-WGeuQDsLEPwX7LaVPa68nUAxX114Zpqt7bryoO9wL4qXdgEnopbOp5WWLALhKEHoIEH7f7",
              "width": 1200,
            },
          ],
        "place_id": "ChIJM1mOVTS6EmsRKaDzrTsgids",
        "plus_code":
          {
            "compound_code": "46J2+XM Sydney, New South Wales",
            "global_code": "4RRH46J2+XM",
          },
        "rating": 4.8,
        "reference": "ChIJM1mOVTS6EmsRKaDzrTsgids",
        "scope": "GOOGLE",
        "types":
          [
            "tourist_attraction",
            "travel_agency",
            "restaurant",
            "food",
            "point_of_interest",
            "establishment",
          ],
        "user_ratings_total": 9,
        "vicinity": "32 The Promenade, Sydney",
      },
      // ...
    ],
  "status": "OK",
}
    

XML

<?xml version="1.0" encoding="UTF-8"?>
<PlaceSearchResponse>
 <status>OK</status>
 <result>
  <name>Cruise Bar</name>
  <vicinity>Level 1, 2 and 3, Overseas Passenger Terminal, Circular Quay W, The Rocks</vicinity>
  <type>bar</type>
  <type>restaurant</type>
  <type>food</type>
  <type>point_of_interest</type>
  <type>establishment</type>
  <geometry>
   <location>
    <lat>-33.8587323</lat>
    <lng>151.2100055</lng>
   </location>
   <viewport>
    <southwest>
     <lat>-33.8600981</lat>
     <lng>151.2085440</lng>
    </southwest>
    <northeast>
     <lat>-33.8573985</lat>
     <lng>151.2112436</lng>
    </northeast>
   </viewport>
  </geometry>
  <rating>4.0</rating>
  <icon>https://maps.gstatic.com/mapfiles/place_api/icons/v1/png_71/bar-71.png</icon>
  <reference>ChIJi6C1MxquEmsR9-c-3O48ykI</reference>
  <opening_hours>
   <open_now>false</open_now>
  </opening_hours>
  <photo>
   <photo_reference>Aap_uEALIq4sgBHhIYWWapOH2NV1T2I7YdOiLzEH7z-483I764cId1sZkbzSq-hVYTk1PQeaHuZzlRfA7-ilwJ3QWon4b37ePd-PBwZbOwFZHxhYs0Cs7jRSgMHWfOzGivp6ZFG4iupyz50qS5pBZT1WbA2ufacTq_U21TtgffQD31wKRPQk</photo_reference>
   <width>1080</width>
   <height>608</height>
   <html_attribution>&lt;a href=&quot;https://maps.google.com/maps/contrib/112582655193348962755&quot;&gt;A Google User&lt;/a&gt;</html_attribution>
  </photo>
  <price_level>2</price_level>
  <user_ratings_total>1269</user_ratings_total>
  <place_id>ChIJi6C1MxquEmsR9-c-3O48ykI</place_id>
  <scope>GOOGLE</scope>
  <plus_code>
   <global_code>4RRH46R6+G2</global_code>
   <compound_code>46R6+G2 The Rocks, New South Wales</compound_code>
  </plus_code>
  <icon_background_color>#FF9E67</icon_background_color>
  <business_status>OPERATIONAL</business_status>
  <icon_mask_base_uri>https://maps.gstatic.com/mapfiles/place_api/icons/v2/bar_pinlet</icon_mask_base_uri>
 </result>
 <result>
  <name>Sydney Harbour Dinner Cruises</name>
  <vicinity>32 The Promenade, Sydney</vicinity>
  <type>tourist_attraction</type>
  <type>restaurant</type>
  <type>food</type>
  <type>travel_agency</type>
  <type>point_of_interest</type>
  <type>establishment</type>
  <geometry>
   <location>
    <lat>-33.8675219</lat>
    <lng>151.2016502</lng>
   </location>
   <viewport>
    <southwest>
     <lat>-33.8688450</lat>
     <lng>151.2004263</lng>
    </southwest>
    <northeast>
     <lat>-33.8661453</lat>
     <lng>151.2031259</lng>
    </northeast>
   </viewport>
  </geometry>
  <rating>4.8</rating>
  <icon>https://maps.gstatic.com/mapfiles/place_api/icons/v1/png_71/generic_business-71.png</icon>
  <reference>ChIJM1mOVTS6EmsRKaDzrTsgids</reference>
  <opening_hours>
   <open_now>true</open_now>
  </opening_hours>
  <photo>
   <photo_reference>Aap_uEB5jH7GXdcozv1Y5HX18syo4f128S58NVUnqBbLJMpWbC39K49wp-wzsLOsUT8QKDaag6ISFL8hl1vVuig4jkc5fMMkWKiqw5PY-ebcWZ5tI3gEXEYGGoG_mDAulaMLudUpSwgBx2_RLnA0SSiugqqQUTYlkGyCZSe8HSyngVczy6XN</photo_reference>
   <width>1200</width>
   <height>835</height>
   <html_attribution>&lt;a href=&quot;https://maps.google.com/maps/contrib/109764923610545394994&quot;&gt;A Google User&lt;/a&gt;</html_attribution>
  </photo>
  <user_ratings_total>9</user_ratings_total>
  <place_id>ChIJM1mOVTS6EmsRKaDzrTsgids</place_id>
  <scope>GOOGLE</scope>
  <plus_code>
   <global_code>4RRH46J2+XM</global_code>
   <compound_code>46J2+XM Sydney, New South Wales</compound_code>
  </plus_code>
  <icon_background_color>#7B9EB0</icon_background_color>
  <business_status>OPERATIONAL</business_status>
  <icon_mask_base_uri>https://maps.gstatic.com/mapfiles/place_api/icons/v2/generic_pinlet</icon_mask_base_uri>
 </result>
 <!-- ... -->
</PlaceSearchResponse>

    

PlacesNearbySearchResponse

字段 必填 类型 说明
required Array<string>

可能包含一组关于此商家信息的提供方信息,这些信息必须向用户显示(某些商家信息可能没有提供方信息)。

required Array<Place>

包含地点数组。

“地点搜索”请求会返回“地点详情”请求返回的部分字段。如果“地点搜索”未返回您所需的字段,您可以使用“地点搜索”获取 place_id,然后使用该地点 ID 发出“地点详情”请求。

如需了解详情,请参阅地点。

required PlacesSearchStatus

包含请求的状态,可能还包含调试信息,以帮助您跟踪请求失败的原因。

如需了解详情,请参阅 PlacesSearchStatus。

可选 字符串

当服务返回 OK< 以外的状态代码时,响应对象中可能会有一个额外的 error_message 字段。此字段包含有关给定状态代码背后原因的更详细信息。此字段不一定会返回,其内容可能会发生变化。

可选 Array<string>

当服务返回有关请求规范的其他信息时,响应对象中可能会有一个额外的 info_messages 字段。只有成功的请求才会返回此字段。它可能并不总是返回,其内容可能会发生变化。

可选 字符串

包含一个令牌,可用于返回最多 20 个额外结果。如果没有其他结果可显示,则不会返回 next_page_token。可返回的结果数上限为 60。从发出 next_page_token 到其生效之间存在短暂的延迟。

PlacesSearchStatus

服务返回的状态代码。

  • OK:表示 API 请求成功。
  • ZERO_RESULTS,表示搜索成功,但未返回任何结果。如果向搜索传递了远程位置中的 latlng,就可能会发生这种情况。
  • INVALID_REQUEST:表示 API 请求格式不正确,通常是因为缺少必需的查询参数(location 或 radius)。
  • OVER_QUERY_LIMIT,表示以下任一情况:
    • 您已超出 QPS 限制。
    • 您的账号尚未启用结算功能。
    • 超出了每月 200 美元的赠金或您设定的用量上限。
    • 提供的付款方式不再有效(例如,信用卡已过期)。
    如需详细了解如何解决此错误,请参阅地图常见问题解答。
  • REQUEST_DENIED:表示您的请求已遭拒,通常是因为:
    • 请求中缺少 API 密钥。
    • key 参数无效。
  • UNKNOWN_ERROR:表示出现未知错误。

地点

地点搜索响应会返回以下地点字段子集。并非所有属性都适用于所有地点类型。如需检索地点搜索未返回的字段(例如 address_components、formatted_phone_number、reviews 或 website),请在地点详情(旧版)请求中传递返回的 place_id。如需了解各个端点的字段可用性和价格层级,请参阅地点数据字段(旧版)。

字段 类型 说明
business_status string 指示地点的营业状态(如果该地点为商家):OPERATIONAL、CLOSED_TEMPORARILY 或 CLOSED_PERMANENTLY。如果不存在状态数据,则省略。
formatted_address string 此地点人类可读的地址。由文本搜索(旧版)和查找地点(旧版)返回。请勿以程序化方式解析设有格式的地址,而应在地点详情(旧版)中请求 address_components。
geometry Geometry 包含具有 lat 和 lng 坐标的经过地理编码的 location,以及具有 northeast 和 southwest 边界的首选 viewport。
icon string 建议图标的网址,您可以在地图上指示此结果时显示该图标。
icon_background_color string 地点类别的默认十六进制颜色代码。
icon_mask_base_uri string 推荐图标的基础网址,不含 SVG 或 PNG 文件类型扩展名。
name string 返回结果的人类可读名称。对于 establishment 结果,此值通常是规范化的商家名称。
opening_hours PlaceOpeningHours 营业时间信息。地点搜索端点仅返回 open_now 布尔值子字段;在地点详情(旧版)中请求 periods 和 weekday_text 的 opening_hours。
permanently_closed boolean 已弃用:请使用 business_status 检查商家的营业状态。
photos Array<PlacePhoto> PlacePhoto 对象数组,每个对象包含 photo_reference、height、width 和 html_attributions。如需了解使用详情,请参阅地点照片(旧版)。
place_id string 用于唯一标识地点的文本标识符。在地点详情(旧版)请求的 place_id 参数中传递此 ID。请参阅地点 ID 概览。
plus_code PlusCode 衍生自纬度和经度坐标的经过编码的位置引用,包含 global_code 和可选的 compound_code。
price_level integer 地点的价格水平,范围为 0 到 4,从最便宜到最贵。请参阅 price_level。
rating number 根据用户总体评价得出的地点评分(从 1.0 到 5.0)。
reference string 已弃用:请改用 place_id。
scope string 已弃用:指示 place_id 的范围,始终为 GOOGLE。由附近搜索(旧版)返回。
types Array<string> 描述给定结果的特征类型数组。请参阅地点类型(旧版)。
user_ratings_total integer 此地点的评分总数(无论是否包含评价文字)。
vicinity string 地点的简化地址,包括街道名称、门牌号和市行政区,但不包括州或省、邮政编码或国家/地区。由附近搜索(旧版)返回。

访问其他结果

默认情况下,对于每个响应,每次查询可返回最多 20 条 establishment 结果;但是,每个搜索可以返回多达 60 条结果,分三页显示。如果搜索返回的结果超过 20 个,则搜索响应将包含一个额外的值:next_page_token。将 next_page_token 的值传递给新请求的 pagetoken 参数,即可查看下一组结果。

  • 如果 next_page_token 为 null 或未返回,则表示没有更多结果。
  • 使用相同的 next_page_token 重试请求将返回下一页结果。
  • 设置 pagetoken 会导致系统忽略任何其他参数。
  • 在原始查询之后,您最多可以请求两次新页面。
  • 每个请求(包括使用 next_page_token 的请求)都算作用量限额中的一次请求,并单独收费。
  • 从 next_page_token 颁发到其生效之间有几秒钟的延迟。在下一页可用之前请求该页将返回 INVALID_REQUEST 响应。包含 next_page_token 的请求始终会产生费用。

例如,在以下查询中,我们搜索澳大利亚悉尼达令港附近的餐厅,并按距离对结果进行排名。您可以看到,响应包含 next_page_token 属性。

{
   "html_attributions" : [],
   "next_page_token" : "CpQCAgEAAFxg8o-eU7_uKn7Yqjana-HQIx1hr5BrT4zBaEko29ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk-ReY7oulyuvKSQrw1lgJElggGlo0d6indiH1U-tDwquw4tU_UXoQ_sj8OBo8XBUuWjuuFShqmLMP-0W59Vr6CaXdLrF8M3wFR4dUUhSf5UC4QCLaOMVP92lyh0OdtF_m_9Dt7lz-Wniod9zDrHeDsz_by570K3jL1VuDKTl_U1cJ0mzz_zDHGfOUf7VU1kVIs1WnM9SGvnm8YZURLTtMLMWx8-doGUE56Af_VfKjGDYW361OOIj9GmkyCFtaoCmTMIr5kgyeUSnB-IEhDlzujVrV6O9Mt7N4DagR6RGhT3g1viYLS4kO5YindU6dm3GIof1Q",
   "results" : [...]
   "status" : "OK"
}

如需查看下一组结果,您可以提交新查询,并将 next_page_token 的结果传递给 pagetoken 参数。例如:

https://maps.googleapis.com/maps/api/place/nearbysearch/json?pagetoken=CpQCAgEAAFxg8o-eU7_uKn7Yqjana-HQIx1hr5BrT4zBaEko29ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk-ReY7oulyuvKSQrw1lgJElggGlo0d6indiH1U-tDwquw4tU_UXoQ_sj8OBo8XBUuWjuuFShqmLMP-0W59Vr6CaXdLrF8M3wFR4dUUhSf5UC4QCLaOMVP92lyh0OdtF_m_9Dt7lz-Wniod9zDrHeDsz_by570K3jL1VuDKTl_U1cJ0mzz_zDHGfOUf7VU1kVIs1WnM9SGvnm8YZURLTtMLMWx8-doGUE56Af_VfKjGDYW361OOIj9GmkyCFtaoCmTMIr5kgyeUSnB-IEhDlzujVrV6O9Mt7N4DagR6RGhT3g1viYLS4kO5YindU6dm3GIof1Q&key=YOUR_API_KEY