Place Photos (جدید)

انتخاب پلاتفرم: Android iOS خدمات وب
توسعه‌دهندگان منطقه اقتصادی اروپا (EEA)

مقدمه

سرویس عکس‌های مکان (جدید) یک API فقط‌خواندنی است که به شما امکان می‌دهد محتوای عکاسی با کیفیت بالا به برنامه‌تان اضافه کنید. «عکس‌های مکان» (جدید) به شما امکان می‌دهد به میلیون‌ها عکسی که در پایگاه داده «مکان‌ها» ذخیره شده است دسترسی داشته باشید.

وقتی بااستفاده از درخواست «جزئیات مکان (جدید)»، «جستجوی اطراف (جدید)»، یا «جستجوی نوشتاری (جدید)» اطلاعات مکان دریافت می‌کنید، می‌توانید منابع عکس را نیز برای محتوای عکاسی مربوط درخواست کنید. بااستفاده از Place Photos (New)، می‌توانید به عکس‌های ارجاع‌شده دسترسی پیدا کنید و اندازه تصویر را به اندازه بهینه برای برنامه‌تان تغییر دهید.

‫APIs Explorer به شما امکان می‌دهد درخواست‌های زنده ارسال کنید تا بتوانید با میانای برنامه‌سازی کاربردی و گزینه‌های میانای برنامه‌سازی کاربردی آشنا شوید:

درخواست‌های «عکس‌های جا» (جدید)

درخواست «عکس‌های مکان (جدید)» یک درخواست HTTP GET به نشانی وب در این قالب است: 
https://places.googleapis.com/v1/NAME/media?key=API_KEY&PARAMETERS

که در آن پارامترهای زیر الزامی است:

  • ‫NAME حاوی نام منبع عکس است.
  • API_KEY حاوی کلید میانای API است.
  • ‫PARAMETERS حاوی پارامتر maxHeightPx، پارامتر maxWidthPx، یا هر دو است.

فهرست کامل پارامترهای الزامی و اختیاری در زیر شرح داده شده است.

پارامترهای الزامی

نام عکس

شناسه رشته‌ای که عکس را به‌طور یکتا شناسایی می‌کند. نام‌های عکس از درخواست جزئیات مکان (جدید)، جستجوی اطراف (جدید)، یا جستجوی نوشتاری (جدید) در دارایی name هر عنصر از آرایه photos[] برگردانده می‌شود.

برای مثال، دریافت نام عکس را ببینید.

maxHeightPx و maxWidthPx

حداکثر ارتفاع و عرض موردنظر تصویر را به پیکسل مشخص می‌کند. اگر تصویر کوچک‌تر از مقادیر مشخص‌شده باشد، تصویر اصلی برگردانده خواهد شد. اگر تصویر در هریک از ابعاد بزرگ‌تر باشد، برای مطابقت با بعد کوچک‌تر، مقیاس آن تغییر می‌کند و به نسبت ابعادی اصلی‌اش محدود می‌شود. هر دو ویژگی maxheight و maxwidth یک عدد صحیح بین ۱ و ۴۸۰۰ را می‌پذیرند.

باید maxHeightPx یا maxWidthPx یا هر دو را مشخص کنید.

پارامترهای اختیاری

skipHttpRedirect

اگر false (پیش‌فرض) است، برای برگرداندن تصویر، به تصویر هدایت HTTP انجام دهید. اگر true، از هدایت مجدد رد شوید و پاسخ JSON حاوی جزئیات تصویر را برگردانید. برای مثال:

{
  "name": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw/photos/Aaw_FcKly0DEv3EWmDJyHiEqXIP5mowOc99lN1GzBun6KHH52AZ5fFA/media",
  "photoUri": "https://lh3.googleusercontent.com/a-/AD_cFT-b=s100-p-k-no-mo"
}

این گزینه برای درخواست‌های غیر HTTP نادیده گرفته می‌شود.

دریافت نام عکس

همه درخواست‌های «عکس‌های مکان» (جدید) باید شامل نام منبع عکس باشند که در پاسخ به درخواست «جستجوی اطراف» (جدید)، «جستجوی نوشتاری» (جدید)، یا «جزئیات مکان» (جدید) برگردانده می‌شود. پاسخ به این درخواست‌ها حاوی آرایه photos[] است اگر مکان محتوای عکس مرتبط داشته باشد.

هر عنصر از photo[] شامل فیلدهای زیر است:

  • name — رشته‌ای که حاوی نام منبع عکس است وقتی‌که درخواست عکس می‌دهید. این رشته به‌صورت زیر است:

    places/PLACE_ID/photos/PHOTO_RESOURCE
  • heightPx — حداکثر ارتفاع تصویر، به پیکسل.
  • widthPx — حداکثر عرض تصویر، به پیکسل.
  • authorAttributions[] — هرگونه ارجاع موردنیاز. این فیلد همیشه وجود دارد، اما ممکن است خالی باشد.

عکس‌های برگشتی از «عکس‌های مکان» (جدید) از مکان‌های مختلفی تأمین می‌شوند، ازجمله عکس‌های همیاری‌شده توسط کاربران و مالکان کسب‌وکار. در بیشتر موارد، این عکس‌ها را می‌توان بدون ذکر منبع استفاده کرد، یا منبع موردنیاز به‌عنوان بخشی از تصویر گنجانده شده است. بااین‌حال، اگر عنصر photo برگشتی شامل مقداری در فیلد authorAttributions باشد، باید ارجاع اضافی را در برنامه‌تان در هر جایی که تصویر را نمایش می‌دهید بگنجانید.

