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

במדריך הזה מוסבר איך ליצור נתוני מיקום ולערוך אותם. My Business Information API מאפשר לכם:

אפשר להשתמש במיקומים ב-Google Ads, אבל הם צריכים להיות מאומת כדי לעמוד בדרישות מופיעים בחיפוש ובמפות Google. נתוני מיקום מיוצגים על ידי accounts.locations האוסף 'עדכונים'.

לפני שמתחילים

לפני שמשתמשים ב-My Business Information API, צריך לרשום את ולקבל פרטי כניסה של OAuth 2.0. לפרטים על תחילת העבודה בעזרת My Business Information API, תוכלו לקרוא את המאמר הגדרה בסיסית.

יצירת מיקום

אפשר להשתמש ב-My 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 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.

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

כשאתם מנהלים מיקום אחד או יותר, כדאי להציג ברשימה את כל המיקומים שמשויכים לחשבון שלך. משתמשים ב 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 Drive' מתאים ל-'4, Privet Drive'.

שילוב שדות מרובים בשאילתת מסנן

ה-API מאפשר ל-AND לחבר את כל ההגבלות בשדות. אבל, לפעמים כשמדובר במילת המפתח OR, כל ההגבלות חייבות לחול השדה הזה. לדוגמה: locationName=A או labels=B אינם מותר.

דוגמה

הדוגמה הבאה מציגה ביטוי סינון שמחזיר את כל המיקומים עם את השם 'פפה לה פיו'. מופיעות בה קטגוריות של 'french_restaurant' או ,"european_restaurant" והתווית 'נפתחו לאחרונה'.

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,600 ק"מ מבולדר, קולורדו, ארה"ב:

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 או מופיע במפות 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 Information API locations.patch.

כדי לשנות שדה אחד או יותר של מיקום מסוים, משתמשים בפעולות הבאות:

HTTP

מוסיפים את השדות ואת הערכים המעודכנים עם שדה המיקום, ומשתמשים ב- רשימה מופרדת בפסיקים של השדות המעודכנים כערך של fieldMask.

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