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

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

مقدمه

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

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

مرورگر APIها به شما امکان می‌دهد درخواست‌های زنده ارسال کنید تا بتوانید با 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 یا هر دو است.

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

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

نام عکس

یک شناسه رشته‌ای که به طور منحصر به فرد یک عکس را مشخص می‌کند. نام عکس‌ها از درخواست‌های Place Details (New) ، Nearby Search (New) یا Text Search (New) در ویژگی 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 نادیده گرفته می‌شود.

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

تمام درخواست‌های مربوط به Place Photos (جدید) باید شامل نام منبع عکس باشند که در پاسخ به درخواست‌های Nearby Search (جدید)، Text Search (جدید) یا Place Details (جدید) برگردانده می‌شود. پاسخ به این درخواست‌ها شامل یک آرایه photos[] است، اگر مکان دارای محتوای عکاسی مرتبط باشد.

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

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

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

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

مثال زیر یک درخواست Place Details (New) را نشان می‌دهد که شامل photos در فیلد mask است، به طوری که پاسخ شامل آرایه 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

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

کدهای خطا

درخواست‌های Place 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. دکمه اجرا را انتخاب کنید. در کادر محاوره‌ای، حسابی را که می‌خواهید برای ارسال درخواست استفاده کنید، انتخاب کنید.

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

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

مقدمه

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

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

مرورگر APIها به شما امکان می‌دهد درخواست‌های زنده ارسال کنید تا بتوانید با 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 یا هر دو است.

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

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

نام عکس

یک شناسه رشته‌ای که به طور منحصر به فرد یک عکس را مشخص می‌کند. نام عکس‌ها از درخواست‌های Place Details (New) ، Nearby Search (New) یا Text Search (New) در ویژگی 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 نادیده گرفته می‌شود.

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

تمام درخواست‌های مربوط به Place Photos (جدید) باید شامل نام منبع عکس باشند که در پاسخ به درخواست‌های Nearby Search (جدید)، Text Search (جدید) یا Place Details (جدید) برگردانده می‌شود. پاسخ به این درخواست‌ها شامل یک آرایه photos[] است، اگر مکان دارای محتوای عکاسی مرتبط باشد.

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

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

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

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

مثال زیر یک درخواست Place Details (New) را نشان می‌دهد که شامل photos در فیلد mask است، به طوری که پاسخ شامل آرایه 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

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

کدهای خطا

درخواست‌های Place 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. دکمه اجرا را انتخاب کنید. در کادر محاوره‌ای، حسابی را که می‌خواهید برای ارسال درخواست استفاده کنید، انتخاب کنید.

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

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

مقدمه

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

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

مرورگر APIها به شما امکان می‌دهد درخواست‌های زنده ارسال کنید تا بتوانید با 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 یا هر دو است.

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

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

نام عکس

یک شناسه رشته‌ای که به طور منحصر به فرد یک عکس را مشخص می‌کند. نام عکس‌ها از درخواست‌های Place Details (New) ، Nearby Search (New) یا Text Search (New) در ویژگی 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 نادیده گرفته می‌شود.

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

تمام درخواست‌های مربوط به Place Photos (جدید) باید شامل نام منبع عکس باشند که در پاسخ به درخواست‌های Nearby Search (جدید)، Text Search (جدید) یا Place Details (جدید) برگردانده می‌شود. پاسخ به این درخواست‌ها شامل یک آرایه photos[] است، اگر مکان دارای محتوای عکاسی مرتبط باشد.

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

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

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

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

مثال زیر یک درخواست Place Details (New) را نشان می‌دهد که شامل photos در فیلد mask است، به طوری که پاسخ شامل آرایه 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

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

کدهای خطا

درخواست‌های Place 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. دکمه اجرا را انتخاب کنید. در کادر محاوره‌ای، حسابی را که می‌خواهید برای ارسال درخواست استفاده کنید، انتخاب کنید.

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