Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Nearby Search (新版)

選取平台： Android iOS JavaScript 網頁服務

歐洲經濟區 (EEA) 開發人員

簡介

Nearby Search (新版) 要求會採用一或多個地點類型，並傳回指定區域內相符地點的清單。您必須提供欄位遮罩，指定一或多個資料類型。Nearby Search (新版) 僅支援 POST 要求。

您可以使用 APIs Explorer 傳送即時要求，熟悉 API 和 API 選項：

試試看！

請試用互動式示範，在地圖上查看 Nearby Search (New) 結果。

Nearby Search (新版) 要求

Nearby Search (新版) 要求是向以下形式的網址發出的 HTTP POST 要求：

https://places.googleapis.com/v1/places:searchNearby

在 POST 要求中，將所有參數傳遞至 JSON 要求內文或標頭。例如：

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965},
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

Nearby Search (新版) 回應

Nearby Search (新版) 會以 JSON 物件的形式傳回回應。在回應中：

places 陣列包含所有相符的地點。
陣列中的每個地點都以 Place 物件表示。Place 物件包含單一地點的詳細資訊。
要求中傳遞的 FieldMask 會指定 Place 物件中傳回的欄位清單。

完整的 JSON 物件格式如下：

{
  "places": [
    {
      object (Place)
    }
  ]
}

必要參數

FieldMask

建立回應欄位遮罩，指定要在回應中傳回的欄位清單。使用網址參數 $fields 或 fields，或使用 HTTP 標頭 X-Goog-FieldMask，將回應欄位遮罩傳遞至方法。回應中沒有預設的傳回欄位清單。如果省略欄位遮罩，這個方法會傳回錯誤。

欄位遮蓋是良好的設計做法，可確保您不會要求不必要的資料，有助於避免不必要的處理時間和帳單費用。

指定要傳回的地點資料類型清單，並以半形逗號分隔。舉例來說，如要擷取地點的顯示名稱和地址，請使用下列程式碼：
```
X-Goog-FieldMask: places.displayName,places.formattedAddress
```
注意： 欄位清單中不得有任何空格。

使用 * 擷取所有欄位。
```
X-Goog-FieldMask: *
```
雖然在開發階段使用萬用字元 (*) 沒問題，但 Google 不建議在正式環境中使用萬用字元回應欄位遮罩，因為這樣可能會傳回大量資料。
如要進一步瞭解如何使用 places.iconMaskBaseUri 和 places.iconBackgroundColor，請參閱「地點圖示」一節。

指定下列一或多個欄位：
- 下列欄位會觸發 Nearby Search Pro SKU：
  
  places.accessibilityOptions
  places.addressComponents
  places.addressDescriptor^*
  places.adrFormatAddress
  places.attributions
  places.businessStatus
  places.containingPlaces
  places.displayName
  places.formattedAddress
  places.googleMapsLinks
  places.googleMapsUri
  places.iconBackgroundColor
  places.iconMaskBaseUri
  places.id
  places.location
  places.name^**
  places.movedPlace
  places.movedPlaceId
  places.openingDate
  places.photos
  places.plusCode
  places.postalAddress
  places.primaryType
  places.primaryTypeDisplayName
  places.pureServiceAreaBusiness
  places.shortFormattedAddress
  places.subDestinations
  places.timeZone
  places.types
  places.utcOffsetMinutes
  places.viewport
  
  ^* 地址描述符通常適用於印度境內的客戶，其他地區則為實驗功能。
  
  ^** places.name 欄位包含地點資源名稱，格式為：places/PLACE_ID。使用 places.displayName 存取地點的文字名稱。
- 下列欄位會觸發 Nearby Search Enterprise SKU：
  
  places.currentOpeningHours
  places.currentSecondaryOpeningHours
  places.internationalPhoneNumber
  places.nationalPhoneNumber
  places.priceLevel
  places.priceRange
  places.rating
  places.regularOpeningHours
  places.regularSecondaryOpeningHours
  places.transitStation
  places.userRatingCount
  places.websiteUri
