يشرح هذا الدليل التوجيهي كيفية إنشاء بيانات الموقع الجغرافي وتعديلها. تتيح لك واجهة برمجة تطبيقات معلومات نشاطي التجاري إمكانية تنفيذ ما يلي:
- أنشئ موقعًا جغرافيًا جديدًا.
- حذف موقع جغرافي
- الحصول على موقع حسب اسم المورد
- أدرِج جميع المواقع الجغرافية لحساب معيّن.
- عدِّل حقلاً واحدًا أو أكثر لموقع جغرافي.
يمكن استخدام المواقع الجغرافية في "إعلانات Google"، ولكن يجب إثبات ملكيتها لتكون مؤهّلة للظهور في "بحث Google" و"خرائط Google". يتم تمثيل بيانات الموقع الجغرافي من خلال مجموعة accounts.locations.
قبل البدء
قبل استخدام واجهة برمجة التطبيقات My Business Information API، عليك تسجيل تطبيقك والحصول على بيانات اعتماد OAuth 2.0. للحصول على تفاصيل حول كيفية البدء باستخدام واجهة برمجة تطبيقات معلومات نشاطي التجاري، راجع الإعداد الأساسي.
إنشاء موقع جغرافي
يمكنك استخدام واجهة برمجة تطبيقات معلومات نشاطي التجاري على Google لإنشاء موقع جغرافي جديد للنشاط التجاري باستخدام 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" } } }
حذف موقع جغرافي
يمكنك استخدام واجهة برمجة تطبيقات معلومات نشاطي التجاري على Google لحذف موقع جغرافي باستخدام locations.delete.
لحذف موقع جغرافي، يُرجى استخدام ما يلي:
DELETE https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}
الحصول على موقع جغرافي حسب الاسم
إذا كانت لديك أنشطة تجارية عديدة مرتبطة بحسابك، قد تريد الحصول على موقع جغرافي واحد. يمكنك الفلترة حسب اسم النشاط التجاري للحصول على موقع جغرافي معيّن باستخدام locations.get.
للحصول على موقع حسب الاسم، استخدِم ما يلي. يجب تحديد readMask لاسترداد حقول محددة. :
GET https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?readMask={commaSeparatedFieldsToRetrieve}
إرجاع إصدار خرائط Google
لعرض إصدار "خرائط Google" لموقع جغرافي، ألحِق googleUpdated
بعنوان URL للطلب، كما في المثال التالي:
GET https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}:googleUpdated?readMask={commaSeparatedFieldsToRetrieve}
إذا لم تكن هناك نتائج، سيتم عرض رمز حالة HTTP 404 NOT FOUND
. يمكنك الاطّلاع هنا على مزيد من التفاصيل حول إدارة التعديلات من Google.
سرد مواقع
عندما تدير موقعًا واحدًا أو أكثر، يمكنك إدراج جميع المواقع الجغرافية المرتبطة بحسابك. استخدِم واجهة برمجة التطبيقات 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}
فلترة النتائج عند إدراج مواقع جغرافية
يمكنك استخدام الفلاتر للحدّ من النتائج التي تظهر عند طلب 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
البحث حسب المسافة أو الحساب
يوضح المثال التالي كيف يمكنك البحث عن مواقع ضمن مسافة معينة من نقطة جغرافية:
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 |
الاسم الحقيقي للنشاط التجاري
|
categories |
الجمع بين الفئة الأساسية والفئات الإضافية. ويجب حذف "gcid:". وإذا كانت هناك عدة فئات، سيتطابق هذا الفلتر إذا كانت هناك فئة واحدة على الأقل تتطابق مع هذا النمط.
|
phone_numbers.primary_phone |
رقم الهاتف الأساسي بالتنسيق E.164 (على سبيل المثال: " +441234567890").
|
storefront_address.region_code |
رمز CLDR للمنطقة التي تضم بلد/منطقة العنوان
|
storefront_address.administrative_area |
أعلى تقسيم فرعي إداري يُستخدم للعناوين البريدية لبلد أو منطقة
|
storefront_address.locality |
جزء المدينة/البلدة من العنوان
|
storefront_address.postal_code |
الرمز البريدي للعنوان
|
metadata.place_id |
إذا تم إثبات ملكية هذا الموقع الجغرافي ويرتبط بـ/يظهر على "خرائط Google"، سيكون هذا الحقل مساويًا لمعرّف المكان للموقع الجغرافي.
|
openInfo.status |
يشير إلى ما إذا كان الموقع الجغرافي مفتوحًا حاليًا للنشاط التجاري أم لا
(
|
labels |
مجموعة من السلاسل الحرة التي تسمح لك بالإشارة إلى نشاطك التجاري. وعلى عكس جميع الحقول الأخرى، يجب أن تتطابق هذه القيمة تمامًا مع تصنيف كامل، بما في ذلك حالة الأحرف وليس فقط الرمز المميز. على سبيل المثال، إذا كانت قيمة التصنيف "XX YY"، لن يتطابق أيٌ من "XX" أو "xx yy".
|
storeCode |
المعرّف الخارجي لهذا الموقع الجغرافي، والذي يجب أن يكون فريدًا داخل حساب معيّن
|
الدوالّ | |
distance |
يسمح لك هذا الخيار بإجراء فلترة استنادًا إلى مسافة الموقع الجغرافي من نقطة جغرافية.
|
الترتيب حسب حقل طلب البحث
يمكنك فرز النتائج حسب اسم النشاط التجاري أو رمز المتجر، بترتيب تصاعدي أو تنازلي. يتم الفصل بين معايير الطلب المتعددة بفواصل في سلسلة orderBy
، كما في المثال التالي:
GET https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&orderBy=locationName,storeCode
تصحيح موقع جغرافي
استخدِم واجهة برمجة تطبيقات معلومات نشاطي التجاري على Google لتعديل حقل واحد أو أكثر لموقع جغرافي معيّن باستخدام locations.patch.
لتغيير حقل واحد أو أكثر لموقع جغرافي، استخدِم ما يلي:
أضِف الحقول والقيم المعدّلة مع حقل الموقع، واستخدِم قائمة مفصولة بفواصل من الحقول المعدَّلة كقيمة للحقل fieldMask
.
PATCH https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?languageCode=language&validateOnly=True|False&updateMask=title { "title": "Google Shoes" }