يوضّح هذا الدليل التعليمي كيفية إنشاء بيانات الموقع الجغرافي وتعديلها. تتيح لك 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.
لإنشاء موقع جغرافي، استخدِم ما يلي:
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.
لحذف موقع جغرافي، اتّبِع الخطوات التالية:
DELETE https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}
الحصول على موقع جغرافي حسب الاسم
إذا كان لديك العديد من الأنشطة التجارية المرتبطة بحسابك، ننصحك بتحديد موقع جغرافي واحد. يمكنك الفلترة حسب اسم النشاط التجاري للحصول على موقع جغرافي معيّن باستخدام locations.get.
للحصول على موقع جغرافي حسب الاسم، استخدِم ما يلي: يجب تحديد قناع قراءة لاسترداد حقول معيّنة. :
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 شارع" مع "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
البحث حسب المسافة أو الحساب
يوضّح المثال التالي كيفية البحث عن مواقع جغرافية ضمن مسافة معيّنة من نقطة جغرافية:
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 |
اسم النشاط التجاري في الواقع
|
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
تصحيح موقع جغرافي
استخدِم واجهة برمجة التطبيقات Business Information API في "نشاطي التجاري على Google" لتعديل حقل واحد أو أكثر لموقع جغرافي باستخدام locations.patch.
لتغيير حقل واحد أو أكثر لموقع جغرافي، استخدِم ما يلي:
أضِف الحقول والقيم المعدّلة مع حقل الموقع الجغرافي، واستخدِم
قائمة مفصولة بفواصل للحقول المعدّلة كقيمة لسمة fieldMask
.
PATCH https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?languageCode=language&validateOnly=True|False&updateMask=title { "title": "Google Shoes" }