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

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

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

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

מחיקת מיקום

באמצעות locations.delete אפשר להשתמש ב-My Business Information API כדי למחוק מיקום.

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

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.

דוגמה

בדוגמה הבאה מוצג ביטוי סינון שמחזיר את כל המיקומים בשם "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

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

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

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 או מופיע במפות 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"
}