تحدِّد أرقام تعريف الأماكن مكانًا بشكلٍ فريد في قاعدة بيانات "أماكن Google" وعلى "خرائط Google". يتم قبول أرقام تعريف الأماكن
في الطلبات المرسَلة إلى واجهات برمجة التطبيقات التالية في "خرائط Google":
استرداد عنوان لرقم تعريف مكان في Geocoding API و
خدمة ترميز المواقع الجغرافية، واجهة برمجة تطبيقات JavaScript للخرائط
تحديد نقاط البداية والوجهة والنقاط الوسيطة في
Routes API وDirections API (القديمة)
وDirections Service وMaps JavaScript API (القديمة)
تحديد نقاط المغادرة والوجهات في Routes API و
Distance Matrix API (القديمة) و
Distance Matrix Service وMaps JavaScript API (القديمة)
استرداد تفاصيل الأماكن في واجهة برمجة التطبيقات Places API (ميزة جديدة)،
وحزمة تطوير البرامج (SDK) للأماكن لنظام Android (ميزة جديدة)، وحزمة تطوير البرامج (SDK) للأماكن لنظام iOS (ميزة جديدة)،
و"مكتبة الأماكن"
استخدام مَعلمات رقم تعريف المكان في واجهة برمجة التطبيقات Maps Embed API
استرداد طلبات البحث في عناوين URL في "خرائط Google"
عرض حدود السرعة في Roads API
العثور على مضلّعات الحدود وتصميمها في التصميم المستنِد إلى البيانات للحدود
العثور على رقم تعريف مكان معيّن
هل تبحث عن معرّف مكان معيّن؟ استخدِم أداة البحث عن معرّف المكان أدناه للبحث عن مكان والحصول على معرّفه:
تتوفّر أرقام تعريف الأماكن لمعظم المواقع الجغرافية، بما في ذلك الأنشطة التجارية والمعالم
والمتنزهات والتقاطعات. من الممكن أن يحتوي المكان أو الموقع الجغرافي نفسه على
أرقام تعريف أماكن متعددة ومختلفة. قد تتغيّر أرقام تعريف الأماكن بمرور الوقت.
من الطرق الشائعة لاستخدام معرّفات الأماكن هي البحث عن مكان
(باستخدام Places API
أو مكتبة
الأماكن في واجهة برمجة التطبيقات JavaScript للخرائط، على سبيل المثال)، ثم استخدام
معرّف المكان الذي تم إرجاعه لاسترداد تفاصيل المكان. يمكنك تخزين رقم تعريف المكان
واستخدامه لاسترداد تفاصيل المكان نفسها لاحقًا. يمكنك الاطّلاع على مزيد من المعلومات عن
حفظ أرقام تعريف الأماكن أدناه.
توضّح الأمثلة التالية كيفية طلب عنوان URL لرمز Places API (الإصدار الجديد) و
Places API (الإصدار القديم).
Places API (جديدة)
باستخدام Places API، يمكنك العثور على معرّف مكان من خلال إرسال طلب
البحث النصي (جديد).
تكون أرقام تعريف الأماكن مُعفاة من القيود المفروضة على التخزين المؤقت والمذكورة في الفقرة 3.2.3(ب)
من بنود خدمة Google Maps Platform. ويمكنك بالتالي تخزين قيم معرّفات الأماكن لاستخدامها لاحقًا.
إعادة تحميل معرّفات الأماكن المخزّنة
بما أنّ أرقام تعريف الأماكن قد تتغيّر بسبب التعديلات على قاعدة بيانات "خرائط Google"، تنصح Google بمحاولة إعادة تحميل أرقام تعريف الأماكن إذا مرّ عليها أكثر من 12 شهرًا. يمكنك إعادة تحميل أرقام تعريف الأماكن بدون أي رسوم من خلال إرسال طلب للحصول على تفاصيل الأماكن، مع تحديد حقل رقم تعريف المكان فقط في المَعلمة fields.
يشير رمز الحالة INVALID_REQUEST إلى أنّ رقم تعريف
المكان المحدّد غير صالح. قد يتم عرض القيمة INVALID_REQUEST عندما يتم اقتطاع رقم تعريف
المكان أو تعديله بأي شكل آخر، ولم يعُد صحيحًا.
NOT_FOUND
يشير رمز الحالة NOT_FOUND إلى أنّ رقم تعريف المكان المحدّد
قديم. قد يصبح معرّف المكان قديمًا إذا تم إغلاق نشاط تجاري أو نقله إلى
موقع جغرافي جديد. قد تتغيّر أرقام تعريف الأماكن أيضًا بسبب التعديلات على قاعدة بيانات "خرائط Google". في هذه الحالات، قد يحصل المكان على معرّف مكان جديد، ويعرض المعرّف القديمNOT_FOUND.
لإعادة تحميل النتائج في حال استخدام معرّف مكان قديم، يمكنك تخزين الطلب الأصلي الذي
أرجع كل معرّف مكان وإعادة إصدار الطلب حسب الحاجة. يُرجى العلم أنّه يتم تقييم رسوم الطلب الذي تمت إعادة إصداره
وفقًا لرقم التخزين التعريفي المناسب.
قد تؤدي بعض أنواع معرّفات الأماكن أحيانًا إلى NOT_FOUND
في الاستجابة، أو قد تعرض واجهة برمجة التطبيقات معرّف مكان مختلفًا في
الاستجابة. تشمل أنواع أرقام تعريف الأماكن هذه ما يلي:
عناوين الشوارع التي لا تظهر في "خرائط Google" كعناوين دقيقة،
ولكن يتم استنتاجها من مجموعة من العناوين
أجزاء من مسار طويل، حيث يحدّد الطلب أيضًا مدينة أو
منطقة
التقاطعات
الأماكن التي تحتوي على مكوّن عنوان من النوع subpremise
غالبًا ما تأخذ هذه المعرّفات شكل سلسلة طويلة (لا يوجد حد أقصى لطول
معرّفات الأماكن). على سبيل المثال:
تاريخ التعديل الأخير: 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\u003ePlace IDs are unique identifiers for places in the Google Places database and are used across various Google Maps Platform APIs.\u003c/p\u003e\n"],["\u003cp\u003eYou can find Place IDs using the Place ID finder or by searching for places using the Places API.\u003c/p\u003e\n"],["\u003cp\u003ePlace IDs can be stored and reused, but it's recommended to refresh them if they are over 12 months old.\u003c/p\u003e\n"],["\u003cp\u003e\u003ccode\u003eINVALID_REQUEST\u003c/code\u003e or \u003ccode\u003eNOT_FOUND\u003c/code\u003e error codes may indicate an invalid or obsolete Place ID.\u003c/p\u003e\n"]]],[],null,["# Place IDs\n\nSelect platform: [Android](/maps/documentation/places/android-sdk/place-id \"View this page for the Android platform docs.\") [iOS](/maps/documentation/places/ios-sdk/place-id \"View this page for the iOS platform docs.\") [JavaScript](/maps/documentation/javascript/place-id \"View this page for the JavaScript platform docs.\") [Web Service](/maps/documentation/places/web-service/place-id \"View this page for the Web Service platform docs.\") \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\nPlace IDs uniquely identify a place in the Google Places database and on Google Maps. Place IDs\nare accepted in requests to the following Maps APIs:\n\n- Retrieving an address for a Place ID in the Geocoding API and Geocoding Service, Maps JavaScript API.\n- Specifying origin, destination and intermediate waypoints in the Routes API and Directions API (Legacy) and Directions Service, Maps JavaScript API (Legacy).\n- Specifying origins and destinations in the Routes API and Distance Matrix API (Legacy) and Distance Matrix Service, Maps JavaScript API (Legacy).\n- Retrieving Place Details in Places API (New), Places SDK for Android (New), Places SDK for iOS (New), and Places Library.\n- Using Place ID parameters in Maps Embed API.\n- Retrieving search queries in Maps URLs.\n- Displaying speed limits in Roads API.\n- Finding and styling boundary polygons in data-driven styling for boundaries.\n\nFind the ID of a particular place\n---------------------------------\n\nAre you looking for the place ID of a specific place? Use the place ID\nfinder below to search for a place and get its ID:\n\nAlternatively, you can\n[view\nthe place ID finder](/maps/documentation/javascript/examples/places-placeid-finder) with its code in the Maps JavaScript API\ndocumentation.\n\nOverview\n--------\n\nA place ID is a textual identifier that uniquely identifies a place. The\nlength of the identifier may vary (there is no maximum length for place IDs).\nExamples:\n\n- `\n ChIJgUbEo8cfqokR5lP9_Wh_DaM\n `\n- `\n GhIJQWDl0CIeQUARxks3icF8U8A\n `\n- `\n EicxMyBNYXJrZXQgU3QsIFdpbG1pbmd0b24sIE5DIDI4NDAxLCBVU0EiGhIYChQKEgnRTo6ixx-qiRHo_bbmkCm7ZRAN\n `\n- `\n EicxMyBNYXJrZXQgU3QsIFdpbG1pbmd0b24sIE5DIDI4NDAxLCBVU0E\n `\n- `\n IhoSGAoUChIJ0U6OoscfqokR6P225pApu2UQDQ\n `\n\nPlace IDs are available for most locations, including businesses, landmarks,\nparks, and intersections. It is possible for the same place or location to\nhave multiple different place IDs. Place IDs may change over time.\n\nYou can use the same place ID across the Places API and a\nnumber of Google Maps Platform APIs. For example, you can use the same place ID to\nreference a place in the\n[Places API](/maps/documentation/places), the\n[Maps JavaScript API](/maps/documentation/javascript/places),\nthe [Geocoding API](/maps/documentation/geocoding),\nthe [Maps Embed API](/maps/documentation/embed)\nand the [Roads API](/maps/documentation/roads/speed-limits).\n\nRetrieve place details using the place ID\n-----------------------------------------\n\nA common way of using place IDs is to search for a place\n(using the [Places API](/maps/documentation/places/web-service)\nor the [Places\nlibrary](/maps/documentation/javascript/places#place_searches) in the Maps JavaScript API, for example) then use the\nreturned place ID to retrieve place details. You can store the place ID and\nuse it to retrieve the same place details later. Read about\n[saving place IDs](#save-id) below.\n\nThe following examples show how to request an icon URL for Places API (New) and\nPlaces API (Legacy). \n\n### Places API (New)\n\nUsing the Places API, you can find a place ID by doing a\n[Text Search (New)](/maps/documentation/places/web-service/text-search)\nrequest. \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: places.id,places.displayName,places.formattedAddress' \\\n'https://places.googleapis.com/v1/places:searchText'\n```\n\nThe response includes a place ID in the `id` field, as shown below: \n\n```text\n{\n \"places\": [\n {\n \"id\": \"ChIJs5ydyTiuEmsR0fRSlU0C7k0\",\n \"formattedAddress\": \"29 King St, Sydney NSW 2000, Australia\",\n \"displayName\": {\n \"text\": \"Peace Harmony\",\n \"languageCode\": \"en\"\n }\n },\n ...\n}\n```\n\nNow you can now make a\n[Place Details (New)](/maps/documentation/places/web-service/place-details)\nrequest by including the place ID in the request URL: \n\n```scdoc\nhttps://places.googleapis.com/v1/places/ChIJs5ydyTiuEmsR0fRSlU0C7k0?fields=id,displayName&key=API_KEY\n```\n\n### Places API (Legacy)\n\nUsing the Places API, you can find a place ID by doing a\n[Place Search](/maps/documentation/places/web-service/search) request.\n\nThe following example is a search request for places of type 'restaurant'\nwithin a 1500m radius of a point in Sydney, Australia, containing the word\n'cruise': \n\n```carbon\nhttps://maps.googleapis.com/maps/api/place/nearbysearch/json?location=-33.8670522,151.1957362&radius=1500&type=restaurant&keyword=cruise&key=YOUR_API_KEY\n```\n\nThe response includes a place ID in the `place_id` field, as\nshown in this snippet: \n\n```scdoc\n{\n \"html_attributions\" : [],\n \"results\" : [\n {\n \"geometry\" : {\n \"location\" : {\n \"lat\" : -33.870775,\n \"lng\" : 151.199025\n }\n },\n ...\n \"place_id\" : \"ChIJrTLr-GyuEmsRBfy61i59si0\",\n ...\n }\n ],\n \"status\" : \"OK\"\n}\n```\n\nNow you can send a\n[Place Details (Legacy) request](/maps/documentation/places/web-service/details#PlaceDetailsRequests),\nputting the place ID in the `place_id` parameter: \n\n```scdoc\nhttps://maps.googleapis.com/maps/api/place/details/json?place_id=ChIJrTLr-GyuEmsRBfy61i59si0&key=YOUR_API_KEY\n```\n\nSave place IDs for later use\n----------------------------\n\nPlace IDs are **exempt from** the caching restrictions stated in\n[Section 3.2.3(b)](https://cloud.google.com/maps-platform/terms#3.-license.)\nof the Google Maps Platform Terms of Service. You can therefore store place ID values for later\nuse.\n\n### Refresh stored place IDs\n\nBecause Place IDs may change due to updates on the Google Maps database, Google recommends\nrefreshing place IDs if they are more than 12 months old. You can refresh Place IDs **at no\ncharge** by making a\n\n[Place Details request](/maps/documentation/places/web-service/place-details#GetPlaceRequest), specifying only the place ID\n\n\nfield in the `fields` parameter. \n\n### Places API (New)\n\nFor example, using [Place Details (New)](/maps/documentation/places/web-service/place-details): \n\n```scdoc\nhttps://places.googleapis.com/v1/places/ChIJ05IRjKHxEQ0RJLV_5NLdK2w?fields=id&key=API_KEY\n```\n\n### Places API (Legacy)\n\nFor example, using [Places API (Legacy)](/maps/documentation/places/web-service/details): \n\n```scdoc\nhttps://maps.googleapis.com/maps/api/place/details/json?place_id=ChIJ05IRjKHxEQ0RJLV_5NLdK2w&fields=place_id&key=API_KEY\n```\n\nThis call triggers the\n\n\n[Place Detail New Essentials IDs Only](/maps/billing-and-pricing/sku-details#place-details-id-only-ess-sku) or\n\n\n[Places Details - ID Refresh](/maps/billing-and-pricing/sku-details#place-details-id-refresh-ess-sku)\n\n\nSKU.\n\nError codes when using place IDs\n--------------------------------\n\n### `INVALID_REQUEST`\n\nThe `INVALID_REQUEST` status code indicates that the specified\nplace ID is not valid. `INVALID_REQUEST` may be returned when the\nplace ID has been truncated or otherwise modified, and is no longer correct.\n\n### `NOT_FOUND`\n\nThe `NOT_FOUND` status code indicates that the specified place ID\nis obsolete. A place ID may become obsolete if a business closes or moves to\na new location. Place IDs may also change due to updates on the Google\nMaps database. In such cases, a place may receive a new place ID, and the old\nID returns a `NOT_FOUND` response.\n| **Note:** Place IDs that are obsolete may continue to be returned in Place Autocomplete (Legacy), Query Autocomplete (Legacy), or Autocomplete (New) responses for a few days after the place ID has been removed from the Google Maps database.\n\nTo refresh results in the event of an obsolete place ID, store the original request that\nreturned each place ID and re-issue the request as needed. Note that the **re-issued request is\nbilled at the appropriate SKU.**\n\nSome types of place IDs may sometimes cause a\n`NOT_FOUND` response, or the API may return a different place ID in\nthe response. These place ID types include:\n\n- Street addresses that don't exist in Google Maps as precise addresses, but are inferred from a range of addresses.\n- Segments of a long route, where the request also specifies a city or locality.\n- Intersections.\n- Places with an address component of type `subpremise`.\n\nThese IDs often take the form of a long string (there is no maximum length\nfor Place IDs). For example: \n\n```\nEpID4LC14LC_4LCo4LCv4LGN4LCo4LCX4LCw4LGNIC0g4LC44LGI4LCm4LGN4LCs4LC-4LCm4LGNIOCwsOCxi-CwoeCxjeCwoeCxgSAmIOCwteCwv-CwqOCwr-CxjSDgsKjgsJfgsLDgsY0g4LCu4LGG4LCv4LC_4LCo4LGNIOCwsOCxi-CwoeCxjeCwoeCxgSwg4LC14LC_4LCo4LCv4LGNIOCwqOCwl-CwsOCxjSDgsJXgsL7gsLLgsKjgsYAsIOCwsuCwleCxjeCwt-CxjeCwruCwv-CwqOCwl-CwsOCxjSDgsJXgsL7gsLLgsKjgsYAsIOCwuOCwsOCxguCwsOCxjSDgsKjgsJfgsLDgsY0g4LC14LGG4LC44LGN4LCf4LGNLCDgsLjgsK_gsYDgsKbgsL7gsKzgsL7gsKbgsY0sIOCwueCxiOCwpuCwsOCwvuCwrOCwvuCwpuCxjSwg4LCk4LGG4LCy4LCC4LCX4LC-4LCjIDUwMDA1OSwg4LCt4LC-4LCw4LCk4LCm4LGH4LC24LCCImYiZAoUChIJ31l5uGWYyzsR9zY2qk9lDiASFAoSCd9ZebhlmMs7Efc2NqpPZQ4gGhQKEglDz61OZpjLOxHgDJCFY-o1qBoUChIJi37TW2-YyzsRr_uv50r7tdEiCg1MwFcKFS_dyy4\n```"]]
