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

این آموزش نحوه ایجاد و ویرایش داده‌های مکانی را نشان می‌دهد. API اطلاعات کسب و کار من (My Business Business) امکان انجام موارد زیر را برای شما فراهم می‌کند:

می‌توان از مکان‌ها در تبلیغات استفاده کرد، اما برای اینکه واجد شرایط نمایش در جستجو و نقشه‌ها باشند، باید تأیید شوند. داده‌های مکان توسط مجموعه accounts.locations نمایش داده می‌شوند.

قبل از اینکه شروع کنی

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

ایجاد یک مکان

شما می‌توانید از 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"
      }
     }
}

حذف یک مکان

شما می‌توانید از API اطلاعات کسب و کار من برای حذف یک مکان با استفاده از locations.delete استفاده کنید.

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

اچ‌تی‌پی 
DELETE
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}

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

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

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

اچ‌تی‌پی 
GET
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?readMask={commaSeparatedFieldsToRetrieve}

نسخه نقشه‌های گوگل را برگردانید

اچ‌تی‌پی

برای برگرداندن نسخه نقشه گوگل یک مکان، googleUpdated را به URL درخواست اضافه کنید، مانند مثال زیر:

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

اگر نتیجه‌ای وجود نداشته باشد، کد وضعیت HTTP 404 NOT FOUND برگردانده می‌شود. برای جزئیات بیشتر در مورد مدیریت به‌روزرسانی‌های گوگل، به بخش «پذیرش یا رد به‌روزرسانی‌ها» مراجعه کنید.

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

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

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

اچ‌تی‌پی 
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}

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

اچ‌تی‌پی 
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/-/locations?readMask={commaSeparatedFieldsToRetrieve}

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

اچ‌تی‌پی

شما می‌توانید از فیلترها برای محدود کردن نتایجی که هنگام فراخوانی accounts.locations.list برگردانده می‌شوند، استفاده کنید. برای فیلتر کردن یک درخواست، یک عبارت فیلتر را همانطور که در این مثال نشان داده شده است، به URL پایه اضافه کنید:

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" مطابقت دارد.

ترکیب چندین فیلد در یک پرس و جوی فیلتر

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

مثال

مثال زیر یک عبارت فیلتر را نشان می‌دهد که تمام مکان‌های دارای نام "Pepé Le Pew" را برمی‌گرداند. این عبارت، دسته‌بندی‌هایی برای "french_restaurant" یا "european_restaurant" و برچسب "newly open" را نشان می‌دهد.

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

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

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

فیلدها شرح و مثال
فیلدهای تطبیق رشته
title

نام واقعی کسب و کار در دنیای واقعی

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/ {accountId} /locations?readMask= {commaSeparatedFieldsToRetrieve} &filter=title:"Bajis" (با هر نام مکانی که "Bajis" به عنوان زیررشته داشته باشد، مطابقت دارد)

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/ {accountId} /locations?readMask= {commaSeparatedFieldsToRetrieve} &filter=title="Bajis" (هر نام مکانی که "Bajis" به عنوان توکن/کلمه در آن باشد را مطابقت می‌دهد)

categories

ترکیب دسته اصلی و دسته‌های اضافی. توجه داشته باشید که "gcid:" باید حذف شود. اگر چندین دسته وجود داشته باشد، این فیلتر در صورتی مطابقت دارد که حداقل یک دسته با این الگو مطابقت داشته باشد.

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/ {accountId} /locations?readMask= {commaSeparatedFieldsToRetrieve} &filter=categories="french_restaurant"

phone_numbers.primary_phone

شماره تلفن اصلی با فرمت E.164 (برای مثال: "+441234567890").

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/ {accountId} /locations?readMask= {commaSeparatedFieldsToRetrieve} &filter=phone_numbers.primary_phone="+441234567890"

storefront_address.region_code

کد منطقه CLDR کشور/منطقه آدرس

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/ {accountId} /locations?readMask= {commaSeparatedFieldsToRetrieve} &filter=storefront_address.region_code="US"

storefront_address.administrative_area

بالاترین تقسیم‌بندی اداری که برای آدرس‌های پستی یک کشور یا منطقه استفاده می‌شود

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/ {accountId} /locations?readMask= {commaSeparatedFieldsToRetrieve} &filter=storefront_address.administrative_area="CA"

storefront_address.locality

بخش شهر/شهرستان آدرس

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/ {accountId} /locations?readMask= {commaSeparatedFieldsToRetrieve} &filter=storefront_address.locality="New York"

storefront_address.postal_code

کد پستی آدرس

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/ {accountId} /locations?readMask= {commaSeparatedFieldsToRetrieve} &filter=storefront_address.postal_code="12345"

metadata.place_id

اگر این مکان تأیید شده باشد و به نقشه‌های گوگل متصل باشد/در آنها نمایش داده شود، این فیلد برابر با شناسه مکان برای آن مکان است.

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/ {accountId} /locations?readMask= {commaSeparatedFieldsToRetrieve} &filter=metadata.place_id="12345"

openInfo.status

نشان می‌دهد که آیا مکان در حال حاضر برای کسب و کار باز است یا خیر ( OPEN ، CLOSED_PERMANENTLY )

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/ {accountId} /locations?readMask= {commaSeparatedFieldsToRetrieve} &filter=openInfo.status="OPEN"

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/ {accountId} /locations?readMask= {commaSeparatedFieldsToRetrieve} &filter=openInfo.status="CLOSED_PERMANENTLY"

labels

مجموعه‌ای از رشته‌های آزاد که به شما امکان می‌دهد کسب‌وکار خود را برچسب‌گذاری کنید. برخلاف سایر فیلدها، این مقدار باید دقیقاً با یک برچسب کامل شامل حروف کوچک و نه فقط یک توکن مطابقت داشته باشد. مثلاً اگر یک برچسب "XX YY" باشد، نه "XX" و نه "xx yy" مطابقت نخواهند داشت.

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/ {accountId} /locations?readMask= {commaSeparatedFieldsToRetrieve} &filter=labels="newly open"

storeCode

شناسه خارجی برای این مکان، که باید در یک حساب کاربری مشخص منحصر به فرد باشد

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/ {accountId} /locations?readMask= {commaSeparatedFieldsToRetrieve} &filter=storeCode="12345"

توابع
distance

به شما امکان می‌دهد بر اساس فاصله مکان از یک نقطه جغرافیایی فیلتر کنید.

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

مرتب سازی بر اساس فیلد جستجو

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

اچ‌تی‌پی 
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&orderBy=locationName,storeCode

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

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

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

اچ‌تی‌پی

فیلدها و مقادیر به‌روزرسانی‌شده را به همراه فیلد مکان اضافه کنید و از فهرستی از فیلدهای به‌روزرسانی‌شده که با کاما از هم جدا شده‌اند، به عنوان مقدار fieldMask استفاده کنید. 

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