این صفحه مشخصات فنی فید نقطه مورد نظر (POI) را شرح میدهد. این شامل خلاصهای از فیلدهای مورد نیاز، تعاریف جامع طرحواره و یک نمونه JSON برای راهنمایی در پیادهسازی است.
مشخصات خوراک
این بخش الزامات و تعاریف مربوط به فید POI را شرح میدهد.
الزامات میدانی
| نام فیلد | مورد نیاز | توضیحات |
|---|---|---|
| poi_id | مورد نیاز | رشتهای که توسط شریک ایجاد شده و یک نقطه مورد علاقه (ویژگی) را مشخص میکند. |
| نام | مورد نیاز | نام POI. این نام به عنوان نام نمایشی ملک در واحد تجمیعکننده استفاده خواهد شد. |
| تلفن | خوب است که داشته باشیم | شماره تلفن تماس نقطه مورد نظر شامل کد کشور و منطقه، برای مثال +14567891234 |
| آدرس اینترنتی | خوب است که داشته باشیم | آدرس وبسایت عمومی POI. توجه: این آدرس فقط برای اهداف تطبیق استفاده میشود، نه برای نمایش. |
| مکان | الزامی (آدرس) خوب بود (طولانی/کوتاه) | محل نقطه مورد نظر (POI). الزامی: آدرس و فیلدهای همراه آن برای مطابقت صحیح با ملک الزامی است. خوب است که داشته باشیم: طول و عرض جغرافیایی. در صورت ارائه، گوگل از طول و عرض جغرافیایی در نمایش پینهای ملک در نقشه واحد تجمیعکننده شما استفاده خواهد کرد. |
| تصاویر | الزامی (یک تصویر) خوب است که داشته باشید (چندگانه) | تصاویر از نقاط مورد توجه. تصاویر در نمایش املاک مهم خواهند بود. اکیداً توصیه میکنیم حداقل ۱ تصویر اضافه کنید. میتوانید چندین تصویر تا حداکثر ۵ تصویر ارائه دهید. در صورت ارائه چندین تصویر، آنها به ترتیب ارائه (در صورت غیرقابل استفاده بودن تصویر) استفاده خواهند شد. تصاویر بررسی خواهند شد تا اطمینان حاصل شود که سیاستهای جستجوی امن گوگل را نقض نمیکنند. |
| رتبهبندی | توصیه شده | امتیاز متوسط برای ملک. |
| تعداد رتبهبندیها | توصیه شده | تعداد رتبهبندیهای مشارکتکننده برای فیلد rating . |
| مقیاس_رتبهبندی | خوب است که داشته باشیم | مقیاس رتبهبندی مورد استفاده برای فیلد rating . اگر حداکثر رتبهبندی ۵ باشد، rating_scale برابر با ۵ خواهد بود. |
| دسته | خوب است که داشته باشیم | نشان دهنده دسته بندی ملک است. |
| hotel_data | خوب است که داشته باشیم | فیلدهای مخصوص هتل. برای جزئیات بیشتر به تعریف HotelData مراجعه کنید. |
| هتل_ستاره_کلاس | توصیه شده | مقدار رسمی ستاره درجه هتل. انتظار میرود این مقدار یک عدد صحیح بین ۰ تا ۵ باشد. لطفاً در صورتی که رتبهبندی درجه ستاره در دسترس نیست، ناشناخته است یا مشخص نشده است، مقدار ۰ را وارد کنید. وقتی روی ۰ تنظیم شود، هیچ درجه ستاره هتلی در رابط کاربری برای کاربران نمایش داده نمیشود. |
| شناسههای برند | خوب است که داشته باشیم | برندهایی که میتوانند این هتل را نمایش دهند. اگر این فیلد خالی باشد، هتل میتواند تحت هر یک از برندهای مرتبط با فید نمایش داده شود. |
| توضیحات | خوب است که داشته باشیم | شرح مفصلی از ملک. |
| نمایش_آدرس | خوب است که داشته باشیم | آدرسی که در رابط کاربری نمایش داده میشود. |
دستورالعملهای تصویر
تمام تصاویر اضافه شده به فید باید از این دستورالعملها پیروی کنند:
- فرمت: باید JPEG، PNG یا WebP باشد.
- حداکثر حجم فایل: کمتر از ۳۰ مگابایت برای هر تصویر.
- حداکثر ابعاد: مجموعاً کمتر از ۷۵ مگاپیکسل (عرض × ارتفاع < ۷۵,۰۰۰,۰۰۰).
- نوع URL: مسیر مستقیم به تصویر (مثلاً با پسوند .jpg تمام شود).
- مجوزها: مطمئن شوید که سرور میزبان به رباتهای گوگل یا خزندهها اجازه دسترسی میدهد و هیچ فایل robots.txt دایرکتوریهای تصاویر را مسدود نمیکند.
پشتیبانی چندزبانه
فید Point of Interest از ارائه محتوای بومیسازیشده برای فیلدهای خاص پشتیبانی میکند. فیلدهای زیر از نوع Text هستند و از بومیسازی پشتیبانی میکنند:
-
name -
description -
display_address
برای ارائه محتوا به چندین زبان، باید یک default_locale در فیلد مشخص کنید و رشتههای محلیسازیشده را در لیست localizations ارائه دهید. تمام محلیسازیها را برای یک ویژگی در یک ورودی POI واحد ارائه دهید. یک ویژگی واحد را بین فایلهای JSON چند زبانه تقسیم نکنید.
مثال:
"name": {
"localizations": [
{
"locale": "en",
"text": "Banana Hotel"
},
{
"locale": "es",
"text": "Hotel Plátano"
}
],
"default_locale": "en"
}
دستورالعملهای بستهبندی فایل
برای اطمینان از بلع موفقیتآمیز، الزامات بستهبندی زیر را رعایت کنید:
- بایگانی JSON تجمیعشدهی واحد (الزامی) : تمام رکوردهای ویژگی را در یک فایل JSON واحد ترکیب کنید. توصیه میکنیم آن را در یک بایگانی GZIP واحد فشرده کرده و آپلود کنید.
- هشدار ضد الگو : از یک فایل برای هر ویژگی یا چندین فایل که بر اساس کشور از هم جدا شدهاند در یک آرشیو استفاده نکنید. این رویکرد پشتیبانی نمیشود و باعث خرابی در استخراج میشود.
تعاریف
تعریف VssPoiFeed
// Represents a Point of Interest (POI) data feed provided by a partner. export message VssPoiFeed { // The POIs in the feed. repeated VssPoi data = 1; }
تعریف VssPoi
// Represents a single Point of Interest (POI) entity e.g. a hotel or // restaurant. export message VssPoi { // Required. A string generated by the partner that identifies a POI. string poi_id = 1; // The entity name, telephone, url and location are used to support // matching partner inventory with entities already present on Google. // Required. The name of the POI. Text name = 2; // The contact telephone number of the POI including its country and // area codes, e.g. +14567891234. string telephone = 3 [(datapol.semantic_type) = ST_PHONE_NUMBER]; // The url of the POI's public website. // Note: This will be used just for matching purposes, not for display. string url = 4; // Required. The location of the POI. GeoCoordinates location = 5; // The address displayed on the UI. Text display_address = 17; // Images of the POI. // Max number of images: 5. repeated Image images = 6; // Average rating for the POI. float rating = 12; // The number of contributing ratings for the `rating` field. int64 num_ratings = 13; // The rating scale used for the `rating` field. If max rating is 5, then // rating_scale is 5. int32 rating_scale = 14; // Represents the category of the POI. // It should match the `additional_data` oneof field below. export enum Category { UNKNOWN_CATEGORY = 0; HOTEL = 1; LOCAL = 4; } // Required. Represents the category of the POI. Category category = 9; // A description of the POI. Text description = 16; // Required. Category specific fields. // It should match the `category` field above. oneof additional_data { // Hotel specific fields. HotelData hotel_data = 10; // Local specific fields. LocalData local_data = 15; } }
تعریف متن
// Represents a text with localizations. message Text { // Represents a localized string. message LocalizedString { // The text's language tag, such as "en", "en-US" or "sr-Latn". string locale = 1; // The text in the specified locale. string text = 2; } // The localized strings. repeated LocalizedString localizations = 1; // The locale to use as the default language it must be present in the // localizations. string default_locale = 2; }
تعریف مختصات جغرافیایی
// The Geo data of a location, including latitude, longitude, and address. message GeoCoordinates { option (datapol.msg_semantic_type) = ST_LOCATION; // [-90, +90] degrees (inclusive). // Required if longitude is set, otherwise nice to have. double latitude = 1; // [-180, +180] degrees (inclusive). // Required if latitude is set, otherwise nice to have. double longitude = 2; // Required. Address for a location. oneof addresses { // Postal address of the location. PostalAddress address = 3; } }
تعریف آدرس پستی
// The postal address for the location. message PostalAddress { option (datapol.msg_semantic_type) = ST_LOCATION; // Required. The country, using ISO 3166-1 alpha-2 country code, e.g. "US". string country = 1; // Required. The locality/city, e.g. "Mountain View". string locality = 2; // The region/state/province, e.g. "CA". This field is only required in // countries where region is commonly a part of the address. (optional) string region = 3; // Required. The postal code, e.g. "94043". string postal_code = 4; // Required. The street address, e.g. "1600 Amphitheatre Pkwy". string street_address = 5; }
تعریف تصویر
// Represents an image of the Point of Interest (POI). export message Image { // The url of the image. Google will crawl the media hosted at this URL. // Max length: 2000. string url = 1; // The alternative text to be used for accessibility. Text alt_text = 2; }
تعریف هتل دیتا
// Hotel specific feed data. message HotelData { // The official hotel class star value. // Can be used in a label like "5-star hotel." // This value is expected to be an integer between 0 and 5. A rating of 0 // should be used if a rating is unavailable or not specified. When // set to 0, no star class will be displayed on the UI for users. int32 hotel_star_class = 1; // The brands that can display this hotel. // If this field is empty, the hotel can be displayed under any of the // brands associated with the feed. repeated string brand_ids = 2 [(datapol.semantic_type) = ST_PARTNER_ID]; }
نمونهها
فید نقاط مورد علاقه
نام فایل: poi_1707240000.json
{ "data": [ { "poi_id": "hotel_banana", "name": { "localizations": [ { "locale": "en", "text": "Banana Hotel" } ], "default_locale": "en" }, "telephone": "+16195550100", "url": "https://www.example-banana-hotel.com", "location": { "latitude": 32.7157, "longitude": -117.1611, "address": { "country": "US", "locality": "San Diego", "region": "CA", "postal_code": "92101", "street_address": "2845 W 7th St" } }, "images": [ { "url": "https://www.example.com/banana_hotel.jpg", "alt_text": { "localizations": [ { "locale": "en", "text": "Banana Hotel Exterior" } ] } } ], "rating": 4.5, "category": "HOTEL", "hotel_data": { "hotel_star_class": 4, "brand_ids": ["brand_a", "brand_b"] } }, { "poi_id": "hotel_kiwi", "name": { "localizations": [ { "locale": "en", "text": "Kiwi Hotel" } ], "default_locale": "en" }, "telephone": "+41445550100", "url": "https://www.example-kiwi-hotel.com", "location": { "latitude": 47.3769, "longitude": 8.5417, "address": { "country": "CH", "locality": "Zurich", "postal_code": "8001", "street_address": "Bahnhofstrasse 10" } }, "images": [ { "url": "https://www.example.com/kiwi_hotel.jpg", "alt_text": { "localizations": [ { "locale": "en", "text": "Kiwi Hotel Lobby" } ] } } ], "rating": 4.0, "category": "HOTEL", "hotel_data": { "hotel_star_class": 3, "brand_ids": ["brand_c"] } }, { "poi_id": "hotel_croissant", "name": { "localizations": [ { "locale": "en", "text": "Croissant Hotel" } ], "default_locale": "en" }, "telephone": "+41445550200", "url": "https://www.example-croissant-hotel.com", "location": { "latitude": 47.3686, "longitude": 8.5392, "address": { "country": "CH", "locality": "Zurich", "postal_code": "8002", "street_address": "Paradeplatz 1" } }, "images": [ { "url": "https://www.example.com/croissant_hotel.jpg", "alt_text": { "localizations": [ { "locale": "en", "text": "Croissant Hotel View" } ] } } ], "rating": 5.0, "category": "HOTEL", "hotel_data": { "hotel_star_class": 5 } }, { "poi_id": "hotel_tiburon", "name": { "localizations": [ { "locale": "en", "text": "Hotel Tiburon" } ], "default_locale": "en" }, "telephone": "+15105550100", "url": "https://www.example-tiburon-hotel.com", "location": { "latitude": 37.7652, "longitude": -122.2416, "address": { "country": "US", "locality": "Alameda", "region": "CA", "postal_code": "94501", "street_address": "1100 Atlantic Ave" } }, "images": [ { "url": "https://www.example.com/tiburon_hotel.jpg", "alt_text": { "localizations": [ { "locale": "en", "text": "Hotel Tiburon Pool" } ] } } ], "rating": 4.2, "category": "HOTEL", "hotel_data": { "hotel_star_class": 5, "brand_ids": ["brand_a"] } } ] }
فید POI چند زبانه
نام فایل: poi_multilingual.json
{ "data": [ { "poi_id": "hotel_banana_multilingual", "name": { "localizations": [ { "locale": "en", "text": "Banana Hotel" }, { "locale": "es", "text": "Hotel Plátano" }, { "locale": "fr", "text": "Hôtel Banane" } ], "default_locale": "en" }, "description": { "localizations": [ { "locale": "en", "text": "A beautiful hotel shaped like a banana." }, { "locale": "es", "text": "Un hermoso hotel con forma de plátano." }, { "locale": "fr", "text": "Un bel hôtel en forme de banane." } ], "default_locale": "en" }, "display_address": { "localizations": [ { "locale": "en", "text": "123 Banana Way, Fruit City, CA 90000" }, { "locale": "es", "text": "123 Vía Plátano, Ciudad Fruta, CA 90000" } ], "default_locale": "en" }, "telephone": "+16195550100", "url": "https://www.example-banana-hotel.com", "location": { "latitude": 32.7157, "longitude": -117.1611, "address": { "country": "US", "locality": "Fruit City", "region": "CA", "postal_code": "90000", "street_address": "123 Banana Way" } }, "images": [ { "url": "https://www.example.com/banana_hotel.jpg", "alt_text": { "localizations": [ { "locale": "en", "text": "Banana Hotel Exterior" }, { "locale": "es", "text": "Exterior del Hotel Plátano" } ] } } ], "rating": 4.5, "category": "HOTEL", "hotel_data": { "hotel_star_class": 4, "brand_ids": ["brand_mango", "brand_apricot"] } } ] }