این آموزش نحوه ایجاد و ویرایش داده های مکان را نشان می دهد. 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 استفاده کنید.
برای ایجاد یک مکان، از موارد زیر استفاده کنید:
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 را برگردانید
برای بازگرداندن نسخه Google Maps یک مکان، googleUpdated به URL درخواست اضافه کنید، مانند مثال زیر:
GET
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}:googleUpdated?readMask={commaSeparatedFieldsToRetrieve}
اگر هیچ نتیجه ای وجود نداشت، کد وضعیت 404 NOT FOUND HTTP برگردانده می شود. جزئیات بیشتر در مورد مدیریت به روز رسانی های گوگل را می توانید در اینجا بیابید.
مکان ها را فهرست کنید
وقتی یک یا چند مکان را مدیریت می‌کنید، ممکن است بخواهید همه مکان‌های مرتبط با حساب خود را فهرست کنید. از accounts.locations.list API برای فهرست کردن همه مکان‌های مرتبط با یک کاربر استفاده کنید.
برای فهرست کردن همه مکان‌هایی که مستقیماً تحت مالکیت یا مدیریت یک کاربر احراز هویت هستند، از موارد زیر استفاده کنید:
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 درایو» با «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
جستجو بر اساس فاصله یا حساب
مثال زیر نشان می دهد که چگونه می توانید مکان هایی را در فاصله معینی از یک نقطه جغرافیایی جستجو کنید:
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 | نام دنیای واقعی کسب و کار |
categories | ترکیبی از دسته اولیه و دسته های اضافی. توجه داشته باشید که "gcid:" باید حذف شود. اگر چندین دسته وجود دارد، اگر حداقل یک دسته با این الگو مطابقت داشته باشد، این فیلتر مطابقت دارد. |
phone_numbers.primary_phone | شماره تلفن اصلی در قالب E.164 (به عنوان مثال: "+441234567890"). |
storefront_address.region_code | کد منطقه CLDR کشور/منطقه آدرس |
storefront_address.administrative_area | بالاترین بخش اداری که برای آدرس های پستی یک کشور یا منطقه استفاده می شود |
storefront_address.locality | بخش شهر/شهرک آدرس |
storefront_address.postal_code | کد پستی آدرس |
metadata.place_id | اگر این مکان تأیید شده باشد و به Google Maps متصل باشد/در Google Maps ظاهر شود، این قسمت برابر با شناسه مکان برای مکان است. |
openInfo.status | نشان می دهد که آیا مکان در حال حاضر برای تجارت باز است یا خیر ( |
labels | مجموعه ای از رشته های آزاد که به شما امکان می دهد کسب و کار خود را برچسب گذاری کنید. برخلاف تمام فیلدهای دیگر، این مقدار باید دقیقاً با یک برچسب کامل شامل پوشش و نه تنها یک نشانه مطابقت داشته باشد. به عنوان مثال، اگر یک برچسب "XX YY" باشد، هیچ کدام "XX" یا "xx yy" مطابقت ندارند. |
storeCode | شناسه خارجی برای این مکان، که باید در یک حساب مشخص منحصر به فرد باشد |
| کارکرد | |
distance | به شما امکان می دهد بر اساس فاصله مکان از یک نقطه جغرافیایی فیلتر کنید. |
مرتب سازی بر اساس فیلد پرس و جو
می توانید نتایج را بر اساس نام کسب و کار یا کد فروشگاه، به ترتیب صعودی یا نزولی مرتب کنید. چندین معیار ترتیب با کاما در رشته orderBy از هم جدا می شوند، مانند مثال زیر:
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&orderBy=locationName,storeCode
یک مکان را وصله کنید
از My Business Business Information API برای به‌روزرسانی یک یا چند فیلد برای مکان دارای locations.patch استفاده کنید.
برای تغییر یک یا چند فیلد برای یک مکان، از موارد زیر استفاده کنید:
فیلدها و مقادیر به روز شده را با فیلد مکان اضافه کنید و از یک لیست فیلدهای به روز شده جدا شده با کاما به عنوان مقدار fieldMask استفاده کنید.
PATCH
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?languageCode=language&validateOnly=True|False&updateMask=title
{
"title": "Google Shoes"
}