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

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

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

قبل البدء

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

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

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

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

يمكنك استخدام واجهة برمجة التطبيقات Business Information API في "نشاطي التجاري على Google" لحذف موقع جغرافي باستخدام locations.delete.

لحذف موقع جغرافي، اتّبِع الخطوات التالية:

بروتوكول HTTP
DELETE
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}

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

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

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

بروتوكول 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 شارع" مع "4، شارع السعادة".

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

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

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

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

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

بروتوكول HTTP

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

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