تتضمّن واجهة برمجة التطبيقات لأداء الأعمال في Google طريقة واجهة برمجة تطبيقات جديدة تتيح جلب عدة "مقاييس يومية" في طلب واحد لواجهة برمجة التطبيقات.
يُرجى مراجعة الجدول الزمني للإيقاف وتعليمات نقل البيانات من طريقة v4 reportInsights API إلى واجهة برمجة التطبيقات الخاصة بأداء "الملف التجاري على Google".

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

يوضّح هذا الدليل التعليمي كيفية إنشاء بيانات الموقع الجغرافي وتعديلها. تتيح لك 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"
}