مثال زیر درخواست «جزئیات مکان (جدید)» را نشان می‌دهد که شامل photos در پوشش فیلد است تا پاسخ شامل آرایه photos[] در پاسخ باشد:

curl -X GET \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: id,displayName,photos" \
https://places.googleapis.com/v1/places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E
 نمونه‌ای از آرایه photos[] در پاسخ در زیر نشان داده شده است. 
    ...
    "photos" : [
      {
        "name": "places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E/photos/AUacShh3_Dd8yvV2JZMtNjjbbSbFhSv-0VmUN-uasQ2Oj00XB63irPTks0-A_1rMNfdTunoOVZfVOExRRBNrupUf8TY4Kw5iQNQgf2rwcaM8hXNQg7KDyvMR5B-HzoCE1mwy2ba9yxvmtiJrdV-xBgO8c5iJL65BCd0slyI1",
        "widthPx": 6000,
        "heightPx": 4000,
        "authorAttributions": [
          {
            "displayName": "John Smith",
            "uri": "//maps.google.com/maps/contrib/101563",
            "photoUri": "//lh3.googleusercontent.com/a-/AD_cFT-b=s100-p-k-no-mo"
          }
        ]
      },
    ...

درخواست عکس مکان

درخواست نمونه زیر تصویری را بااستفاده از منبع name آن برمی‌گرداند و آن را تغییر اندازه می‌دهد تا حداکثر ۴۰۰ پیکسل ارتفاع و عرض داشته باشد:

https://places.googleapis.com/v1/places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E/photos/ATKogpeivkIjQ1FT7QmbeT33nBSwqLhdPvIWHfrG1WfmgrFjeZYpS_Ls7c7rj8jejN9QGzlx4GoAH0atSvUzATDrgrZic_tTEJdeITdWL-oG3TWi5HqZoLozrjTaxoAIxmROHfV5KXVcLeTdCC6kmZExSy0CLVIG3lAPIgmvUiewNf-ZHYE4-jXYwPQpWHJgqVosvZJ6KWEgowEA-qRAzNTu9VH6BPFqHakGQ7EqBAeYOiU8Dh-xIQC8FcBJiTi0xB4tr-MYXUaF0p_AqzAhJcDE6FAgLqG1s7EsME0o36w2nDRHA-IuoISBC3SIahINE3Xwq2FzEZE6TpNTFVfgTpdPhV8CGLeqrauHn2I6ePm-2hA8-87aO7aClXKJJVzlQ1dc_JuHz6Ks07d2gglw-ZQ3ibCTF5lMtCF9O-9JHyRQXsfuXw/media?maxHeightPx=400&maxWidthPx=400&key=API_KEY

پاسخ درخواست موفق «عکس‌های مکان» (جدید) یک تصویر است.

کدهای خطا

درخواست‌های «عکس‌های مکان» (جدید) ممکن است کدهای خطای زیر را برگردانند.

از سهمیه بیشتر شد (۴۰۳)

اگر درخواست شما از سهمیه دردسترس شما فراتر رود، سرور وضعیت HTTP 403 را برمی‌گرداند و تصویر زیر را نمایش می‌دهد تا نشان دهد که سهمیه فراتر رفته است:

اعلان فراتر رفتن از سهمیه

درخواست نامعتبر (۴۰۴)

اگر سرور نتواند درخواست شما را درک کند، وضعیت HTTP 400 را برمی‌گرداند که نشان‌دهنده درخواست نامعتبر است. رایج‌ترین دلایل برای درخواست نامعتبر عبارت‌اند از:

تعداد درخواست‌ها بسیار زیاد است (۴۲۹)

Google توصیه می‌کند عکس‌ها را درصورت درخواست بار کنید. اگر بخواهید همه تصاویر یک مکان را به‌طور هم‌زمان نشان دهید، ممکن است سرور وضعیت HTTP 429 را برگرداند که نشان می‌دهد عکس‌های زیادی به‌طور هم‌زمان بارگیری شده است. اگر این پیام خطا را دریافت کردید، با «پشتیبانی» تماس بگیرید و درخواست افزایش سهمیه کنید.

امتحان کنید!

‫API Explorer به شما امکان می‌دهد درخواست‌های نمونه‌ای ایجاد کنید تا با API و گزینه‌های API آشنا شوید.

برای درخواست دادن:

  1. نماد API در سمت چپ صفحه را انتخاب کنید.
  2. پارامتر name را روی این مقدار تنظیم کنید: 
    places/PLACE_ID/photos/PHOTO_RESOURCE/media
  3. ‫skipHttpRedirect را روی true تنظیم کنید تا درخواست پاسخ JSON برگرداند. به‌طور پیش‌فرض، درخواست تصویر را برمی‌گرداند که نمی‌تواند توسط «کاوشگر API» نمایش داده شود.
  4. دکمه اجرا را انتخاب کنید. در کادر گفتگو، حسابی را که می‌خواهید برای درخواست استفاده کنید انتخاب کنید.

  5. در پانل «کاوشگر API»، نماد تمام‌صفحه را برای ازهم بازکردن پنجره «کاوشگر API» انتخاب کنید.