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

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

• أنشئ موقعًا جغرافيًا جديدًا.
• حذف موقع جغرافي
• الحصول على موقع جغرافي حسب اسم المورد
• إدراج جميع المواقع الجغرافية لحساب
• تعديل حقل واحد أو أكثر لموقع جغرافي

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

لإنشاء موقع جغرافي، استخدِم ما يلي:

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.

لحذف موقع جغرافي، استخدِم ما يلي:

DELETE
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}

الحصول على موقع جغرافي حسب الاسم

إذا كان لديك العديد من المؤسسات المرتبطة بحسابك، قد تحتاج إلى الحصول على موقع جغرافي واحد. يمكنك الفلترة حسب اسم المؤسسة للحصول على موقع جغرافي محدّد باستخدام locations.get.

للحصول على موقع جغرافي حسب الاسم، استخدِم ما يلي. يجب تحديد readMask لاسترداد حقول معيّنة. :

GET
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?readMask={commaSeparatedFieldsToRetrieve}

عرض إصدار "خرائط Google"

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:

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

للاطّلاع على أمثلة كاملة على الاستجابة وتفاصيل حول تفسير حالة التعديل لكل حقل وانتهاكات السياسة، يُرجى الاطّلاع على التحقّق من حالة التعديل للمواقع الجغرافية والسمات.

سرد مواقع

عند إدارة موقع جغرافي واحد أو أكثر، قد تحتاج إلى إدراج جميع المواقع الجغرافية المرتبطة بحسابك. استخدِم واجهة برمجة التطبيقات accounts.locations.list لإدراج جميع المواقع الجغرافية المرتبطة بمستخدم معيّن.

لعرض جميع المواقع الجغرافية التي يملكها أو يديرها مستخدم مصادَق عليه مباشرةً، استخدِم ما يلي:

GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}

استخدِم حرف البدل '-' للحساب في عنوان URL للطلب من أجل تضمين البيانات المملوكة بشكل غير مباشر (المملوكة أو المُدارة من خلال مجموعة):

GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/-/locations?readMask={commaSeparatedFieldsToRetrieve}

فلترة النتائج عند إدراج المواقع الجغرافية

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

البحث حسب المسافة أو الحساب

يوضّح المثال التالي كيفية البحث عن المواقع الجغرافية ضمن مسافة معيّنة من نقطة جغرافية:

GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=distance(latlng, geopoint({latitude}, {longitude}))<{distance}

GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=distance(latlng, geopoint(40.01, -105.27))<1000.0

قائمة بجميع حقول الفلاتر المتوافقة

في ما يلي قائمة شاملة بجميع الحقول التي يمكن استخدامها للفلترة:

الترتيب حسب حقل طلب البحث

يمكنك ترتيب النتائج حسب اسم المؤسسة أو رمز المتجر، بترتيب تصاعدي أو تنازلي. يتم الفصل بين معايير الترتيب المتعددة بفواصل في السلسلة orderBy، كما في المثال التالي:

GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&orderBy=locationName,storeCode

تصحيح موقع جغرافي

استخدِم My Business Business Information API لتعديل حقل واحد أو أكثر لموقع جغرافي باستخدام locations.patch.

لتغيير حقل واحد أو أكثر لموقع جغرافي، استخدِم ما يلي:

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