- 下列欄位會觸發 Nearby Search Enterprise + Atmosphere SKU：
  
  places.allowsDogs
  places.curbsidePickup
  places.delivery
  places.dineIn
  places.editorialSummary
  places.evChargeAmenitySummary
  places.evChargeOptions
  places.fuelOptions
  places.generativeSummary
  places.goodForChildren
  places.goodForGroups
  places.goodForWatchingSports
  places.liveMusic
  places.menuForChildren
  places.neighborhoodSummary
  places.parkingOptions
  places.paymentOptions
  places.outdoorSeating
  places.reservable
  places.restroom
  places.reviews
  places.reviewSummary
  routingSummaries^*
  places.servesBeer
  places.servesBreakfast
  places.servesBrunch
  places.servesCocktails
  places.servesCoffee
  places.servesDessert
  places.servesDinner
  places.servesLunch
  places.servesVegetarianFood
  places.servesWine
  places.takeout
  
  ^* 僅限文字搜尋和附近搜尋
locationRestriction

要搜尋的區域，指定為圓形，並以聚焦點和半徑 (以公尺為單位) 定義。半徑必須介於 0.0 至 50000.0 之間 (含首尾)。預設半徑為 0.0。您必須在要求中將其設為大於 0.0 的值。

例如：
```
"locationRestriction": {
  "circle": {
    "center": {
      "latitude": 37.7937,
      "longitude": -122.3965
    },
    "radius": 500.0
  }
}
```

選用參數

includeFutureOpeningBusinesses

如果 true，則會傳回預計在未來開幕的商家。預設為 false。

如要擷取營業狀態，請在要求欄位遮罩中加入 places.businessStatus。如要擷取商家的預計開幕日期，請在要求欄位遮罩中加入 places.openingDate。
includedTypes/excludedTypes、includedPrimaryTypes/excludedPrimaryTypes

可讓您從類型清單中指定類型，以篩選搜尋結果。表 A每個類型限制類別最多可指定 50 個類型。

注意： 只有在回應中，才會傳回表格 B 的值。您無法使用表 B 中的值做為篩選條件。

一個地點只能有一個主要類型，且該類型必須與表 A 中的類型相關聯。舉例來說，主要類型可能是 "mexican_restaurant" 或 "steak_house"。使用 includedPrimaryTypes 和 excludedPrimaryTypes 依地點的主要類型篩選結果。

一個地點也可以有多個類型值，這些值來自與該地點相關聯的類型表 A。舉例來說，餐廳可能具有下列類型： "seafood_restaurant"、"restaurant"、"food"、 "point_of_interest"、"establishment"。使用 includedTypes 和 excludedTypes 篩選與地點相關聯的類型清單結果。

指定一般主要類型 (例如 "restaurant" 或 "hotel") 時，回應可能包含主要類型比指定類型更具體的地點。舉例來說，您指定要納入 "restaurant" 的主要類型。回覆內容隨後可能會包含主要類型為 "restaurant" 的地點，但回覆內容也可能包含主要類型更具體的地點，例如 "chinese_restaurant" 或 "seafood_restaurant"。

如果搜尋條件指定多項類型限制，系統只會傳回符合所有限制的地點。舉例來說，如果您指定 {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}，傳回的地點會提供 "restaurant" 相關服務，但主要業務並非 "steak_house"。

如果從要求中省略 includedTypes、excludedTypes、includedPrimaryTypes 和 excludedPrimaryTypes，搜尋結果會傳回位置限制範圍內所有類型的地點。

includedTypes

以半形逗號分隔的清單，列出要搜尋的表 A 地點類型。如果省略這個參數，系統會傳回所有類型的地點。

excludedTypes

以半形逗號分隔的清單，列出要從搜尋中排除的表 A 地點類型。

如果在要求中同時指定 includedTypes ( 例如 "school") 和 excludedTypes (例如 "primary_school")，則回應會包含歸類為 "school" 但不屬於 "primary_school" 的地點。回應會包含至少一個符合 includedTypes 的地點，以及沒有符合 excludedTypes 的地點。

如有任何衝突的型別 (例如同時出現在 includedTypes 和 excludedTypes 中的型別)，系統會傳回 INVALID_REQUEST 錯誤。

includedPrimaryTypes

以半形逗號分隔的清單，列出要納入搜尋範圍的表 A 主要地點類型。

excludedPrimaryTypes

以逗號分隔的清單，列出要從搜尋中排除的表 A 主要地點類型。

如有任何衝突的主要類型 (例如同時出現在 includedPrimaryTypes 和 excludedPrimaryTypes 中的類型)，系統會傳回 INVALID_ARGUMENT 錯誤。
languageCode

