نقل البيانات إلى ميزة "البحث عن قرب" (ميزة جديدة)
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
المطوّرون في المنطقة الاقتصادية الأوروبية
مقدمة
تتيح Places API استخدام Nearby Search (الإصدار القديم).
إذا كنت معتادًا على ميزة "البحث القريب" (الإصدار القديم)، ستلاحظ أنّ
ميزة "البحث القريب" (الإصدار الجديد) تتضمّن التغييرات التالية:
- تستخدم خدمة Nearby Search (جديدة) طلبات HTTP POST.
يمكنك تمرير المَعلمات في نص الطلب أو في العناوين كجزء من طلب HTTP POST. في المقابل، عند استخدام خدمة "البحث القريب" (الإصدار القديم)،
يمكنك تمرير مَعلمات عنوان URL باستخدام طلب HTTP GET.
- يجب إخفاء الحقل. يجب تحديد الحقول التي تريد عرضها في الرد. لا توجد قائمة تلقائية بالحقول التي يتم عرضها. إذا حذفت هذه القائمة، ستعرض الطرق خطأ. لمزيد من المعلومات، يُرجى الاطّلاع على
FieldMask.
- تتيح واجهة برمجة التطبيقات Nearby Search (New) استخدام كل من
مفاتيح واجهة برمجة التطبيقات
ورموز OAuth كآلية للمصادقة.
- لا يتوفّر سوى تنسيق JSON كشكل استجابة في واجهة برمجة التطبيقات "البحث القريب" (جديدة).
- يجب الآن استخدام البحث النصي (جديد) في جميع الطلبات التي تتضمّن طلب بحث نصيًا، لأنّ "البحث في الأماكن القريبة (جديد)" لا يتيح إدخال نص.
- تم تغيير تنسيق استجابة JSON الخاص بخدمة "البحث القريب" (إصدار جديد) ليصبح مختلفًا عن تنسيق واجهات برمجة التطبيقات القديمة. لمزيد من التفاصيل، يُرجى الاطّلاع على
نقل استجابة Places API.
يسرد الجدول التالي المَعلمات في Nearby Search (الإصدار القديم) التي تمت إعادة تسميتها أو تعديلها في Nearby Search (الإصدار الجديد)، أو المَعلمات التي لم تعُد متاحة.
| المَعلمة الحالية |
معلَمة جديدة |
ملاحظات |
keyword |
|
غير مدعوم. استخدِم
البحث النصي (جديد)
بدلاً من ذلك. |
language |
languageCode |
|
location |
locationRestriction |
مطلوب. |
maxprice/minprice |
|
غير مدعوم. |
|
maxResultCount |
معلَمة جديدة |
opennow |
|
غير مدعوم. |
pagetoken |
|
غير مدعوم. |
radius |
|
استخدِم locationRestriction الآن. |
rankby |
rankPreference |
|
|
regionCode |
معلَمة جديدة |
type |
includedTypes
excludedTypes
includedPrimaryTypes
excludedPrimaryTypes
|
تقبل المَعلمات الجديدة أيضًا قيمًا متعددة للنوع. لا تقبل واجهة برمجة التطبيقات القديمة سوى قيمة واحدة. |
مثال على الطلب
يستخدم مثال طلب GET التالي خدمة "البحث القريب" (الإصدار القديم). في هذا المثال، تطلب استجابة JSON تحتوي على معلومات حول أماكن من النوع restaurant وتمرّر جميع المَعلمات كمَعلمات عنوان URL:
curl -L -X GET \
'https://maps.googleapis.com/maps/api/place/nearbysearch/json?location=37.7937%2C-122.3965&radius=500&type=restaurant&key=API_KEY'
باستخدام Nearby Search (New)، يمكنك إرسال طلب POST وتمرير جميع المَعلمات في نص طلب JSON أو في العناوين كجزء من طلب POST.
يستخدم هذا المثال أيضًا قناع حقل حتى تتضمّن الاستجابة الاسم المعروض والعنوان المنسّق للمكان فقط:
curl -X POST -d '{
"includedTypes": ["restaurant"],
"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" \
https://places.googleapis.com/v1/places:searchNearby
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2025-08-29 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-08-29 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["# Migrate to Nearby Search (New)\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\nPlaces API supports\n[Nearby Search (Legacy)](/maps/documentation/places/web-service/search-nearby).\nIf you are familiar with Nearby Search (Legacy), the [Nearby Search (New)](/maps/documentation/places/web-service/nearby-search) makes the following\nchanges:\n\n- Nearby Search (New) uses HTTP POST requests. Pass parameters in the request body or in headers as part of an HTTP POST request. In contrast, with Nearby Search (Legacy), you pass URL parameters using an HTTP GET request.\n- Field masking is required. You must specify which fields you want returned in the response. There is no default list of returned fields. If you omit this list, the methods return an error. For more information, see [FieldMask](/maps/documentation/places/web-service/nearby-search#fieldmask).\n- Nearby Search (New) supports both [API keys](/maps/documentation/places/web-service/get-api-key) and [OAuth](/maps/documentation/places/web-service/oauth-token) tokens as the authentication mechanism.\n- Only JSON is supported as a response format in Nearby Search (New).\n- All requests that include a text query should now use [Text Search (New)](/maps/documentation/places/web-service/text-search) because Nearby Search (New) does not support text input.\n- The JSON response format for Nearby Search (New) has changed from the format of the legacy APIs. For more details, see [Migrate the Places API response](/maps/documentation/places/web-service/migrate-response).\n\nThe following table lists parameters in Nearby Search (Legacy) that have been\nrenamed or modified for Nearby Search (New), or parameters that are no\nlonger supported.\n\n| Current parameter | New parameter | Notes |\n|---------------------|-------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|\n| `keyword` | | Not supported. Use [Text Search (New)](/maps/documentation/places/web-service/text-search) instead. |\n| `language` | `languageCode` | |\n| `location` | `locationRestriction` | Required. |\n| `maxprice/minprice` | | Not supported. |\n| | `maxResultCount` | New parameter. |\n| `opennow` | | Not supported. |\n| `pagetoken` | | Not supported. |\n| `radius` | | Use `locationRestriction` now. |\n| `rankby` | `rankPreference` | |\n| | `regionCode` | New parameter. |\n| `type` | `includedTypes` `excludedTypes` `includedPrimaryTypes` `excludedPrimaryTypes` | The new parameters also accept multiple type values. The legacy API only accepts a single value. |\n\nExample request\n---------------\n\nThe following example GET request uses the Nearby Search (Legacy). In this\nexample, you request a JSON response containing information about places of type\n`restaurant` and pass all parameters as URL parameters: \n\n```curl\ncurl -L -X GET \\\n'https://maps.googleapis.com/maps/api/place/nearbysearch/json?location=37.7937%2C-122.3965&radius=500&type=restaurant&key=API_KEY'\n```\n\nWith Nearby Search (New), you make a POST request and pass all\nparameters in the JSON request body or in headers as part of the POST request.\nThis example also uses a field mask so the response only includes the display\nname and formatted address of the place: \n\n```curl\ncurl -X POST -d '{\n \"includedTypes\": [\"restaurant\"],\n \"locationRestriction\": {\n \"circle\": {\n \"center\": {\n \"latitude\": 37.7937,\n \"longitude\": -122.3965},\n \"radius\": 500.0\n }\n }\n}' \\\n-H 'Content-Type: application/json' -H \"X-Goog-Api-Key: API_KEY\" \\\n-H \"X-Goog-FieldMask: places.displayName,places.formattedAddress\" \\\nhttps://places.googleapis.com/v1/places:searchNearby\n```"]]
