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

במדריך הזה מוסבר איך ליצור ולערוך נתוני מיקום. באמצעות ה-API של פרטי העסק ב'עסק שלי', אתם יכולים:

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

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

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

יצירת מיקום

אפשר להשתמש ב-API של פרטי העסק ב-'Google לעסק שלי' כדי ליצור מיקום חדש לעסק באמצעות 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}

אם אין תוצאות, קוד הסטטוס 404 NOT FOUND‏ HTTP מוחזר. כאן אפשר למצוא פרטים נוספים על ניהול עדכוני Google.

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

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

שילוב של כמה שדות בשאילתת סינון

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

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