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

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

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

قبل از شروع

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

یک مکان ایجاد کنید

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

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

HTTP
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 استفاده کنید.

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

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

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

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

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

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

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

HTTP

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

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

اگر هیچ نتیجه ای وجود نداشت، کد وضعیت 404 NOT FOUND HTTP برگردانده می شود. جزئیات بیشتر در مورد مدیریت به روز رسانی های گوگل را می توانید در اینجا بیابید.

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

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

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

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

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

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

وقتی مکان‌ها را فهرست می‌کنید، نتایج را فیلتر کنید

HTTP

می‌توانید از فیلترها برای محدود کردن نتایجی که هنگام تماس با 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 درایو» با «4، Privet Drive» مطابقت دارد.

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

API به 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

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

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

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

برای فیلتر کردن مکان ها در 1000 مایلی بولدر، کلرادو ایالات متحده:

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

اگر این مکان تأیید شده باشد و به Google Maps متصل باشد/در Google Maps ظاهر شود، این قسمت برابر با شناسه مکان برای مکان است.

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 از هم جدا می شوند، مانند مثال زیر:

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

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

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

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

HTTP

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

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