کار کردن با داده‌های مکان

این آموزش نحوه ایجاد و ویرایش داده‌های مکان را نشان می‌دهد. My Business Business Information API به شما امکان می‌دهد کارهای زیر را انجام دهید:

• مکان جدیدی ایجاد کنید.
• حذف مکان.
• دریافت مکان با نام منبع.
• فهرست کردن همه مکان‌های حساب.
• یک یا چند فیلد را برای مکانی به‌روز کنید.

از مکان‌ها می‌توان در Ads استفاده کرد، اما برای اینکه واجدشرایط نمایش در «جستجو» و Maps باشند، باید به‌تأیید برسند. داده‌های مکان با مجموعه accounts.locations نشان داده می‌شود.

قبل‌از شروع

قبل‌از استفاده از My Business Business Information API، باید برنامه‌تان را ثبت کنید و اطلاعات اعتباری OAuth 2.0 را دریافت کنید. برای جزئیات درباره نحوه شروع کار با My Business Business Information API، به راه‌اندازی اولیه مراجعه کنید.

ایجاد مکان

می‌توانید از My Business Business Information API برای ایجاد مکان جدید برای کسب‌وکار با accounts.locations.create استفاده کنید.

برای ایجاد مکان، از موارد زیر استفاده کنید:

POST
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?requestId=requestId&validateOnly=True|False

{
    "storeCode": "GOOG-SYD",
    "languageCode": "en-AU",
    "title": "Google Sydney",
    "phoneNumbers": {
      "primaryPhone": "02 9374 4000"
     },
    "storefrontAddress": {
      "addressLines": [
        "Level 5",
        "48 Pirrama Road"
      ],
      "locality": "Pyrmont",
      "postalCode": "2009",
      "administrativeArea": "NSW",
      "regionCode": "AU"
    },
    "websiteUri": "https://www.google.com.au/",
    "regularHours": {
      "periods": [
        {
          "openDay": "MONDAY",
          "closeDay": "MONDAY",
          "openTime": "09:00",
          "closeTime": "17:00"
        },
        {
          "openDay": "TUESDAY",
          "closeDay": "TUESDAY",
          "openTime": "09:00",
          "closeTime": "17:00"
        },
        {
          "openDay": "WEDNESDAY",
          "closeDay": "WEDNESDAY",
          "openTime": "09:00",
          "closeTime": "17:00"
        },
        {
          "openDay": "THURSDAY",
          "closeDay": "THURSDAY",
          "openTime": "09:00",
          "closeTime": "17:00"
        },
        {
          "openDay": "FRIDAY",
          "closeDay": "FRIDAY",
          "openTime": "09:00",
          "closeTime": "17:00"
        }
      ]
    },
    "categories": {
      "primaryCategory": {
        "name": "gcid:software_company"
      }
     }
}

حذف مکان

می‌توانید از My Business Business Information API برای حذف مکان با locations.delete استفاده کنید.

برای حذف مکان، از موارد زیر استفاده کنید:

DELETE
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}

دریافت مکان با نام

اگر کسب‌وکارهای زیادی با حسابتان مرتبط است، شاید بخواهید یک مکان را دریافت کنید. می‌توانید براساس نام کسب‌وکار فیلتر کنید تا مکان خاصی را با locations.get دریافت کنید.

برای دریافت مکان براساس نام، از موارد زیر استفاده کنید. برای بازیابی فیلدهای خاص، باید readMask را مشخص کنید. :

GET
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?readMask={commaSeparatedFieldsToRetrieve}

برگرداندن نسخه Google Maps

GET
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}:googleUpdated?readMask={commaSeparatedFieldsToRetrieve}

اگر نتیجه‌ای وجود نداشته باشد، رمز وضعیت اچ‌تی‌تی‌پی 404 NOT FOUND برگردانده می‌شود. برای جزئیات بیشتر درباره مدیریت به‌روزرسانی‌های Google، پذیرفتن یا رد کردن به‌روزرسانی‌ها را ببینید.

Return extended location data and edit status (v1alpha)

برای بازیابی داده‌های مکان ارائه‌شده توسط فروشنده و داده‌های مکان ارائه‌شده به مصرف‌کننده به‌همراه مراحل چرخه حیات ویرایش هر فیلد (مانند EDIT_LIFECYCLE_STAGE_PENDING یا EDIT_LIFECYCLE_STAGE_REJECTED)، منبع ویرایش (SOURCE_API یا SOURCE_UI)، و دلایل نقض خط‌مشی در یک تماس، از locations.getExtended در v1alpha استفاده کنید:

