במדריך הזה אנחנו מסבירים איך ליצור ולערוך נתוני מיקום. My Business Information API מאפשר לכם לבצע את הפעולות הבאות:
- יוצרים מיקום חדש.
- למחוק מיקום.
- קבלת מיקום לפי שם המשאב.
- הצגת רשימה של כל המיקומים של חשבון.
- מעדכנים שדה אחד או יותר של מיקום.
אפשר להשתמש במיקומים ב-Google Ads, אבל צריך לאמת אותם כדי שהם יוכלו להופיע בחיפוש ובמפות. נתוני המיקום מיוצגים על ידי האוסף accounts.locations
לפני שמתחילים
לפני שתוכלו להשתמש ב-My Business Information API, עליכם לרשום את הבקשה ולקבל פרטי כניסה ל-OAuth 2.0. במאמר הגדרה בסיסית מוסבר איך מתחילים להשתמש ב-My Business Information API.
יצירת מיקום
אפשר להשתמש ב-My 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" } } }
מחיקת מיקום
באמצעות locations.delete אפשר להשתמש ב-My Business Information API כדי למחוק מיקום.
כדי למחוק מיקום, משתמשים באפשרויות הבאות:
DELETE https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}
קבלת מיקום לפי שם
אם לחשבון שלכם משויכים הרבה עסקים, יכול להיות שתרצו להשתמש במיקום אחד. בעזרת locations.get אפשר לסנן לפי שם העסק כדי להציג מיקום ספציפי.
כדי לקבל מיקום לפי שם, משתמשים בקוד הבא. כדי לאחזר שדות ספציפיים, יש לציין ReadMask. :
GET https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?readMask={commaSeparatedFieldsToRetrieve}
החזרת הגרסה של מפות Google
כדי להחזיר גרסה של מיקום במפות Google, צריך לצרף את
googleUpdated
לכתובת ה-URL של הבקשה, כמו בדוגמה הבאה:
GET https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}:googleUpdated?readMask={commaSeparatedFieldsToRetrieve}
אם לא התקבלו תוצאות, יוחזר קוד מצב HTTP 404 NOT FOUND
. כאן אפשר למצוא פרטים נוספים על ניהול העדכונים של Google.
הצגת רשימה של מיקומים
כשאתם מנהלים מיקום אחד או יותר, כדאי להציג רשימה של כל המיקומים שמשויכים לחשבון. השתמשו ב-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, Drive' יתאים ל-'4, Privet Drive'.
שילוב שדות מרובים בשאילתת מסנן
ה-API מאפשר ל-AND לחבר את כל הגבלות השדות. עם זאת,
כשמדובר במילת המפתח OR, צריך להחיל את כל ההגבלות על אותו השדה. לדוגמה: אסור
locationName=A
או labels=B
.
דוגמה
בדוגמה הבאה מוצג ביטוי סינון שמחזיר את כל המיקומים בשם "Pepé Le Pew". מוצגות בה קטגוריות של "french_restaurant" או "european_restaurant", ואת התווית "פתחתי לאחרונה".
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}
כדי לסנן מיקומים בטווח של 1,000 ק"מ מבולדר, קולורדו, ארה"ב:
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 או מופיע במפות Google, השדה הזה יהיה זהה למזהה המקום של המיקום.
|
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 Information API כדי לעדכן שדה אחד או יותר של מיקום באמצעות locations.patch.
כדי לשנות שדה אחד או יותר של מיקום, צריך להשתמש באפשרויות הבאות:
מוסיפים את השדות והערכים המעודכנים באמצעות שדה המיקום, ומשתמשים ברשימה של השדות המעודכנים שמופרדים בפסיקים בתור הערך של fieldMask
.
PATCH https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?languageCode=language&validateOnly=True|False&updateMask=title { "title": "Google Shoes" }