傳回結果時使用的語言。
- 請參閱支援語言清單。Google 會經常更新支援的語言，因此這份清單可能不完整。
- 如未提供 languageCode，API 會預設為 en。如果指定無效的語言代碼，API 會傳回 INVALID_ARGUMENT 錯誤。
- API 會盡量提供使用者和當地人都能辨識的街道地址。為達成這個目標，系統會以當地語言傳回街道地址，並視需要轉譯成使用者可讀取的文字，同時遵守偏好的語言。其他地址則會以偏好語言顯示。地址元件一律會以同一種語言傳回，而該語言是從第一個元件中選擇。
- 如果偏好語言沒有名稱，API 會使用最接近的名稱。
- 偏好語言對 API 選擇傳回的結果集和傳回順序影響不大。地理編碼器會根據語言，以不同方式解讀縮寫，例如街道類型縮寫，或在某種語言中有效但在另一種語言中無效的同義字。
maxResultCount

指定要傳回的地點結果數上限。必須介於 1 到 20 之間 (含 1 和 20)，預設為 20。
rankPreference

要使用的排名類型。如果省略這個參數，系統會依熱門程度排序結果。可以是下列任一值：
- POPULARITY (預設) 根據熱門程度排序結果。
- DISTANCE：依照地點與指定位置之間的距離，以遞增順序排列結果。
regionCode

用於格式化回應的區域代碼，指定為兩個字元的 CLDR 代碼值。沒有預設值。

如果回應中 formattedAddress 欄位的國家/地區名稱與 regionCode 相符，則 formattedAddress 會省略國家/地區代碼。這個參數不會影響 adrFormatAddress (一律包含國家/地區名稱) 或 shortFormattedAddress (一律不包含國家/地區名稱)。

大多數 CLDR 代碼與 ISO 3166-1 代碼相同，但有一些需要注意的例外情況。舉例來說，英國的 ccTLD 是「uk」(對應到 .co.uk)，而 ISO 3166-1 代碼是「gb」(技術上是指「大不列顛及北愛爾蘭聯合王國」實體)。這個參數可能會根據適用法律影響結果。

Nearby Search (新推出) 範例

尋找特定類型的地點

以下範例顯示 Nearby Search (New) 要求，用於取得 circle 所定義 500 公尺半徑內所有餐廳的顯示名稱：

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965},
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

請注意，X-Goog-FieldMask 標頭會指定回應包含下列資料欄位：places.displayName。回應的格式如下：

{
  "places": [
    {
      "displayName": {
        "text": "La Mar Cocina Peruana",
        "languageCode": "en"
      }
    },
    {
      "displayName": {
        "text": "Kokkari Estiatorio",
        "languageCode": "en"
      }
    },
    {
      "displayName": {
        "text": "Harborview Restaurant & Bar",
        "languageCode": "en"
      }
    },
...
}

在欄位遮罩中新增更多資料類型，即可傳回其他資訊。舉例來說，加入 places.formattedAddress,places.types,places.websiteUri 可在回應中加入餐廳地址、類型和網址：

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965},
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.formattedAddress,places.types,places.websiteUri" \
https://places.googleapis.com/v1/places:searchNearby

回應現在的格式如下：

