{"places":[{"name":"places/ChIJs5ydyTiuEmsR0fRSlU0C7k0","id":"ChIJs5ydyTiuEmsR0fRSlU0C7k0","types":["vegetarian_restaurant","vegan_restaurant","meal_takeaway","restaurant","food","point_of_interest","establishment"],"nationalPhoneNumber":"0433 479 794","internationalPhoneNumber":"+61 433 479 794","formattedAddress":"29 King St, Sydney NSW 2000, Australia","displayName":{"text":"Spiced @ Barangaroo","languageCode":"en"},...},...]}
因此，您會以以下形式為這些 API 指定欄位遮罩：
places[.secondLevelField][.thirdLevelField][...]
如要只傳回 formattedAddress 和 displayName 欄位，請將欄位遮罩設為：
places.formattedAddress,places.displayName
指定 displayName 時，會同時包含 displayName 的 text 和 language 欄位。如果只需要 text 欄位，請將欄位遮罩設為：
places.formattedAddress,places.displayName.text
定義 Place Details (新版) 的回應欄位遮罩
Place Details (New) 會以以下形式傳回單一 Place 物件：
{"name":"places/ChIJkR8FdQNB0VQRm64T_lv1g1g","id":"ChIJkR8FdQNB0VQRm64T_lv1g1g","types":["locality","political"],"formattedAddress":"Trinidad, CA 95570, USA","displayName":{"text":"Trinidad","languageCode":"en"}...}
[null,null,["上次更新時間：2025-08-29 (世界標準時間)。"],[[["\u003cp\u003eWhen calling Place Details, Nearby Search, or Text Search methods, you must specify desired fields using a response field mask to avoid errors.\u003c/p\u003e\n"],["\u003cp\u003eField masks help reduce costs and latency by only retrieving necessary data, and should be tailored based on specific field requirements.\u003c/p\u003e\n"],["\u003cp\u003eConstruct field masks using dot-separated paths starting from the top-level response message, such as \u003ccode\u003eplaces.formattedAddress\u003c/code\u003e for Nearby and Text Search or \u003ccode\u003eformattedAddress\u003c/code\u003e for Place Details.\u003c/p\u003e\n"],["\u003cp\u003eUse \u003ccode\u003e*\u003c/code\u003e to request all fields during development, but define specific fields in production to optimize performance and costs.\u003c/p\u003e\n"],["\u003cp\u003eAvoid unnecessary data retrieval by only including required fields, which minimizes processing time, response size, and potential billing charges.\u003c/p\u003e\n"]]],["When using Place Details, Nearby Search, or Text Search, you must define a response field mask, specifying desired fields. This mask, a comma-separated list of paths, is passed via `$fields`, `fields`, or the `X-Goog-FieldMask` header. For Nearby and Text Search, the path starts with `places`; for Place Details, it starts with the desired fields directly. Using the wildcard `*` is discouraged in production. Defining the field masks ensures efficient processing, reduces data transfer, and controls costs. Only requested fields will be in the response.\n"],null,["# Choose fields to return\n\n**European Economic Area (EEA) developers** If your billing address is in the European Economic Area, effective on 8 July 2025, the [Google Maps Platform EEA Terms of Service](https://cloud.google.com/terms/maps-platform/eea) will apply to your use of the Services. Functionality varies by region. [Learn more](/maps/comms/eea/faq).\n\nIntroduction\n------------\n\nWhen you call the\n[Place Details (New)](/maps/documentation/places/web-service/place-details),\n[Nearby Search (New)](/maps/documentation/places/web-service/nearby-search),\nor [Text Search (New)](/maps/documentation/places/web-service/text-search)\nmethods, you must specify which fields you want returned in the response. There\nis no default list of returned fields. If you omit this list, the methods return\nan error.\n\nA full list of supported data fields and their corresponding SKUs can be found\nin [Place Data Fields\n(New)](/maps/documentation/places/web-service/data-fields). For information on\nfields specific to each API, see the following:\n\n- Place Details (New) [FieldMask](/maps/documentation/places/web-service/place-details#fieldmask) parameters\n- Nearby Search (New) [FieldMask](/maps/documentation/places/web-service/nearby-search#fieldmask) parameters\n- Text Search (New) [FieldMask](/maps/documentation/places/web-service/text-search#fieldmask) parameters\n\nYou specify the field list by creating a **response field mask** . You then pass\nthe response field mask to either method by using the parameter `$fields` or\n`fields`, or by using the HTTP or gRPC header `X-Goog-FieldMask`.\n\nField masking is a good design practice to ensure that you don't request\nunnecessary data, which helps to avoid unnecessary processing time and billing\ncharges.\n\nDefine a response field mask\n----------------------------\n\nThe response field mask is a comma-separated list of paths, where each path\nspecifies a unique field in the response body. The path starts from the\ntop-level response message and uses a dot-separated path to the specified field.\n\nConstruct a field path as follows: \n\n```\ntopLevelField[.secondLevelField][.thirdLevelField][...]\n```\n| **Note:** Don't use spaces anywhere in the list of field paths.\n\nYou can request all fields by using a field mask of `*`.\n| **Caution:** While this wildcard field mask is okay to use in development, don't use the wildcard (\\*) response field mask in production. The cost may be higher than expected as more advanced features are requested through this field mask, and it increases response latency. Make sure you are requesting only the fields you need to minimize your costs and request response time.\n\nFor more information about how to construct field masks, see the\n[field_mask.proto](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/field_mask.proto).\n\n### Determine what field masks to use\n\nHere's how you can determine which field masks you want to use:\n\n1. Request all fields using a field mask of `*`.\n2. Look at the hierarchy of the fields in the response, and determine what fields you want.\n3. Build your field mask using the field hierarchy.\n\n### Define a response field mask for Nearby Search (New) and Text Search (New)\n\nNearby Search (New) and Text Search (New) return an array of Place\nobjects in the `places` field of the response. For these APIs, `places` is the\ntop-level field of the response.\n\nFor example, to see the complete response object from a Text Search (New): \n\n```\ncurl -X POST -d '{\n \"textQuery\" : \"Spicy Vegetarian Food in Sydney, Australia\"\n}' \\\n-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \\\n-H 'X-Goog-FieldMask: *' \\\n'https://places.googleapis.com/v1/places:searchText'\n```\n\nThe complete response object from a Text Search (New)\ncall is in the form: \n\n```json\n{\n \"places\": [\n {\n \"name\": \"places/ChIJs5ydyTiuEmsR0fRSlU0C7k0\",\n \"id\": \"ChIJs5ydyTiuEmsR0fRSlU0C7k0\",\n \"types\": [\n \"vegetarian_restaurant\",\n \"vegan_restaurant\",\n \"meal_takeaway\",\n \"restaurant\",\n \"food\",\n \"point_of_interest\",\n \"establishment\"\n ],\n \"nationalPhoneNumber\": \"0433 479 794\",\n \"internationalPhoneNumber\": \"+61 433 479 794\",\n \"formattedAddress\": \"29 King St, Sydney NSW 2000, Australia\",\n \"displayName\": {\n \"text\": \"Spiced @ Barangaroo\",\n \"languageCode\": \"en\"\n }, ...\n },\n ...\n ]\n}\n```\n\nTherefore, you specify a field mask for these APIs in the form: \n\n```\nplaces[.secondLevelField][.thirdLevelField][...]\n```\n\nIf you want to return only the `formattedAddress` and `displayName` fields, set\nyour field mask to: \n\n```\nplaces.formattedAddress,places.displayName\n```\n\nSpecifying `displayName` includes both the `text` and `language` fields of\n`displayName`. If you only want the `text` field, set the field mask as: \n\n```\nplaces.formattedAddress,places.displayName.text\n```\n\n### Define a response field mask for Place Details (New)\n\nPlace Details (New) returns a single Place object in the form: \n\n```json\n{\n \"name\": \"places/ChIJkR8FdQNB0VQRm64T_lv1g1g\",\n \"id\": \"ChIJkR8FdQNB0VQRm64T_lv1g1g\",\n \"types\": [\n \"locality\",\n \"political\"\n ],\n \"formattedAddress\": \"Trinidad, CA 95570, USA\",\n \"displayName\": {\n \"text\": \"Trinidad\",\n \"languageCode\": \"en\"\n }\n ...\n}\n```\n\nTherefore, you specify a field mask for this API by specifying the fields of the\nPlace object that you want to return: \n\n```\ncurl -X GET -H 'Content-Type: application/json' \\\n-H \"X-Goog-Api-Key: API_KEY\" \\\n-H \"X-Goog-FieldMask: formattedAddress,displayName\" \\\nhttps://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw\n```\n\n### gRPC call\n\nFor gRPC, set a variable containing the response field mask. You can then pass\nthat variable to the request. \n\n```json\nconst (\n fieldMask = \"places.formattedAddress,places.displayName\"\n)\n```\n\nField path considerations\n-------------------------\n\nInclude only the fields that you require in the response. Returning just the\nfields that you need:\n\n- **Decreases processing times**, so your results are returned with a lower latency.\n- **Ensures stable latency performance** if the API adds more response fields in the future, and those new fields require extra computation time. If you select all fields, or if you select all fields at the top level, you might experience performance degradation when all new fields are automatically included in your response.\n- **Results in a smaller response size**, which translates into higher network throughput.\n- **Ensures that you don't request unnecessary data**, which helps to avoid unnecessary processing time and billed charges.\n\n| **Note:** When a response message is parsed, and a field in the response message contains its default value, the field may be omitted from the response even if you specified it in the response field mask. For more information, see the [Language Guide (proto3)](https://developers.google.com/protocol-buffers/docs/proto3#default)."]]
