العمل مع بيانات الموقع الجغرافي

يوضّح هذا البرنامج التعليمي كيفية إنشاء بيانات الموقع الجغرافي وتعديلها. تمنحك واجهة My Business Business Information API إمكانية إجراء ما يلي:

يمكن استخدام المواقع الجغرافية في "الإعلانات"، ولكن يجب إثبات ملكيتها لتكون مؤهَّلة للظهور على "بحث 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 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".

الجمع بين حقول متعدّدة في طلب بحث باستخدام فلتر

تسمح واجهة برمجة التطبيقات باستخدام AND لربط جميع قيود الحقول. ومع ذلك، عندما يتعلق الأمر بالكلمة الرئيسية OR، يجب أن تنطبق جميع القيود على الحقل نفسه. على سبيل المثال: لا يُسمح باستخدام locationName=A OR 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}

لفلترة المواقع الجغرافية ضمن مسافة 1000 ميل من بولدر، كولورادو، الولايات المتحدة الأمريكية:

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