{
  "places": [
    {
      "types": [
        "seafood_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "PIER 1 1/2 The Embarcadero N, San Francisco, CA 94105, USA",
      "websiteUri": "http://lamarsf.com/",
      "displayName": {
        "text": "La Mar Cocina Peruana",
        "languageCode": "en"
      }
    },
    {
      "types": [
        "greek_restaurant",
        "meal_takeaway",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "200 Jackson St, San Francisco, CA 94111, USA",
      "websiteUri": "https://kokkari.com/",
      "displayName": {
        "text": "Kokkari Estiatorio",
        "languageCode": "en"
      }
    },
...
}

尋找多種地點

以下範例顯示 Nearby Search (New) 要求，用於取得指定 circle 1000 公尺半徑內所有便利商店和酒類商店的顯示名稱：

curl -X POST -d '{
  "includedTypes": ["liquor_store", "convenience_store"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.primaryType,places.types" \
https://places.googleapis.com/v1/places:searchNearby

這個範例會在欄位遮罩中加入 places.primaryType 和 places.types，讓回應包含每個地點的類型資訊，方便從結果中選取適當的地點。

從搜尋中排除特定類型的地點

以下範例顯示 Nearby Search (New) 要求，用於尋找所有 "school" 類型的地點，排除所有 "primary_school" 類型的地點，並依距離排序結果：

curl -X POST -d '{
  "includedTypes": ["school"],
  "excludedTypes": ["primary_school"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  },
  "rankPreference": "DISTANCE"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

搜尋區域附近的所有地點，並依距離排序

以下範例顯示對舊金山市中心某個點附近地點的 Nearby Search (New) 要求。在本範例中，您會加入 rankPreference 參數，依距離排序結果：

curl -X POST -d '{
  "maxResultCount": 10,
  "rankPreference": "DISTANCE",
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

取得位址描述元

地址描述符提供地點位置的關係資訊，包括附近地標和所屬區域。

注意：地址描述符號已在印度全面推出，其他地區則處於實驗階段。如果 Places API 要求在欄位遮罩中只使用 addressDescriptor，系統會按照 SKU：Places API Nearby Search Pro 計費。

以下範例顯示聖荷西購物中心附近地點的 Nearby Search (新版) 要求。在本範例中，您會在欄位遮罩中加入 addressDescriptors：

curl -X POST -d '{
  "maxResultCount": 5,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.321328,
        "longitude": -121.946275
      },"radius": 1000
    }
  },
  "includedTypes": ["restaurant", "cafe"],
  "excludedTypes": [],
  "rankPreference":"POPULARITY"
}' \
-H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.addressDescriptor" \
https://places.googleapis.com/v1/places:searchNearby

回應會包含要求中指定的地點、附近地標清單和與地點的距離，以及區域清單和與地點的包含關係：

  {
    "places": [
      {
        "displayName": {
          "text": "Westfield Valley Fair",
          "languageCode": "en"
        },
        "addressDescriptor": {
          "landmarks": [
            {
              "name": "places/ChIJ62_oCR7Lj4AR_MGWkSPotD4",
              "placeId": "ChIJ62_oCR7Lj4AR_MGWkSPotD4",
              "displayName": {
                "text": "Nordstrom",
                "languageCode": "en"
              },
              "types": [
                "clothing_store",
                "department_store",
                "establishment",
                "point_of_interest",
                "shoe_store",
                "store"
              ],
              "straightLineDistanceMeters": 114.76984,
              "travelDistanceMeters": 114.261856
            },
            {
              "name": "places/ChIJgexMlR_Lj4ARiKCKuhNnjn0",
              "placeId": "ChIJgexMlR_Lj4ARiKCKuhNnjn0",
              "displayName": {
                "text": "Valley Fair Mall Eyexam of CA",
                "languageCode": "en"
              },
              "types": [
                "establishment",
                "health",
                "point_of_interest"
              ],
              "straightLineDistanceMeters": 131.62566,
              "travelDistanceMeters": 237.33253
            },
            {
              "name": "places/ChIJWWIlNx7Lj4ARpe1E0ob-_GI",
              "placeId": "ChIJWWIlNx7Lj4ARpe1E0ob-_GI",
              "displayName": {
                "text": "Din Tai Fung",
                "languageCode": "en"
              },
              "types": [
                "establishment",
                "food",
                "point_of_interest",
                "restaurant"
              ],
              "straightLineDistanceMeters": 110.0775,
              "travelDistanceMeters": 171.41951
            },
            {
              "name": "places/ChIJwyfPQx7Lj4AR7bYI2A2Yc54",
              "placeId": "ChIJwyfPQx7Lj4AR7bYI2A2Yc54",
              "displayName": {
                "text": "Abercrombie & Fitch",
                "languageCode": "en"
              },
              "types": [
                "clothing_store",
                "establishment",
                "point_of_interest",
                "shoe_store",
                "store"
              ],
              "spatialRelationship": "DOWN_THE_ROAD",
              "straightLineDistanceMeters": 53.620117,
              "travelDistanceMeters": 2.4578214
            },
            {
              "name": "places/ChIJpycNQx7Lj4ARjhXw3PrM_kU",
              "placeId": "ChIJpycNQx7Lj4ARjhXw3PrM_kU",
              "displayName": {
                "text": "Hollister Co.",
                "languageCode": "en"
              },
              "types": [
                "clothing_store",
                "establishment",
                "point_of_interest",
                "shoe_store",
                "store"
              ],
              "spatialRelationship": "DOWN_THE_ROAD",
              "straightLineDistanceMeters": 56.53726,
              "travelDistanceMeters": 15.418246
            }
          ],
          "areas": [
            {
              "name": "places/ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
              "placeId": "ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
              "displayName": {
                "text": "Westfield Valley Fair",
                "languageCode": "en"
              },
              "containment": "WITHIN"
            },
            {
              "name": "places/ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
              "placeId": "ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
              "displayName": {
                "text": "Valley Fair",
                "languageCode": "en"
              },
              "containment": "WITHIN"
            },
            {
              "name": "places/ChIJtYoUX2DLj4ARKoKOb1G0CpM",
              "placeId": "ChIJtYoUX2DLj4ARKoKOb1G0CpM",
              "displayName": {
                "text": "Central San Jose",
                "languageCode": "en"
              },
              "containment": "OUTSKIRTS"
            }
          ]
        }
      },
  /.../
  }

尋找日後營業的商家

以下範例顯示愛達荷州新梅多斯未來開業的商家，提出的 Nearby Search (New) 要求：

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.id,places.displayName,places.businessStatus,places.openingDate" \
-d '{
  "includeFutureOpeningBusinesses": true,
  "maxResultCount": 20,
  "locationRestriction": {
    "circle": {
      "center": {"latitude": 44.9755100, "longitude": -116.2842180},
      "radius": 20
    }
  },
  "rankPreference": "DISTANCE"
}' \
"https://places.googleapis.com/v1/places:searchNearby"

