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

يشرح هذا الدليل التوجيهي كيفية إنشاء بيانات الموقع الجغرافي وتعديلها. تتيح لك واجهة برمجة تطبيقات معلومات نشاطي التجاري إمكانية تنفيذ ما يلي:

يمكن استخدام المواقع الجغرافية في "إعلانات Google"، ولكن يجب إثبات ملكيتها لتكون مؤهّلة للظهور في "بحث Google" و"خرائط Google". يتم تمثيل بيانات الموقع الجغرافي من خلال مجموعة accounts.locations.

قبل البدء

قبل استخدام واجهة برمجة التطبيقات My Business Information API، عليك تسجيل تطبيقك والحصول على بيانات اعتماد OAuth 2.0. للحصول على تفاصيل حول كيفية البدء باستخدام واجهة برمجة تطبيقات معلومات نشاطي التجاري، راجع الإعداد الأساسي.

إنشاء موقع جغرافي

يمكنك استخدام واجهة برمجة تطبيقات معلومات نشاطي التجاري على 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"
      }
     }
}

حذف موقع جغرافي

يمكنك استخدام واجهة برمجة تطبيقات معلومات نشاطي التجاري على Google لحذف موقع جغرافي باستخدام 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 لإدراج جميع المواقع الجغرافية المرتبطة بالمستخدم.

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

بروتوكول 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".

دمج حقول متعددة في طلب بحث فلتر

تسمح واجهة برمجة التطبيقات "و" بربط جميع قيود الحقول. ومع ذلك، عندما يتعلق الأمر بالكلمة الرئيسية OR، يجب أن تنطبق جميع القيود على نفس الحقل. على سبيل المثال: لا يُسمح باستخدام locationName=A أو labels=B.

مثال

يوضح المثال التالي تعبير فلتر يعرض جميع المواقع التي تحمل الاسم "Pepé Le Pew". حيث يعرض فئات إما "مطعم_مطعم فرنسي" أو "مطعم_أوروبي"، وتصنيف "مفتوح حديثًا".

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"، سيكون هذا الحقل مساويًا لمعرّف المكان للموقع الجغرافي.

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

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

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

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

بروتوكول HTTP

أضِف الحقول والقيم المعدّلة مع حقل الموقع، واستخدِم قائمة مفصولة بفواصل من الحقول المعدَّلة كقيمة للحقل fieldMask.

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