GET
https://mybusinessbusinessinformation.googleapis.com/v1alpha/locations/{locationId}:getExtended

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

فهرست کردن مکان‌ها

وقتی یک یا چند مکان را مدیریت می‌کنید، ممکن است بخواهید همه مکان‌های مرتبط با حسابتان را فهرست کنید. از accounts.locations.list API برای فهرست کردن همه مکان‌های مرتبط با کاربر استفاده کنید.

برای فهرست کردن همه مکان‌هایی که مستقیماً تحت مالکیت یا مدیریت کاربر اصالت‌سنجی‌شده است، از موارد زیر استفاده کنید:

GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}

از نویسه عام '-' برای حساب در نشانی وب درخواست استفاده کنید تا فهرستگان تحت مالکیت غیرمستقیم (تحت مالکیت یا مدیریت ازطریق گروه) را اضافه کنید:

GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/-/locations?readMask={commaSeparatedFieldsToRetrieve}

فیلتر کردن نتایج هنگام فهرست کردن مکان‌ها

GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter={FIELD_NAME}=%22{YOUR_QUERY}%22

نحو پُرسمان پایه

محدودیت دارای نحو زیر است: <field><operator><value>، که در آن عملگر یا EQUALS (=) یا HAS (:) است. عملگرهای EQUALS (=) و HAS (:) برای همه فیلدها به‌جز locationName معادل هستند (جدول زیر را ببینید).

علامت‌های نقل‌قول به‌صورت «%22» و فاصله‌ها به‌صورت علامت جمع (+) کدگذاری می‌شوند.

مگر اینکه طور دیگری ذکر شده باشد، همه مقایسه‌ها مقایسه‌های نشانه‌ای غیرحساس به حروف بزرگ و کوچک هستند. برای مثال، «4 drive» با «4, Privet Drive» مطابقت دارد.

ترکیب کردن چند فیلد در پُرسمان فیلتر

میانای برنامه‌سازی کاربردی اجازه می‌دهد AND همه محدودیت‌های فیلدها را متصل کند. اما وقتی نوبت به کلیدواژه OR می‌رسد، همه محدودیت‌ها باید بر همان فیلد اعمال شود. برای مثال: locationName=A یا labels=B مجاز نیست.

مثال

مثال زیر عبارت فیلتری را نشان می‌دهد که همه مکان‌های دارای نام «Pepé Le Pew» را برمی‌گرداند. این مکان دسته‌های «رستوران فرانسوی» یا «رستوران اروپایی» و برچسب «تازه افتتاح‌شده» را نشان می‌دهد.

locationName=%22Pepé+Le+Pew%22+AND+
(categories=%22french_restaurant%22+OR+
categories=%22european_restaurant%22)+AND+
labels=%22newly+open%22

جستجو براساس فاصله یا حساب

مثال زیر نشان می‌دهد که چگونه می‌توانید مکان‌ها را در فاصله مشخصی از یک نقطه جغرافیایی جستجو کنید:

GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=distance(latlng, geopoint({latitude}, {longitude}))<{distance}

GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=distance(latlng, geopoint(40.01, -105.27))<1000.0

فهرست همه فیلدهای فیلتر پشتیبانی‌شده

در زیر فهرست کاملی از همه فیلدهایی که می‌توانند برای فیلتر کردن استفاده شوند ارائه شده است:

مرتب‌سازی براساس فیلد پرسمان

می‌توانید نتایج را براساس نام کسب‌وکار یا کد فروشگاه، به‌ترتیب صعودی یا نزولی مرتب کنید. معیارهای چندگانه سفارش با کاما در رشته orderBy از هم جدا می‌شوند، مانند مثال زیر:

GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&orderBy=locationName,storeCode

وصله کردن مکان

از My Business Business Information API برای به‌روزرسانی یک یا چند فیلد برای مکان با locations.patch استفاده کنید.

برای تغییر یک یا چند فیلد برای مکان، از موارد زیر استفاده کنید:

PATCH
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?languageCode=language&validateOnly=True|False&updateMask=title
{
    "title": "Google Shoes"
}