回應內容包括即將開幕的商家，以及商家的營業狀態和預計開幕日期：

{
  "places": [
    {
      "id": "ChIJp1-VoKWJplQRMz8g-7Wa3Do",
      "businessStatus": "FUTURE_OPENING",
      "displayName": {
        "text": "Roberts Greenhouse and Tree Farm",
        "languageCode": "en"
      },
      "openingDate": {
        "year": 2026,
        "month": 4,
        "day": 15
      }
    }
  ]
}

取得大眾運輸站資訊

您可以使用「Nearby Search (新版)」取得指定位置特定半徑內的大眾運輸車站資訊。回應主體包含車站相關資訊，包括車站名稱、所屬運輸公司，以及行經車站的運輸路線。此外，回應還會提供車輛圖示和顏色，方便您顯示大眾運輸車站資訊。

以下範例顯示曼哈頓中城 50 公尺範圍內的大眾運輸車站要求：

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.id,places.displayName,places.transitStation" \
-d '{
  "includedTypes": ["transit_station"],
  "locationRestriction": {
    "circle": {
      "center": {"latitude": 40.754851, "longitude": -73.984164},
      "radius": 50.0
    }
  }
}' \
"https://places.googleapis.com/v1/places:searchNearby"

回應主體包含半徑範圍內每個車站的資訊、車站提供的路線、大眾運輸機構在該停靠站發布的快訊，以及出發資訊：

