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

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

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

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

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

درخواست عکس را قرار دهید

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

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

مثال زیر یک درخواست Place Details را نشان می‌دهد که شامل 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/AUacShh3_Dd8yvV2JZMtNjjbbSbFhSv-0VmUN-uasQ2Oj00XB63irPTks0-A_1rMNfdTunoOVZfVOExRRBNrupUf8TY4Kw5iQNQgf2rwcaM8hXNQg7KDyvMR5B-HzoCE1mwy2ba9yxvmtiJrdV-xBgO8c5iJL65BCd0slyI1/media?maxHeightPx=400&maxWidthPx=400&key=API_KEY

پاسخ درخواست موفقیت آمیز عکس مکان یک تصویر است. نوع تصویر به نوع عکس ارسالی اصلی بستگی دارد.

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

تصویر بیش از سهمیه

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

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

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

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

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

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

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