במדריך הזה מוסבר איך ליצור ולערוך נתוני מיקום. באמצעות My Business Business Information API אתם יכולים:
- יוצרים מיקום חדש.
- מחיקת מיקום
- קבלת מיקום לפי שם המשאב.
- הצגת רשימה של כל המיקומים בחשבון.
- עדכון של שדה אחד או יותר במיקום.
אפשר להשתמש במיקומים ב-Google Ads, אבל צריך לאמת אותם כדי שהם יוכלו להופיע בחיפוש Google ובמפות Google. נתוני המיקום מיוצגים על ידי האוסף 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
כדי להחזיר את הגרסה של מיקום במפות Google, מוסיפים את הפרמטר googleUpdated לכתובת ה-URL של הבקשה, כמו בדוגמה הבאה:
GET
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}:googleUpdated?readMask={commaSeparatedFieldsToRetrieve}
אם אין תוצאות, מוחזר קוד סטטוס של HTTP 404 NOT FOUND. פרטים נוספים על ניהול עדכונים של Google זמינים במאמר אישור או דחייה של עדכונים.
החזרת נתוני מיקום מורחבים וסטטוס עריכה (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
במאמר בדיקת סטטוס העריכה של מיקומים ומאפיינים מופיעות דוגמאות לתגובות מלאות ופרטים על הפרשנות של סטטוס העריכה והפרות המדיניות בכל שדה.
הצגת רשימה של מיקומים
אם אתם מנהלים מיקום אחד או יותר, יכול להיות שתרצו להציג את כל המיקומים שמשויכים לחשבון שלכם. משתמשים ב-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}
כדי לסנן מיקומים בטווח של 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 או מופיע בהן, השדה הזה זהה למזהה המקום של המיקום.
|
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"
}