نظرة عامة على نقل البيانات
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
المطوّرون في المنطقة الاقتصادية الأوروبية
يسلّط هذا الدليل الضوء على الاختلافات الرئيسية بين "خدمة الأماكن" القديمة وفئة Place الجديدة. يوفّر الترقية إلى فئة Place مزايا كبيرة،
بما في ذلك تحسين الأداء ونموذج تسعير جديد.
للاستفادة إلى أقصى حدّ من ميزة "الأماكن" وضمان تحديث تطبيقاتك، ننصحك بالتعرّف على التغييرات الموضّحة بالتفصيل في هذا الدليل.
أفضل ممارسات الفوترة لعملية نقل البيانات
warning_amber
تنطبق هذه الإرشادات إذا كان استخدامك لواجهة برمجة التطبيقات مرتفعًا بما يكفي للانتقال إلى فئة الأسعار الثانية. عند نقل البيانات إلى إصدار أحدث من واجهة برمجة التطبيقات، سيتم أيضًا تحصيل رسوم منك مقابل رمز تخزين تعريفي مختلف. لتجنُّب زيادة التكاليف خلال شهر الانتقال، ننصحك بالتبديل إلى واجهات برمجة التطبيقات الجديدة في مرحلة الإنتاج في أقرب وقت ممكن من بداية الشهر. سيضمن لك ذلك الوصول إلى فئات الأسعار الشهرية الأكثر فعالية من حيث التكلفة خلال شهر نقل البيانات. للحصول على معلومات حول فئات الأسعار، يُرجى الاطّلاع على صفحة الأسعار والأسئلة الشائعة حول الأسعار.
تفعيل Places API
يعتمد فئة المكان على خدمة Places API.
لاستخدام ميزات فئة Place الجديدة، يجب أولاً تفعيل Places API (الجديدة) في مشروعك على Google Cloud. لمزيد من المعلومات، يُرجى الاطّلاع على البدء.
التغييرات العامة
يسرد الجدول التالي بعض الاختلافات الرئيسية بين PlacesService وPlace:
التغييرات الخاصة بواجهة برمجة التطبيقات
يوفر فئة Place واجهة برمجة تطبيقات لاستخدام مكتبة Places، كما تتوافق مع أنماط الاستخدام الحديثة، مثل Promises. يعرض فئة Place حقول بيانات المكان وأنواع الأماكن نفسها التي كانت تعرضها خدمة Places القديمة، كما تتضمّن العديد من القيم الجديدة لحقول بيانات المكان وأنواع الأماكن.
يوضّح هذا الجدول كيفية ربط ميزات "خدمة الأماكن" بميزات فئة Place:
تحميل "مكتبة الأماكن"
تعتمد طريقة تحميل تطبيقك لمكتبة "أماكن Google" على أداة تحميل التمهيد المستخدَمة. إذا كان تطبيقك يستخدم استيراد المكتبة الديناميكية،
يمكنك تحميل المكتبات المطلوبة في وقت التشغيل باستخدام عامل التشغيل await
لطلب importLibrary()، كما هو موضّح هنا:
const { Place } = await google.maps.importLibrary("places");
إذا كان تطبيقك يستخدم علامة تحميل النص البرمجي المباشر،
اطلب المكتبة places في النص البرمجي الخاص بأداة التحميل:
<script async
src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=places&callback=initMap">
</script>
مزيد من المعلومات حول تحميل Maps JavaScript API
يتضمّن هذا القسم الأدلة التالية لمساعدتك في نقل تطبيقاتك لاستخدام أحدث إصدار من Places API:
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2025-08-31 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-08-31 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["# Migration overview\n\n\u003cbr /\u003e\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\nThis guide highlights key differences between the legacy\nPlaces Service and the new\nPlace class. Upgrading to the\nPlace class offers significant advantages,\nincluding improved performance and a new [pricing model](/maps/documentation/javascript/usage-and-billing#places-js-library).\nTo get the most out of Places and ensure your apps are up-to-date, familiarize\nyourself with the changes detailed in this guide.\n\n\nBilling best practices for migration\n------------------------------------\n\nwarning_amber\n\nThis guidance applies if your API usage is high enough to\nmove into second-tier pricing. When migrating to a newer version of an API,\nyou're also being billed for a different SKU. To avoid increased costs during the month of\nyour transition, we recommend switching to the new APIs in production as close to the\nbeginning of the month as possible. This will ensure that you reach the most cost-effective\nmonthly pricing tiers during the migration month. For information about pricing tiers,\nsee the [pricing page](/maps/billing-and-pricing/pricing)\nand the [pricing FAQ](/maps/billing-and-pricing/faq).\n\n\u003cbr /\u003e\n\nEnable Places API\n-----------------\n\nThe Place class relies on the Places API service.\nTo use the features of the new Place class, you\nmust first enable Places API (New) in your Google Cloud project. For more\ninformation, see [Get started](/maps/documentation/javascript/place-get-started).\n\nGeneral changes\n---------------\n\nThe following table lists some of the main differences between `PlacesService`\nand `Place`:\n\n| [`PlacesService`](/maps/documentation/javascript/reference/places-service) (Legacy) | [`Place`](/maps/documentation/javascript/reference/place) (New) |\n|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| Methods require the use of a callback to handle the results object and `google.maps.places.PlacesServiceStatus` response. | Uses Promises, and works asynchronously. |\n| Methods require a `PlacesServiceStatus` check. | No required status check, can use standard error handling. |\n| [Place data fields](/maps/documentation/javascript/place-data-fields) are formatted using snake case. | [Place data fields](/maps/documentation/javascript/place-class-data-fields) are formatted using camel case. |\n| Limited to a fixed set of [place types](/maps/documentation/javascript/supported_types) and [place data fields](/maps/documentation/javascript/place-data-fields). | Provides an expanded selection of regularly updated [place types](/maps/documentation/javascript/place-types) and [place data fields](/maps/documentation/javascript/place-class-data-fields). |\n\nAPI-specific changes\n--------------------\n\nThe Place class provides an API for using the Places library, and supports\nmodern usage patterns such as Promises. The Place class exposes the same place\ndata fields and place types as the legacy Places Service, and includes many new\nvalues for place data fields and place types.\n\nThis table shows how features of the Places Service\nmap to those of the Place class:\n\n| Places Service (Legacy) | Place Class (New) |\n|----------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|\n| [Place Data Fields](/maps/documentation/javascript/place-data-fields) | [Place Class Data Fields](/maps/documentation/javascript/place-class-data-fields) |\n| [Place Types](/maps/documentation/javascript/supported_types) | [Place Types](/maps/documentation/javascript/place-types) |\n| [`PlacesService.findPlaceFromQuery()`](/maps/documentation/javascript/reference/places-service#PlacesService.findPlaceFromQuery) | [`Place.searchByText()`](/maps/documentation/javascript/reference/place#Place.searchByText) |\n| [`PlacesService.findPlaceFromPhoneNumber()`](/maps/documentation/javascript/reference/places-service#PlacesService.findPlaceFromPhoneNumber) | [`Place.searchByText()`](/maps/documentation/javascript/reference/place#Place.searchByText) |\n| [`PlacesService.textSearch()`](/maps/documentation/javascript/reference/places-service#PlacesService.textSearch) | [`Place.searchByText()`](/maps/documentation/javascript/reference/place#Place.searchByText) |\n| [`PlacesService.nearbySearch()`](/maps/documentation/javascript/reference/places-service#PlacesService.nearbySearch) | [`Place.searchNearby()`](/maps/documentation/javascript/reference/place#Place.searchNearby) |\n| [`PlacesService.getDetails()`](/maps/documentation/javascript/reference/places-service#PlacesService.getDetails) | [`Place.fetchFields()`](/maps/documentation/javascript/reference/place#Place.fetchFields) |\n| [`Places.AutocompletionRequest`](/maps/documentation/javascript/reference/places-autocomplete-service?db=wfrench#AutocompletionRequest) | [`Places.AutocompleteRequest`](/maps/documentation/javascript/reference/autocomplete-data#AutocompleteRequest) |\n| [`Places.AutocompletePrediction`](/maps/documentation/javascript/reference/places-autocomplete-service#AutocompletePrediction) | [`Places.PlacePrediction`](/maps/documentation/javascript/reference/autocomplete-data#PlacePrediction) |\n| [`Autocomplete`](/maps/documentation/javascript/reference/places-widget#Autocomplete) class | [`PlaceAutocompleteElement`](/maps/documentation/javascript/reference/places-widget#PlaceAutocompleteElement) class |\n| [`SearchBox`](/maps/documentation/javascript/reference/places-widget#SearchBox) class | --- |\n\nLoad the Places library\n-----------------------\n\nHow your app loads the Places library depends on which bootstrap loader is in\nuse. If your app uses [dynamic library import](/maps/documentation/javascript/load-maps-js-api#dynamic-library-import),\nyou can load the needed libraries at runtime by using the `await` operator to\ncall `importLibrary()`, as shown here: \n\n const { Place } = await google.maps.importLibrary(\"places\");\n\nIf your app uses the [direct script loading tag](/maps/documentation/javascript/load-maps-js-api#use-legacy-tag),\nrequest the `places` library in the loader script:\n\n\n```html\n\u003cscript async\n src=\"https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=places&callback=initMap\"\u003e\n\u003c/script\u003e\n```\n\n\u003cbr /\u003e\n\n[Learn more about loading the Maps JavaScript API.](/maps/documentation/javascript/load-maps-js-api)\n\nThis section includes the following guides to help you migrate your apps to use\nthe newest version of the Places API:\n\n- [Migrate to Place Details](/maps/documentation/javascript/places-migration-details)\n- [Migrate to Text Search (New)](/maps/documentation/javascript/places-migration-search)\n- [Migrate to Nearby Search (New)](/maps/documentation/javascript/places-migration-nearby)\n- [Migrate to Place Photos](/maps/documentation/javascript/places-migration-photos)\n- [Migrate to Place Reviews](/maps/documentation/javascript/places-migration-reviews)\n- [Migrate to Place Autocomplete](/maps/documentation/javascript/places-migration-autocomplete)"]]