{
  "places": [
    {
      "id": "ChIJH2EstKpZwokRCwZtYyMd5Fg",
      "displayName": {
        "text": "6 Av/W 41 St",
        "languageCode": "en"
      },
      "transitStation": {
        "displayName": {
          "text": "6 Av/W 41 St",
          "languageCode": "en"
        },
        "agencies": [
          {
            "displayName": {
              "text": "ShortLine Hudson",
              "languageCode": "en"
            },
            "url": "https://www.coachusa.com/",
            "lines": [
              {
                "id": "ChIJSQlbzvPwwokRolrIA-Kuh6o",
                "vehicleType": "BUS",
                "displayName": {
                  "text": "200 - Northern District – Nanuet",
                  "languageCode": "en"
                },
                "shortDisplayName": {
                  "text": "ShortLine Hudson",
                  "languageCode": "en"
                },
                "textColor": "#000000",
                "backgroundColor": "#ED60A3",
                "vehicleIcon": {
                  "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/bus2.svg"
                }
              }
            ]
          },
          {
            "displayName": {
              "text": "MTA New York City Transit",
              "languageCode": "en"
            },
            "url": "http://www.mta.info/",
            "lines": [
              {
                "id": "ChIJjUrj7PBewokR3O3S2JVpBrI",
                "vehicleType": "SUBWAY",
                "displayName": {
                  "text": "E Train (8 Av Local)",
                  "languageCode": "en"
                },
                "shortDisplayName": {
                  "text": "E Line",
                  "languageCode": "en"
                },
                "textColor": "#FFFFFF",
                "backgroundColor": "#0039A6",
                "url": "https://www.mta.info/schedules/subway/e-train",
                "icon": {
                  "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/us-ny-mta/E.svg",
                  "nameIncluded": true
                },
                "vehicleIcon": {
                  "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/subway2.svg"
                }
              },
              ...
            ]
          },
        "stops": [
          {
            "id": "ChIJvRnquapZwokRdUOyVwNGbe8",
            "displayName": {
              "text": "6 Av/W 41 St",
              "languageCode": "en"
            },
            "location": {
              "latitude": 40.754509,
              "longitude": -73.984216500000016
            },
            "wheelchairAccessibleEntrance": true
          }
        ],
        "departureBoards": [
          {
            "displayType": "DIRECTION_CENTRIC",
            "rows": [
              {
                "departures": [
                  {
                    "timedDeparture": {
                      "scheduledTime": "2026-05-15T22:29:51Z",
                      "timingType": "SCHEDULED"
                    },
                    "originallyScheduledStopId": "ChIJvRnquapZwokRdUOyVwNGbe8",
                    "lineId": "ChIJA1aFyaZfwokRkO5869M6UXk"
                  }
                ]
              },
              {
                "departures": [
                  {
                    "timedDeparture": {
                      "scheduledTime": "2026-05-15T22:33:55Z",
                      "timingType": "SCHEDULED"
                    },
                    "originallyScheduledStopId": "ChIJvRnquapZwokRdUOyVwNGbe8",
                    "lineId": "ChIJj3iCEwJfwokRZE2Qtnm4pPI"
                  }
                ]
              },
              ...
            ]
          }
        ]
      }
    },
    ...
    {
      {
        "id": "ChIJPyq6TZBZwokRdGoiJ5Iq_hE",
        "vehicleType": "BUS",
        "displayName": {
          "text": "W 44 St - South Ferry",
          "languageCode": "en"
        },
        "shortDisplayName": {
          "text": "M55",
          "languageCode": "en"
        },
        "textColor": "#FFFFFF",
        "backgroundColor": "#1D59B3",
        "vehicleIcon": {
          "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/bus2.svg"
        },
        "alerts": [
          {
            "effect": "OTHER",
            "texts": [
              {
                "headline": {
                  "text": "Information",
                  "languageCode": "en"
                },
                "summary": {
                  "text": "Northbound M20 and M55 stop on State St at Bridge St is closed; use the temporary stop on State St before the intersection instead",
                  "languageCode": "en"
                },
                "fullDescription": {
                  "text": "See a map of the new stop location. What's happening? Construction",
                  "languageCode": "en"
                }
              }
            ],
            "detailsUrls": [
              {
                "url": "https://www.mta.info/"
              }
            ],
            "cause": "OTHER_CAUSE",
            "startTime": "2025-04-02T04:00:00Z",
            "endTime": "2026-06-15T00:00:00Z",
            "attribution": {
              "link": {
                "text": "www.mta.info",
                "url": "https://www.mta.info/"
              }
            },
            "createTime": "2026-05-15T22:32:00Z",
            "severityLevel": "INFO"
          }
        ]
      },
      ...
    }
    ...
  }

試試看！

您可以使用 APIs Explorer 提出範例要求，熟悉 API 和 API 選項。

選取頁面右側的 API 圖示 api。
視需要編輯要求參數。
選取「Execute」按鈕。在對話方塊中，選擇要用來提出要求的帳戶。
在 APIs Explorer 面板中，選取全螢幕圖示 fullscreen，展開 APIs Explorer 視窗。

Nearby Search (新版) 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

簡介

Nearby Search (新版) 要求

Nearby Search (新版) 回應

必要參數

FieldMask

locationRestriction

選用參數

includeFutureOpeningBusinesses

includedTypes/excludedTypes、includedPrimaryTypes/excludedPrimaryTypes

includedTypes

excludedTypes

includedPrimaryTypes

excludedPrimaryTypes

languageCode

maxResultCount

rankPreference

regionCode

Nearby Search (新推出) 範例

尋找特定類型的地點

尋找多種地點

從搜尋中排除特定類型的地點

搜尋區域附近的所有地點，並依距離排序

取得位址描述元

尋找日後營業的商家

取得大眾運輸站資訊

試試看！

Nearby Search (新版)