عکس‌های مکان (جدید)

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

مقدمه

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

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

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

درخواست‌های مکان عکس (جدید).

درخواست Place Photos (جدید) یک درخواست HTTP GET به یک URL به شکل زیر است:
https://places.googleapis.com/v1/NAME/media?key=API_KEY&PARAMETERS

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

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

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

پارامترهای مورد نیاز

نام عکس

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

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

maxHeightPx و maxWidthPx

حداکثر ارتفاع و عرض تصویر را بر حسب پیکسل مشخص می کند. اگر تصویر کوچکتر از مقادیر مشخص شده باشد، تصویر اصلی برگردانده می شود. اگر تصویر در هر یک از ابعاد بزرگتر باشد، برای مطابقت با ابعاد کوچکتر از دو بعد، محدود به نسبت تصویر اصلی آن، مقیاس بندی می شود. هر دو ویژگی maxheight و maxwidth یک عدد صحیح بین 1 و 4800 را می پذیرند.

باید 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[] - هر گونه اسناد مورد نیاز. این فیلد همیشه وجود دارد، اما ممکن است خالی باشد.

عکس‌های برگردانده شده توسط Place Photos (جدید) از مکان‌های مختلف، از جمله صاحبان کسب‌وکار و عکس‌های ارائه‌شده توسط کاربر، تهیه شده‌اند. در بیشتر موارد، این عکس‌ها را می‌توان بدون ذکر منبع استفاده کرد یا به عنوان بخشی از تصویر، ارجاع مورد نیاز را در نظر گرفت. با این حال، اگر عنصر 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 منبع آن برمی گرداند و اندازه آن را طوری تغییر می دهد که حداکثر 400 پیکسل بلند و عرض داشته باشد:

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

پاسخ یک درخواست موفق مکان Photos (جدید) یک تصویر است.

کدهای خطا

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

از سهمیه (403) فراتر رفت

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

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

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

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

  • نام عکس ارسالی به درستی مشخص نشده است.
  • این درخواست شامل پارامتر maxHeightPx یا maxWidthPx نبود.
  • مقدار maxHeightPx یا پارامتر maxWidthtPx روی null تنظیم شد.
  • name منقضی شده است. اگر name منقضی شده است، برای دریافت name جدید، از جزئیات مکان (جدید) ، جستجوی نزدیک (جدید) یا جستجوی متن (جدید) درخواست کنید.

درخواست های بسیار زیاد (429)

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

آن را امتحان کنید!

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

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

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

  5. در پانل API Explorer، نماد صفحه را انتخاب کنید تا پنجره API Explorer گسترش یابد.