هذا المنتج أو هذه الميزة في حالة "قديم". لمزيد من المعلومات عن الحالة "قديمة"، يُرجى الاطّلاع على المنتجات والميزات القديمة. لنقل البيانات إلى Places API (الإصدار الجديد)، يُرجى الاطّلاع على دليل نقل البيانات.
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
المطوّرون في المنطقة الاقتصادية الأوروبية
يمكنك استخدام حزمة تطوير برامج "الأماكن" لأجهزة Android لطلب صورة مكان لعرضها في تطبيقك. تأتي الصور التي تعرضها خدمة "صور Google" من
مصادر متنوعة، بما في ذلك صور مالكِي الأنشطة التجارية والصور التي ينشرها المستخدمون.
تعرِض حزمة تطوير برامج "الأماكن" لنظام التشغيل Android صورة نقطية بحجم 1600 x 1600 بكسل كحدٍ أقصى.
عملية استرداد الصور
لاسترداد صورة لمكان، اتّبِع الخطوات التالية:
استخدِم تفاصيل المكان لجلب عنصر Place (استخدِم إما
fetchPlace() أو
findCurrentPlace()).
احرص على تضمين الحقل Place.Field PHOTO_METADATAS في قائمة الحقول التي تريد
تضمينها في عنصر Place في الاستجابة.
// Define a Place ID.valplaceId="INSERT_PLACE_ID_HERE"// Specify fields. Requests for photos must always have the PHOTO_METADATAS field.valfields=listOf(Place.Field.PHOTO_METADATAS)// Get a Place object (this example uses fetchPlace(), but you can also use findCurrentPlace())valplaceRequest=FetchPlaceRequest.newInstance(placeId,fields)placesClient.fetchPlace(placeRequest).addOnSuccessListener{response:FetchPlaceResponse->
valplace=response.place// Get the photo metadata.valmetada=place.photoMetadatasif(metada==null||metada.isEmpty()){Log.w(TAG,"No photo metadata.")return@addOnSuccessListener}valphotoMetadata=metada.first()// Get the attribution text.valattributions=photoMetadata?.attributions// Create a FetchPhotoRequest.valphotoRequest=FetchPhotoRequest.builder(photoMetadata).setMaxWidth(500)// Optional..setMaxHeight(300)// Optional..build()placesClient.fetchPhoto(photoRequest).addOnSuccessListener{fetchPhotoResponse:FetchPhotoResponse->
valbitmap=fetchPhotoResponse.bitmapimageView.setImageBitmap(bitmap)}.addOnFailureListener{exception:Exception->
if(exceptionisApiException){Log.e(TAG,"Place not found: "+exception.message)valstatusCode=exception.statusCodeTODO("Handle error with given status code.")}}}
Java
// Define a Place ID.finalStringplaceId="INSERT_PLACE_ID_HERE";// Specify fields. Requests for photos must always have the PHOTO_METADATAS field.finalList<Place.Field>fields=Collections.singletonList(Place.Field.PHOTO_METADATAS);// Get a Place object (this example uses fetchPlace(), but you can also use findCurrentPlace())finalFetchPlaceRequestplaceRequest=FetchPlaceRequest.newInstance(placeId,fields);placesClient.fetchPlace(placeRequest).addOnSuccessListener((response)->{finalPlaceplace=response.getPlace();// Get the photo metadata.finalList<PhotoMetadata>metadata=place.getPhotoMetadatas();if(metadata==null||metadata.isEmpty()){Log.w(TAG,"No photo metadata.");return;}finalPhotoMetadataphotoMetadata=metadata.get(0);// Get the attribution text.finalStringattributions=photoMetadata.getAttributions();// Create a FetchPhotoRequest.finalFetchPhotoRequestphotoRequest=FetchPhotoRequest.builder(photoMetadata).setMaxWidth(500)// Optional..setMaxHeight(300)// Optional..build();placesClient.fetchPhoto(photoRequest).addOnSuccessListener((fetchPhotoResponse)->{Bitmapbitmap=fetchPhotoResponse.getBitmap();imageView.setImageBitmap(bitmap);}).addOnFailureListener((exception)->{if(exceptioninstanceofApiException){finalApiExceptionapiException=(ApiException)exception;Log.e(TAG,"Place not found: "+exception.getMessage());finalintstatusCode=apiException.getStatusCode();// TODO: Handle error with given status code.}});});
عمليات تحديد المصدر
في معظم الحالات، يمكن استخدام صور الأماكن بدون نسبها إلى مؤلفها، أو سيتم تضمين
نسبة الصورة المطلوبة كجزء من الصورة. ومع ذلك، يمكن أن يحتوي عنصر البيانات الوصفية للصورة من النوع
PhotoMetadata
على أيّ من نوعَي الإسنادَين الإضافيَين التاليَين:
إذا كان عنصر PhotoMetadata المعروض يتضمّن أيًا من نوعَي الإسناد، يجب
تضمين الإسناد في تطبيقك في أي مكان تعرض فيه الصورة. لمزيد من المعلومات،
اطّلِع على عرض الإسناد.
الاستخدام والفوترة
يتم تحصيل رسوم رمز التخزين التعريفي Places Photo مقابل المكالمات إلى fetchPhoto().
اطّلِع على صفحة الاستخدام والفوترة للاطّلاع على التفاصيل.
تاريخ التعديل الأخير: 2025-08-27 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","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-08-27 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["# Place Photos\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\nYou can use the Places SDK for Android to request a place photo to\ndisplay in your application. Photos returned by the photos service come from a\nvariety of sources, including business owners and user-contributed photos.\n\nPlaces SDK for Android returns a bitmap image with a maximum\nsize of 1600 by 1600 pixels.\n\nPhoto retrieval process\n-----------------------\n\nTo retrieve an image for a place:\n\n1. Use [Place Details](/maps/documentation/places/android-sdk/legacy/place-details) to fetch a `Place` object (use either [`fetchPlace()`](/maps/documentation/places/android-sdk/legacy/reference/com/google/android/libraries/places/api/net/PlacesClient#fetchPlace(com.google.android.libraries.places.api.net.FetchPlaceRequest)) or [`findCurrentPlace()`](/maps/documentation/places/android-sdk/legacy/reference/com/google/android/libraries/places/api/net/PlacesClient#findCurrentPlace(com.google.android.libraries.places.api.net.FindCurrentPlaceRequest))). Be sure to include the `Place.Field PHOTO_METADATAS` field in the list of fields to include in the response `Place` object.\n2. In the [`OnSuccessListener`](https://developer.android.com/reference/com/google/android/play/core/tasks/OnSuccessListener) for your [`FetchPlaceResponse`](/maps/documentation/places/android-sdk/legacy/reference/com/google/android/libraries/places/api/net/FetchPlaceResponse) or [`FindCurrentPlaceResponse`](/maps/documentation/places/android-sdk/legacy/reference/com/google/android/libraries/places/api/net/FindCurrentPlaceResponse), use [`Place.getPhotoMetadas()`](/maps/documentation/places/android-sdk/legacy/reference/com/google/android/libraries/places/api/model/Place#getPhotoMetadatas()) to get the photo metadata object, of type [`PhotoMetadata`](/maps/documentation/places/android-sdk/legacy/reference/com/google/android/libraries/places/api/model/PhotoMetadata) from the response `Place` object.\n3. Create a [`FetchPhotoRequest`](/maps/documentation/places/android-sdk/legacy/reference/com/google/android/libraries/places/api/net/FetchPhotoRequest) object, optionally specifying maximum height and width (in pixels). Photos can have a maximum width or height of 1600px.\n4. Use [`PlacesClient.fetchPhoto()`](/maps/documentation/places/android-sdk/legacy/reference/com/google/android/libraries/places/api/net/PlacesClient#fetchPhoto(com.google.android.libraries.places.api.net.FetchPhotoRequest)) to request the photo bitmap.\n5. Add an `OnSuccessListener` and get the photo from the [`FetchPhotoResponse`](/maps/documentation/places/android-sdk/legacy/reference/com/google/android/libraries/places/api/net/FetchPhotoResponse).\n\nGet a photo\n-----------\n\nThe following example demonstrates getting a place photo: \n\n### Kotlin\n\n```kotlin\n// Define a Place ID.\nval placeId = \"INSERT_PLACE_ID_HERE\"\n\n// Specify fields. Requests for photos must always have the PHOTO_METADATAS field.\nval fields = listOf(Place.Field.PHOTO_METADATAS)\n\n// Get a Place object (this example uses fetchPlace(), but you can also use findCurrentPlace())\nval placeRequest = FetchPlaceRequest.newInstance(placeId, fields)\n\nplacesClient.fetchPlace(placeRequest)\n .addOnSuccessListener { response: FetchPlaceResponse -\u003e\n val place = response.place\n\n // Get the photo metadata.\n val metada = place.photoMetadatas\n if (metada == null || metada.isEmpty()) {\n Log.w(TAG, \"No photo metadata.\")\n return@addOnSuccessListener\n }\n val photoMetadata = metada.first()\n\n // Get the attribution text.\n val attributions = photoMetadata?.attributions\n\n // Create a FetchPhotoRequest.\n val photoRequest = FetchPhotoRequest.builder(photoMetadata)\n .setMaxWidth(500) // Optional.\n .setMaxHeight(300) // Optional.\n .build()\n placesClient.fetchPhoto(photoRequest)\n .addOnSuccessListener { fetchPhotoResponse: FetchPhotoResponse -\u003e\n val bitmap = fetchPhotoResponse.bitmap\n imageView.setImageBitmap(bitmap)\n }.addOnFailureListener { exception: Exception -\u003e\n if (exception is ApiException) {\n Log.e(TAG, \"Place not found: \" + exception.message)\n val statusCode = exception.statusCode\n TODO(\"Handle error with given status code.\")\n }\n }\n }\n\n \n```\n\n### Java\n\n```java\n// Define a Place ID.\nfinal String placeId = \"INSERT_PLACE_ID_HERE\";\n\n// Specify fields. Requests for photos must always have the PHOTO_METADATAS field.\nfinal List\u003cPlace.Field\u003e fields = Collections.singletonList(Place.Field.PHOTO_METADATAS);\n\n// Get a Place object (this example uses fetchPlace(), but you can also use findCurrentPlace())\nfinal FetchPlaceRequest placeRequest = FetchPlaceRequest.newInstance(placeId, fields);\n\nplacesClient.fetchPlace(placeRequest).addOnSuccessListener((response) -\u003e {\n final Place place = response.getPlace();\n\n // Get the photo metadata.\n final List\u003cPhotoMetadata\u003e metadata = place.getPhotoMetadatas();\n if (metadata == null || metadata.isEmpty()) {\n Log.w(TAG, \"No photo metadata.\");\n return;\n }\n final PhotoMetadata photoMetadata = metadata.get(0);\n\n // Get the attribution text.\n final String attributions = photoMetadata.getAttributions();\n\n // Create a FetchPhotoRequest.\n final FetchPhotoRequest photoRequest = FetchPhotoRequest.builder(photoMetadata)\n .setMaxWidth(500) // Optional.\n .setMaxHeight(300) // Optional.\n .build();\n placesClient.fetchPhoto(photoRequest).addOnSuccessListener((fetchPhotoResponse) -\u003e {\n Bitmap bitmap = fetchPhotoResponse.getBitmap();\n imageView.setImageBitmap(bitmap);\n }).addOnFailureListener((exception) -\u003e {\n if (exception instanceof ApiException) {\n final ApiException apiException = (ApiException) exception;\n Log.e(TAG, \"Place not found: \" + exception.getMessage());\n final int statusCode = apiException.getStatusCode();\n // TODO: Handle error with given status code.\n }\n });\n});\n\n \n```\n| **Note:** For more information on initializing `PlacesClient`, see [Initialize the Places API client](/maps/documentation/places/android-sdk/config#connect-client).\n| You can use a [CancellationToken](/android/reference/com/google/android/gms/tasks/CancellationToken)\n| to attempt to cancel a request to any of the request classes (for example,\n| `FetchPlaceRequest`). Cancellation is done on a best-effort basis.\n| Once a cancellation request is issued, no response will be returned.\n| **Issuing a cancellation token does NOT guarantee that a particular request\n| will be cancelled, and you may still be charged for the request even if no\n| response is returned**.\n\nAttributions\n------------\n\nIn most cases, place photos can be used without attribution, or will have\nthe required attribution included as part of the image. However, the photo metadata object, of type\n[`PhotoMetadata`](/maps/documentation/places/android-sdk/legacy/reference/com/google/android/libraries/places/api/model/PhotoMetadata),\ncan contain either of two types of additional attributions:\n\n- **Attributions** , an attribution string accessed by [`PhotoMetadata.getAttributions()`](/maps/documentation/places/android-sdk/legacy/reference/com/google/android/libraries/places/api/model/PhotoMetadata#public-abstract-string-getattributions).\n- **AuthorAttributions** , an [`AuthorAttributions`](/maps/documentation/places/android-sdk/legacy/reference/com/google/android/libraries/places/api/model/AuthorAttributions) object accessed by [`PhotoMetadata.getAuthorAttributions()`](/maps/documentation/places/android-sdk/legacy/reference/com/google/android/libraries/places/api/model/PhotoMetadata#public-abstract-authorattributions-getauthorattributions).\n\nIf the returned `PhotoMetadata` object includes either type of attribution, you must\ninclude the attribution in your application wherever you display the image. For more information,\nsee [Displaying Attributions](/maps/documentation/places/android-sdk/legacy/attributions#photos).\n\nUsage and billing\n-----------------\n\nA **Places Photo** SKU is charged for calls to `fetchPhoto()`.\nSee the [Usage and Billing](/maps/documentation/places/android-sdk/legacy/usage-and-billing#places-photo-legacy-ent-sku) page for details."]]