עבודה עם נתוני מיקום

במדריך הזה מוסבר איך ליצור ולערוך נתוני מיקום. באמצעות 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.

כדי ליצור מיקום, משתמשים בשיטה הבאה:

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

HTTP

כדי להחזיר את הגרסה של מיקום במפות 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:

HTTP
GET
https://mybusinessbusinessinformation.googleapis.com/v1alpha/locations/{locationId}:getExtended

במאמר בדיקת סטטוס העריכה של מיקומים ומאפיינים מופיעות דוגמאות לתגובות מלאות ופרטים על הפרשנות של סטטוס העריכה והפרות המדיניות בכל שדה.

הצגת רשימה של מיקומים

אם אתם מנהלים מיקום אחד או יותר, יכול להיות שתרצו להציג את כל המיקומים שמשויכים לחשבון שלכם. משתמשים ב-API‏ accounts.locations.list כדי להציג את כל המיקומים שמשויכים למשתמש.

כדי להציג את כל המיקומים שבבעלות ישירה או בניהול ישיר של משתמש מאומת, משתמשים בבקשה הבאה:

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 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

חיפוש לפי מרחק או חשבון

בדוגמה הבאה אפשר לראות איך מחפשים מיקומים במרחק מסוים מנקודה גיאוגרפית:

HTTP
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

השם של העסק בעולם האמיתי

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 או מופיע בהן, השדה הזה זהה למזהה המקום של המיקום.

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"
}