A
Destination
تشير إلى موقع أو مكان محدّدَين يعتزم المستخدم الوصول إليهما أو التنقّل
نحوهما. يتضمن Destination أيضًا مجموعة من المعلومات المتعلقة بالموقع أو المكان، مثل نقاط التنقل والمعالم والمداخل والمخططات التفصيلية للمبنى.
تتيح لك طريقة
SearchDestinations
في Geocoding API استرداد معلومات مفصّلة عن وجهات مختلفة استنادًا إلى معايير إدخال مختلفة، مثل عنوان أو رقم تعريف مكان أو
إحداثيات خط العرض وخط الطول.
طلب البحث عن الوجهات
طلب البحث عن الوجهات طلب هو طلب HTTP POST إلى عنوان URL بالتنسيق التالي:
https://geocode.googleapis.com/v4/geocode/destinations
مرِّر جميع المَعلمات في نص طلب JSON أو في العناوين كجزء من طلب POST. على سبيل المثال:
curl -X POST -d '{
"place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4/geocode/destinations
يمكنك تحديد الموقع الجغرافي للبحث عن وجهة بإحدى الطرق الثلاث التالية:
- العنوان
- رقم تعريف المكان
- إحداثيات خطوط العرض وخطوط الطول
البحث عن وجهة حسب العنوان
يمكنك تحديد العنوان كسلسلة غير منظَّمة. لا يحلّ الترميز الجغرافي للعنوان إحداثيات خط العرض وخط الطول أو السلاسل غير المنظَّمة الأخرى التي لا تمثّل عنوانًا. لا تتوافق الطلبات التي تستخدم مثل هذه السلاسل وقد تؤدي إلى ردود تتضمّن أخطاء أو سلوك غير محدّد. في ما يلي أمثلة على طلبات البحث غير المتوافقة:
| نوع طلب البحث | مثال |
|---|---|
| إحداثيات خطوط العرض وخطوط الطول. استخدِم طلب بحث عن موقع جغرافي بدلاً من ذلك. | "37.422131,-122.084801" |
| الكثير من المفاهيم أو القيود، مثل أسماء أماكن أو طرق أو مدن متعددة في طلب بحث واحد | "شارع ماركت سان فرانسيسكو مطار سان خوسيه" |
| عناصر العنوان البريدي غير الممثَّلة على "خرائط Google" |
"عناية جون سميث 123 شارع رئيسي" "صندوق بريد 13 سان فرانسيسكو" |
| أسماء المؤسسات أو السلاسل أو الفئات المدمَجة مع المواقع الجغرافية التي لا تتوفّر فيها هذه الكيانات | "تيسكو بالقرب من دالاس، تكساس" |
| طلبات بحث غامضة تتضمّن تفسيرات متعددة | "تسليم الشاحن" |
| الأسماء التاريخية التي لم تعُد مستخدَمة | "ميدلسكس المملكة المتحدة" |
| العناصر أو الغرض غير الجغرافيين | "كم عدد القوارب في ميناء فينتورا؟" |
| الأسماء غير الرسمية أو الأسماء التي تهدف إلى جذب الانتباه |
"ذا جينغا" "ذا هيلتر سكيلتر" |
| الكيانات السياسية الكبيرة (المدن والولايات والبلدان) |
"مدينة نيويورك" "كاليفورنيا" "الولايات المتحدة الأمريكية" |
| الطرق بدون عناوين محدّدة |
"الجادة الأولى، نيويورك، نيويورك" "I-95" |
curl -X POST -d '{
"addressQuery": {
"addressQuery": "601 S Bernardo Ave, Sunnyvale, CA 94087, USA"
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4/geocode/destinations
أو بتنسيق
postalAddress:
curl -X POST -d '{
"addressQuery": {
"address": {
"addressLines": ["601 S Bernardo Ave"],
"locality": "Sunnyvale",
"postalCode": "94087",
"administrativeArea": "CA",
"regionCode": "US"
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4/geocode/destinations
عادةً ما تستخدم تنسيق postalAddress عند معالجة مكوّنات العنوان التي يتم التقاطها في نموذج HTML.
البحث عن وجهة حسب معرّف المكان
يمكنك استرداد وجهة من خلال تقديم معرّف مكان:
curl -X POST -d '{
"place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4/geocode/destinations
معرّفات الأماكن المتوافقة
تعمل طريقة "البحث عن الوجهات" على أفضل نحو مع معرّفات الأماكن التي تمثّل وجهات محدّدة وقابلة للتنقّل. تكون معرّفات الأماكن لأنواع مثل establishment,
point_of_interest, premise, street_address, و subpremise متوافقة بشكل عام. لا تتوافق معرّفات الأماكن التي لا تمثّل مواقع جغرافية منفصلة، مثل تلك المستنتَجة من نطاقات العناوين (على سبيل المثال، "10-20 شارع رئيسي") أو أقسام من طريق بدون رقم محدّد أو رموز المواقع المفتوحة. لا تتوافق أيضًا معرّفات الأماكن للنتائج التي تكون كبيرة جدًا من حيث المساحة (على سبيل المثال، "المحيط الهادئ").
استخدام ميزة "الإكمال التلقائي" في Places API (الجديدة) مع طريقة "البحث عن الوجهات"
لضمان التوافق، استخدِم ميزة "الإكمال التلقائي" في Places API
(الجديدة) للعثور على معرّفات الأماكن
لاستخدامها مع طريقة "البحث عن الوجهات". عند استخدام ميزة "الإكمال التلقائي"، عليك فلترة
النتائج حسب النوع باستخدام
includedPrimaryTypes
المَعلمة. تتوافق طريقة "البحث عن الوجهات" مع معرّفات الأماكن التي تعرضها ميزة "الإكمال التلقائي" باستخدام الفلتر المقترَح التالي:
"includedPrimaryTypes": [ "establishment", "point_of_interest", "premise", "street_address", "subpremise" ]
بالإضافة إلى ذلك، يجب عدم ضبط العلامة include_pure_service_area_businesses
على true في طلب "الإكمال التلقائي".
البحث عن وجهة حسب الموقع الجغرافي
يمكنك البحث عن وجهة من خلال تقديم إحداثيات خط العرض وخط الطول:
curl -X POST -d '{
"locationQuery": {
"location": {
"latitude": 37.37348780,
"longitude": -122.05678064
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4/geocode/destinations
استخدام بروتوكول OAuth لتقديم طلب
يتوافق Geocoding API v4 مع بروتوكول OAuth 2.0 للمصادقة. لاستخدام بروتوكول OAuth مع Geocoding API، يجب منح رمز OAuth النطاق الصحيح. يتوافق Geocoding API مع النطاقات التالية لاستخدامها مع طريقة "الوجهات":
https://www.googleapis.com/auth/maps-platform.geocode: استخدِم هذا النطاق مع جميع طرق Geocoding API.
يمكنك أيضًا استخدام النطاق العام https://www.googleapis.com/auth/cloud-platform لجميع طرق Geocoding API. يكون هذا النطاق مفيدًا أثناء التطوير، ولكن ليس في مرحلة الإنتاج، لأنّه نطاق عام يتيح الوصول إلى جميع الطرق.
لمزيد من المعلومات والأمثلة، يُرجى الاطّلاع على مقالة استخدام بروتوكول OAuth.
الردّ على طلب البحث عن الوجهات
يقدّم الردّ على طلب البحث عن الوجهات سياقًا غنيًا وعلى مستوى منطقة محلية صغيرة حول الموقع الجغرافي.
تستخدم عناصر PlaceView ضِمن الردّ على طلب البحث عن الوجهات (مثل primary والعناصر في containingPlaces وlandmarks) حقولًا للإشارة إلى نوع المكان:
types: مصفوفة من السلاسل تشير إلى أنواع المكان.primaryType: سلسلة تشير إلى النوع الأساسي للمكان.
يتم استخلاص قيم السلاسل المحتمَلة لكل من types وprimaryType من الجدولَين "أ" و"ب" في صفحة أنواع الأماكن (الجديدة).
يصف هذا القسم حقول الردّ الرئيسية. للاطّلاع على التفاصيل الكاملة عن جميع حقول الردّ، يُرجى الرجوع إلى مرجع واجهة برمجة التطبيقات.
primary
المكان الرئيسي الذي تم تحديده من خلال طلب البحث في الطلب.
containingPlaces
الكيانات الأكبر التي تشكّل الوجهة الرئيسية جزءًا منها (على سبيل المثال، مركز تسوّق يحتوي على متجر)
subDestinations
المواقع الجغرافية الأكثر تحديدًا ضِمن الوجهة الرئيسية (على سبيل المثال، الشقق في مبنى)
entrances
تحتوي العناصر في مصفوفة entrances[] على الحقول التالية:
locationزوج إحداثيات خط العرض وخط الطول يحدّد موقع نقطة الدخول والخروج إلى مكان
entrance_tags[]مصفوفة من علامات مدخل تصف خصائص المدخل القيمة التالية متوافقة:
"PREFERRED"
تشير هذه العلامة إلى أنّ هذا المدخل من المحتمل أن يوفّر وصولًا فعليًا إلى المكان الذي تم عرضه. يمكن أن يكون للمكان مداخل مفضّلة متعددة. إذا لم يكن للمدخل هذه العلامة، يعني ذلك أنّ المدخل يقع فعليًا في المبنى نفسه ولكنّه لا يوفّر بالضرورة وصولًا إلى المكان.
على سبيل المثال، إذا كان المكان الذي تم عرضه هو مطعم في مركز تجاري، ستكون المداخل التي تحمل العلامة
"PREFERRED"هي المداخل التي تؤدي إلى المطعم نفسه، بينما ستكون المداخل الأخرى التي تم عرضها هي مداخل أخرى للمبنى، مثل المداخل إلى المطاعم الأخرى في المركز التجاري.إذا كان المكان الذي تم عرضه هو مبنى نفسه، ستكون المداخل التي تحمل العلامة
"PREFERRED"هي المداخل التي تؤدي إلى الجزء "الرئيسي" من المبنى. على سبيل المثال، في مركز تسوّق، ستكون المداخل التي تحمل العلامة"PREFERRED"هي المداخل التي تتيح الوصول إلى منطقة البهو الرئيسية، ولكن إذا كان المدخل يوفّر الوصول إلى متجر على جانب المبنى فقط، لن يكون مدخلاً"PREFERRED"streetViewThumbnailوstreetViewAnnotationمَعلمات Street View Static API، ما يتيح لك عرض صور ذات صلة بهذه المواقع الجغرافية مزيد من المعلومات حول هذه الحقول.
structureType
نوع الهيكل الذي يمثّله هذا المكان
POINTموقع جغرافي نقطي
SECTIONقسم فرعي من مبنى
BUILDINGمبنى
GROUNDSمنطقة كبيرة تحتوي عادةً على مبانٍ متعددة، مثل حرم جامعي أو مجمّع سكني أو مركز تسوّق
navigationPoints
يحتوي الحقل navigationPoints ضِمن ردّ Geocoding على قائمة بالنقاط المفيدة للتنقّل إلى المكان. على وجه التحديد، يجب استخدامها كنقاط بداية أو نهاية عند توجيه المسار على شبكة طرق من المكان أو إليه.
تحتوي كل نقطة تنقّل على القيم التالية:
navigationPointTokenهو رمز مميّز يحتوي على المعلومات السياقية في الحقلnavigationPoints. يمكنك إرسال هذا الرمز المميّز إلى واجهات برمجة التطبيقات للتوجيه و التنقّل لتحسين التوجيه وتجربة النهر في تطبيقك. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة توجيه المسار باستخدام الرموز المميّزة لنقاط التنقّل.locationيحتوي على قيمة خط العرض وخط الطول لنقطة التنقّل. سيكون هذا الموقع الجغرافي دائمًا قريبًا جدًا من شبكة الطرق ويمثّل نقطة توقف أو نقطة البداية المثالية للتنقّل من مكان وإليه. يتم إزاحة النقطة قليلاً عن خط المنتصف للطريق بشكل متعمّد لوضع علامة واضحة على جانب الطريق الذي يقع فيه المكان.travelModesهي قائمة بوسائل النقل التي يمكن الوصول إليها من نقطة التنقّل:"DRIVE"هو وضع السفر الذي يتوافق مع اتجاهات القيادة."WALK"هي وسيلة النقل التي تتوافق مع اتجاهات المشي.
usagesهي قائمة بالاستخدامات التي تتيحها نقطة التنقّل. يمكن أن تكون الاستخدامات:"DROPOFF""PICKUP""PARKING"
بالنسبة إلى عمليات الاستلام والتسليم، استخدِم نقطة التنقّل التي تكون فيها وسيلة النقل DRIVE والاستخدام PICKUP أو DROPOFF. إذا لم تتوفّر نقاط الاستلام أو التسليم، استخدِم نقطة التنقّل الرئيسية للقيادة.
streetViewThumbnailوentranceAnnotationتوفّر مَعلمات لـ Street View Static API، ما يتيح لك عرض صور ذات صلة بهذه المواقع الجغرافية. مزيد من المعلومات حول هذه الحقول.
arrivalSummary
معلومات مفيدة مستندة إلى الذكاء الاصطناعي للمساعدة في الوصول الاطّلاع على الملخّصات المستندة إلى الذكاء الاصطناعي
landmarks
أماكن قريبة بارزة لمساعدة المستخدمين في فهم محيط الوجهة
parkingOptions
معلومات مفصّلة عن مواقف السيارات
تنسيق الردّ
تعرض طريقة SearchDestinations
SearchDestinationsResponse
بالتنسيق JSON التالي:
{ "destinations": [ { "primary": { "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w", "displayName": { "text": "Arby's", "languageCode": "en" }, "primaryType": "fast_food_restaurant", "types": [ "fast_food_restaurant", "sandwich_shop", "deli", "meal_takeaway", "food_delivery", "american_restaurant", "restaurant", "food_store", "store", "food", "point_of_interest", "establishment" ], "formattedAddress": "Arby's, 601 S Bernardo Ave, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "601 S Bernardo Ave" ] }, "structureType": "BUILDING", "location": { "latitude": 37.3734545, "longitude": -122.05693269999998 }, "displayPolygon": { "type": "Polygon", "coordinates": [ [ [ -122.056930138027, 37.3735253692531 ], [ -122.056960139391, 37.3735372663597 ], [ -122.056994129366, 37.3734828786847 ], [ -122.056969677395, 37.3734731161089 ], [ -122.057061762447, 37.3733261309656 ], [ -122.056979388817, 37.3732935577128 ], [ -122.056798860285, 37.3735818838642 ], [ -122.056875858081, 37.3736121235316 ], [ -122.056930138027, 37.3735253692531 ] ] ] } }, "containingPlaces": [ { "place": "places/ChIJYfdAFum2j4ARIcL2tjME3Sw", "displayName": { "text": "Cherry Chase Shopping Center", "languageCode": "en" }, "primaryType": "shopping_mall", "types": [ "shopping_mall", "point_of_interest", "establishment" ], "formattedAddress": "Cherry Chase Shopping Center, 663 S Bernardo Ave, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087-1020", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "663 S Bernardo Ave" ] }, "structureType": "GROUNDS", "location": { "latitude": 37.3731231, "longitude": -122.0578211 }, "displayPolygon": { "type": "Polygon", "coordinates": [ [ [ -122.057112227103, 37.3714618008523 ], [ -122.057076849821, 37.3715743611411 ], [ -122.056963607756, 37.3719081793948 ], [ -122.056865279559, 37.3722026053835 ], [ -122.056687872374, 37.3727258358476 ], [ -122.056580005889, 37.3730511370747 ], [ -122.056498845827, 37.3732994782583 ], [ -122.056338259713, 37.3737878663325 ], [ -122.056618678291, 37.373887693582 ], [ -122.056912102521, 37.3740010327191 ], [ -122.057532418159, 37.3742476426462 ], [ -122.057673926626, 37.3742441740031 ], [ -122.057735663106, 37.3742328516943 ], [ -122.057766531332, 37.3742220604378 ], [ -122.057797572967, 37.37420520725 ], [ -122.057828267759, 37.3741852342085 ], [ -122.058060299297, 37.3740060842535 ], [ -122.058199726081, 37.3737861673422 ], [ -122.05836707267, 37.373524542556 ], [ -122.058569622393, 37.3732018598683 ], [ -122.0587638478, 37.3728890198039 ], [ -122.058934661823, 37.3726036257774 ], [ -122.059164956851, 37.3722498383629 ], [ -122.058997784906, 37.3721804442035 ], [ -122.057936479838, 37.3717605636234 ], [ -122.057495827092, 37.3715860151634 ], [ -122.057112227103, 37.3714618008523 ] ] ] } } ], "landmarks": [ { "place": { "place": "places/ChIJXXTe7Oi2j4ARoMTA-D6Hjpg", "displayName": { "text": "Chase Bank", "languageCode": "en" }, "primaryType": "bank", "types": [ "bank", "atm", "finance", "point_of_interest", "establishment" ], "formattedAddress": "Chase Bank, 1234 W El Camino Real, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "1234 W El Camino Real" ] }, "structureType": "POINT", "location": { "latitude": 37.373579, "longitude": -122.05752700000001 } }, "relationalDescription": { "text": "Near Chase Bank", "languageCode": "en" }, "tags": [ "ARRIVAL", "ADDRESS" ], "straightLineDistanceMeters": 61.182193756103516, "travelDistanceMeters": 63.075645446777344 }, { "place": { "place": "places/ChIJteQ0Fum2j4ARGi3tqK4Zm14", "displayName": { "text": "Safeway", "languageCode": "en" }, "primaryType": "grocery_store", "types": [ "grocery_store", "butcher_shop", "florist", "deli", "supermarket", "bakery", "food_delivery", "market", "manufacturer", "food_store", "store", "food", "service", "point_of_interest", "establishment" ], "formattedAddress": "Safeway, 639 S Bernardo Ave, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "639 S Bernardo Ave" ] }, "structureType": "POINT", "location": { "latitude": 37.3727912, "longitude": -122.0581172 } }, "relationalDescription": { "text": "Around the corner from Safeway", "languageCode": "en" }, "tags": [ "ARRIVAL", "ADDRESS" ], "straightLineDistanceMeters": 158.65606689453125, "travelDistanceMeters": 131.1669921875 }, { "place": { "place": "places/ChIJu-PSYui2j4ARNiwOwBApGqk", "displayName": { "text": "Oil Changers", "languageCode": "en" }, "types": [ "car_repair", "service", "point_of_interest", "establishment" ], "formattedAddress": "Oil Changers, 1240 W El Camino Real, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "1240 W El Camino Real" ] }, "structureType": "POINT", "location": { "latitude": 37.3743054, "longitude": -122.0584272 } }, "relationalDescription": { "text": "Down the road from Oil Changers", "languageCode": "en" }, "tags": [ "ARRIVAL" ], "straightLineDistanceMeters": 140.52459716796875, "travelDistanceMeters": 143.24220275878906 }, { "place": { "place": "places/ChIJKRbl5oG3j4ARwuvPGUmtCj0", "displayName": { "text": "Apni Mandi Farmers Market Sunnyvale", "languageCode": "en" }, "primaryType": "grocery_store", "types": [ "grocery_store", "cake_shop", "supermarket", "asian_grocery_store", "indian_restaurant", "meal_takeaway", "bakery", "manufacturer", "wholesaler", "restaurant", "food_store", "store", "food", "point_of_interest", "establishment" ], "formattedAddress": "Apni Mandi Farmers Market Sunnyvale, 1111 W El Camino Real, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087-1056", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "1111 W El Camino Real" ] }, "structureType": "POINT", "location": { "latitude": 37.3737199, "longitude": -122.0522958 } }, "relationalDescription": { "text": "Near Apni Mandi Farmers Market Sunnyvale", "languageCode": "en" }, "tags": [ "ADDRESS" ], "straightLineDistanceMeters": 410.37435913085938, "travelDistanceMeters": 479.49893188476562 }, { "place": { "place": "places/ChIJ8enMlui2j4AR2xXK5EHDhBs", "displayName": { "text": "Starbird Chicken", "languageCode": "en" }, "primaryType": "chicken_restaurant", "types": [ "chicken_restaurant", "fast_food_restaurant", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "Starbird Chicken, 1241 W El Camino Real, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087-1028", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "1241 W El Camino Real" ] }, "structureType": "BUILDING", "location": { "latitude": 37.3746764, "longitude": -122.05708860000001 }, "displayPolygon": { "coordinates": [ [ [ -122.057003840785, 37.3747648209809 ], [ -122.057136852459, 37.3747919153144 ], [ -122.057205005705, 37.3745815131859 ], [ -122.057071994114, 37.3745544186944 ], [ -122.057003840785, 37.3747648209809 ] ] ], "type": "Polygon" } }, "relationalDescription": { "text": "Near Starbird Chicken", "languageCode": "en" }, "tags": [ "ADDRESS" ], "straightLineDistanceMeters": 87.348007202148438, "travelDistanceMeters": 214.08084106445312 } ], "entrances": [ { "location": { "latitude": 37.3735328, "longitude": -122.05694879999999 }, "tags": [ "PREFERRED" ], "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w" } ], "navigationPoints": [ { "navigationPointToken": "ChIJeMt61tqvQkARWT2716SDXsASEgljyy_n6LaPgBH9LoGUMNHjbBoSCWPLL-foto-AEf0ugZQw0eNsIhIJhf5y6ei2j4ARz7yBW5KAPI4", "location": { "latitude": 37.3738659, "longitude": -122.05693620000001 }, "travelModes": [ "DRIVE", "WALK" ], "usages": [ "PARKING" ] } ] } ] }
المعلمات المطلوبة
- يجب أن يتضمّن طلب بيانات من واجهة برمجة التطبيقات إحدى المَعلمات الثلاث التالية التي تحدّد العنوان أو المكان أو الموقع الجغرافي للبحث عن وجهة:
addressQuery: العنوان الذي تريد البحث عنهplace: معرّف المكان الذي تريد البحث عنهlocationQuery: إحداثيات خط العرض وخط الطول لـ الموقع الجغرافي الذي تريد البحث عنه
FieldMask
حدِّد قائمة الحقول التي تريد عرضها في الردّ من خلال إنشاء قناع حقول الردّ. مرِّر قناع حقول الردّ إلى الطريقة باستخدام مَعلمة عنوان URL
$fieldsأوfields، أو باستخدام عنوان HTTPX-Goog-FieldMask. على سبيل المثال، لن يعرض الطلب أدناه سوى المداخل ونقاط التنقّل ومعرّف المكان للوجهة الرئيسية.curl -X POST -d '{"place": "places/ChIJG3kh4hq6j4AR_XuFQnV0_t8"}' \ -H "X-Goog-Api-Key: API_KEY" \ -H "Content-Type: application/json" \ -H "X-Goog-FieldMask: destinations.entrances,destinations.navigationPoints,destinations.primary.place" \ https://geocode.googleapis.com/v4/geocode/destinationsلا توجد قائمة تلقائية بالحقول التي يتم عرضها في الردّ. إذا حذفت قناع الحقول، ستعرض الطريقة خطأً. اضبط قناع الحقول على
*لعرض جميع الحقول. لمزيد من التفاصيل، يُرجى الاطّلاع على مقالة اختيار الحقول التي سيتم عرضها.
المعلمات الاختيارية
-
travelModes
تحدّد أنواع
navigationPointsالتي سيتم عرضها. وسيتم استبعاد نقاط التنقّل لوسائل النقل الأخرى. إذا لم يتم ضبطtravelModes، يمكن عرض نقاط التنقّل لجميع وسائل النقل. languageCode
اللغة التي سيتم عرض النتائج بها
- الاطّلاع على قائمة اللغات المتاحة. كثيرًا ما تعدّل Google اللغات المتاحة، لذا قد لا تكون هذه القائمة شاملة.
-
إذا لم يتم تقديم
languageCode، ستستخدم واجهة برمجة التطبيقات اللغةenتلقائيًا. إذا حدّدت رمز لغة غير صالح، ستعرض واجهة برمجة التطبيقات الخطأINVALID_ARGUMENT - تبذل واجهة برمجة التطبيقات قصارى جهدها لتقديم عنوان شارع يمكن قراءته لـ لكل من المستخدم والسكان المحليين. لتحقيق هذا الهدف، تعرض واجهة برمجة التطبيقات عناوين الشوارع باللغة المحلية، مع نقلها إلى نص يمكن للمستخدم قراءته إذا لزم الأمر، مع مراعاة اللغة المفضّلة. يتم عرض جميع العناوين الأخرى باللغة المفضّلة. يتم عرض جميع مكوّنات العنوان باللغة نفسها، والتي يتم اختيارها من المكوّن الأول.
- إذا لم يكن الاسم متاحًا باللغة المفضّلة، تستخدم واجهة برمجة التطبيقات أقرب نتيجة مطابِقة.
- تؤثر اللغة المفضّلة تأثيرًا طفيفًا في مجموعة النتائج التي تختار واجهة برمجة التطبيقات عرضها، والترتيب الذي يتم عرضها به. يفسّر برنامج الترميز الجغرافي الاختصارات بشكل مختلف حسب اللغة، مثل اختصارات أنواع الشوارع أو المرادفات التي قد تكون صالحة في لغة واحدة ولكن ليس في لغة أخرى.
regionCode
رمز المنطقة كقيمة رمز CLDR مكوّنة من حرفَين لا توجد قيمة تلقائية. تتطابق معظم رموز CLDR مع رموز ISO 3166-1.
عند ترميز عنوان جغرافيًا، الترميز الجغرافي الأمامي، يمكن أن تؤثر هذه المَعلمة في النتائج من الخدمة في المنطقة المحدّدة، ولكن لا يمكنها حصرها بالكامل. عند ترميز موقع جغرافي أو مكان جغرافيًا، عكس الترميز الجغرافي أو الترميز الجغرافي للمكان، يمكن استخدام هذه المَعلمة لتنسيق العنوان. في جميع الحالات، يمكن أن تؤثر هذه المَعلمة في النتائج استنادًا إلى القانون الساري.
-
placeFilter
تتيح لك فلترة نتائج البحث
locationQueryلتلبية متطلباتك، مثل عرض الوجهات التي هي مبانٍ فقط أو الوجهات التي لها عناوين واضحة فقط.الفلترة حسب الدقة الهيكلية
يتيح لك فلتر
structureTypeتحديد نوع الهياكل التي يعرضها طلب البحث:- عزل المباني: استخدِم
"structureType": "BUILDING"لعرض المخططات التفصيلية للمباني على خريطة أو الحصول على تفاصيل لهيكل محدّد. - فهم المجمّعات: استخدِم
"structureType": "GROUNDS"لضمان أن تكون النتيجة الرئيسية هي الأراضي الإجمالية. يكون هذا مفيدًا عند طلب البحث عن مناطق أكبر، مثل حرم جامعي أو مراكز تسوّق. - التركيز على الوحدات/الأقسام: استخدِم
"structureType": "SECTION"لتحديد الأقسام ضِمن مبنى.
ضمان توفّر عناوين مفيدة
لا تحتوي بعض الأماكن على عناوين واضحة على مستوى الشارع. يساعدك فلتر
addressabilityفي التحكّم في جودة العناوين في نتائجك:- طلب عنوان أساسي واضح: لضمان أن تحتوي نتيجة الوجهة الرئيسية دائمًا على عنوان أو اسم على مستوى الشارع، استخدِم
"addressability": "PRIMARY". يكون هذا مفيدًا لأغراض التنقّل أو العرض حيث يكون العنوان الواضح ضروريًا. - السماح بالعناوين في الوجهات الفرعية: في الحالات التي قد لا يكون للمكان الرئيسي عنوان، ولكن الوحدات ضِمنه لها عنوان (مثل الشقق في مبنى)، يضمن
"addressability": "WEAK"أن يكون للمكان الرئيسي أو إحدى وجهاته الفرعية عنوان على الأقل. - أي نتيجة: إذا لم يكن توفّر العنوان مهمًا لحالة الاستخدام، استخدِم
"addressability": "ANY".
مثال: الفلترة للمباني التي يمكن تحديد عنوان لها
curl -X POST -d '{ "locationQuery": { "location": { "latitude": 37.37348780, "longitude": -122.05678064 }, "placeFilter": { "structureType": "BUILDING", "addressability": "PRIMARY" } }, "languageCode": "en" }' \\ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \\ -H "X-Goog-FieldMask: place" \\ https://geocode.googleapis.com/v4/geocode/destinations - عزل المباني: استخدِم