تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
المطوّرون في المنطقة الاقتصادية الأوروبية
مقدمة
عند طلب البيانات باستخدام الطرق
Place Details (New) أو
Nearby Search (New) أو
Text Search (New)،
عليك تحديد الحقول التي تريد عرضها في الردّ. لا توجد قائمة تلقائية بالحقول التي يتم عرضها. في حال إغفال هذه القائمة، ستعرض الطرق خطأً.
يمكنك الاطّلاع على القائمة الكاملة بحقول البيانات المتوافقة ورموز التخزين التعريفية المقابلة لها في حقول بيانات الأماكن (جديد). للحصول على معلومات حول الحقول الخاصة بكل واجهة برمجة تطبيقات، يُرجى الاطّلاع على ما يلي:
مَعلمات FieldMask الخاصة بـ "تفاصيل المكان" (جديدة)
يمكنك تحديد قائمة الحقول من خلال إنشاء قناع حقل استجابة. بعد ذلك، يمكنك تمرير قناع حقل الاستجابة إلى أي من الطريقتين باستخدام المَعلمة $fields أو fields، أو باستخدام عنوان HTTP أو gRPC X-Goog-FieldMask.
يُعدّ إخفاء الحقول من أفضل ممارسات التصميم لضمان عدم طلب بيانات غير ضرورية، ما يساعد في تجنُّب وقت المعالجة غير الضروري ورسوم الفوترة.
تحديد قناع حقل الردّ
قناع حقول الرد هو قائمة مسارات مفصولة بفواصل، حيث يحدّد كل مسار حقلاً فريدًا في نص الرد. يبدأ المسار من رسالة الرد ذات المستوى الأعلى ويستخدم مسارًا مفصولاً بنقاط إلى الحقل المحدّد.
لمزيد من المعلومات حول كيفية إنشاء أقنعة الحقول، يُرجى الاطّلاع على field_mask.proto.
تحديد حقول الأقنعة التي يجب استخدامها
في ما يلي كيفية تحديد حقول الأقنعة التي تريد استخدامها:
اطلب جميع الحقول باستخدام قناع حقل *.
اطّلِع على التسلسل الهرمي للحقول في الرد، وحدِّد الحقول التي تريدها.
أنشئ قناع الحقل باستخدام التسلسل الهرمي للحقول.
تحديد قناع حقل الردّ لكلّ من Nearby Search (New) وText Search (New)
تعرض كلّ من "البحث القريب" (إصدار جديد) و"البحث النصي" (إصدار جديد) مصفوفة من عناصر Place في الحقل places للردّ. في واجهات برمجة التطبيقات هذه، places هو الحقل ذو المستوى الأعلى في الرد.
على سبيل المثال، للاطّلاع على عنصر الاستجابة الكامل من Text Search (New):
يكون عنصر الاستجابة الكامل من طلب بحث Text Search (New) بالشكل التالي:
{"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"},...},...]}
لذلك، عليك تحديد قناع حقل لواجهات برمجة التطبيقات هذه في النموذج:
places[.secondLevelField][.thirdLevelField][...]
إذا كنت تريد عرض الحقلَين formattedAddress وdisplayName فقط، اضبط قناع الحقل على ما يلي:
places.formattedAddress,places.displayName
يؤدي تحديد displayName إلى تضمين الحقلَين text وlanguage من displayName. إذا كنت تريد الحقل text فقط، اضبط قناع الحقل على النحو التالي:
places.formattedAddress,places.displayName.text
تحديد قناع حقل الردّ لخدمة "تفاصيل المكان (جديدة)"
تعرض خدمة "تفاصيل المكان (جديدة)" عنصر Place واحدًا بالشكل التالي:
{"name":"places/ChIJkR8FdQNB0VQRm64T_lv1g1g","id":"ChIJkR8FdQNB0VQRm64T_lv1g1g","types":["locality","political"],"formattedAddress":"Trinidad, CA 95570, USA","displayName":{"text":"Trinidad","languageCode":"en"}...}
لذلك، يمكنك تحديد قناع حقل لواجهة برمجة التطبيقات هذه من خلال تحديد حقول عنصر Place التي تريد عرضها:
أدرِج فقط الحقول التي تحتاج إليها في الردّ. عرض الحقول التي تحتاج إليها فقط:
تقليل أوقات المعالجة، ما يؤدي إلى عرض النتائج بوقت استجابة أقل
يضمن أداءً ثابتًا لوقت الاستجابة إذا أضافت واجهة برمجة التطبيقات المزيد من حقول الردود
في المستقبل، وكانت هذه الحقول الجديدة تتطلّب وقتًا إضافيًا للمعالجة. في حال اختيار جميع الحقول، أو إذا اخترت جميع الحقول على المستوى الأعلى، قد ينخفض الأداء عندما يتم تضمين جميع الحقول الجديدة تلقائيًا في ردّك.
نتائج بحجم ردّ أصغر، ما يؤدي إلى زيادة معدل نقل البيانات على الشبكة.
يضمن عدم طلب بيانات غير ضرورية، ما يساعد في تجنُّب وقت المعالجة والرسوم غير الضرورية.
تاريخ التعديل الأخير: 2025-09-04 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-09-04 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\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)."]]
