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

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

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

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

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

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

قبل البدء

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

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

يمكنك استخدام My 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 Information API لحذف موقع جغرافي يضم 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، Drive الخاص".

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

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

مثال

يوضح المثال التالي تعبير فلتر يعرض جميع المواقع التي تحتوي على باسم "بيبي لو بيو". إنه يعرض فئات إما "المطعم_الفرنسي" أو "المطعم الأوروبي" وتصنيف "مفتوح حديثًا".

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 Information API لتعديل حقل واحد أو أكثر لأحد المواقع الجغرافية باستخدام locations.patch.

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

بروتوكول HTTP

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

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