تشير Destination إلى نقطة اهتمام أو موقع جغرافي محدّد ينوي المستخدم الوصول إليه أو الانتقال نحوه. يمكن أن تتضمّن Destination معلومات مثل نقاط التنقّل والمعالم البارزة والمداخل ومخططات المباني.
تتيح لك نقطة نهاية
SearchDestinations
في Geocoding API استرداد معلومات تفصيلية حول
وجهات مختلفة استنادًا إلى معايير إدخال مختلفة، مثل عنوان أو
معرّف مكان أو إحداثيات خطوط الطول والعرض.
طلب البحث عن الوجهات
طلب البحث عن وجهات هو طلب HTTP POST يتم إرساله إلى عنوان URL بالتنسيق التالي:
https://geocode.googleapis.com/v4beta/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/v4beta/geocode/destinations
يمكنك تحديد الموقع الجغرافي للبحث عن وجهة بإحدى الطرق الثلاث التالية:
- العنوان
- معرّف المكان
- إحداثيات خطوط العرض وخطوط الطول
البحث عن وجهة حسب العنوان
يمكنك تحديد العنوان كسلسلة غير منظَّمة. لا يحلّ الترميز الجغرافي للعناوين إحداثيات خطوط الطول والعرض أو السلاسل الأخرى غير المنظَّمة التي لا تمثّل عنوانًا. لا تتوافق الطلبات التي تستخدم سلاسل من هذا النوع، وقد تؤدي إلى ظهور ردود تتضمّن أخطاء أو سلوك غير محدّد. تشمل الأمثلة على طلبات البحث غير المتوافقة ما يلي:
| نوع طلب البحث | مثال |
|---|---|
| إحداثيات خط العرض وخط الطول استخدِم طلب بحث عن موقع جغرافي بدلاً من ذلك. | "37.422131,-122.084801" |
| عدد كبير جدًا من المفاهيم أو القيود، مثل أسماء أماكن أو طرق أو مدن متعددة في طلب بحث واحد | "شارع ماركت في سان فرانسيسكو، مطار سان خوسيه" |
| عناصر العنوان البريدي غير الممثّلة على "خرائط Google" |
"C/O John Smith 123 Main Street" "P.O. Box 13 San Francisco" |
| أسماء الأنشطة التجارية أو السلاسل أو الفئات مع المواقع الجغرافية التي لا تتوفّر فيها هذه الكيانات | "Tesco بالقرب من دالاس، تكساس" |
| طلبات بحث غامضة تتضمّن تفسيرات متعددة | "تسليم الشاحن" |
| الأسماء القديمة التي لم يعُد يتم استخدامها | "Middlesex United Kingdom" |
| العناصر أو النية غير الجغرافية المكانية | "كم عدد القوارب في ميناء فينتورا؟" |
| أسماء غير رسمية أو أسماء مستعارة |
"The Jenga" "The Helter Skelter" |
| الكيانات السياسية الكبيرة (المدن والولايات والبلدان) |
"مدينة نيويورك" "كاليفورنيا" "الولايات المتحدة الأمريكية" |
| المسارات التي لا تتضمّن عناوين محدّدة |
"1st Ave., NYC, NY" "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/v4beta/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/v4beta/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/v4beta/geocode/destinations
أرقام تعريف الأماكن المتوافقة
تعمل نقطة نهاية "بحث في الوجهات" على أفضل نحو مع معرّفات الأماكن التي تمثّل وجهات محدّدة يمكن الانتقال إليها.
تتوفّر بشكل عام أرقام تعريف الأماكن لأنواع مثل establishment وpoint_of_interest وpremise وstreet_address وsubpremise.
لا تتوافق معرّفات الأماكن التي لا تمثّل مواقع جغرافية منفصلة، مثل تلك المستنتَجة من نطاقات العناوين (على سبيل المثال، "10-20 شارع Main") أو أقسام من مسار بدون رقم محدّد أو رموز المواقع المفتوحة.
لضمان التوافق عند استخدام ميزة "الإكمال التلقائي للأماكن" للعثور على معرّفات الأماكن، ننصحك بفلترة النتائج حسب النوع. يمكنك استخدام المَعلمة
includedPrimaryTypes
في طلبات الإكمال التلقائي لتضمين الأنواع المتوافقة فقط
المدرَجة أعلاه:
"includedPrimaryTypes": [ "establishment", "point_of_interest", "premise", "street_address", "subpremise" ]
يضمن ذلك أنّ أرقام تعريف الأماكن التي تعرضها ميزة "الإكمال التلقائي للأماكن" هي الأكثر توافقًا مع طريقة Search Destinations. يُرجى العِلم أنّ النوع
establishment واسع النطاق. على الرغم من أنّ هذا الفلتر ضروري لتحديد العديد من المواقع الجغرافية الخاصة بالأنشطة التجارية، قد يتضمّن أيضًا نتائج ميزة "الإكمال التلقائي للأماكن" لأنواع natural_feature التي لا تتوفّر لها سوى إمكانية محدودة في "وجهات البحث".
البحث عن وجهة حسب الموقع الجغرافي
يمكنك البحث عن وجهة من خلال تقديم إحداثيات خط العرض وخط الطول:
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/v4beta/geocode/destinations
استخدام OAuth لتقديم طلب
تتيح الإصدار 4 من Geocoding API استخدام OAuth 2.0 للمصادقة. لاستخدام OAuth مع Geocoding API، يجب منح رمز OAuth المميز النطاق الصحيح. تتيح Geocoding API النطاقات التالية لاستخدامها مع نقطة النهاية Destinations:
https://www.googleapis.com/auth/maps-platform.geocode— تُستخدَم مع جميع نقاط نهاية Geocoding API.
يمكنك أيضًا استخدام النطاق العام https://www.googleapis.com/auth/cloud-platform
لجميع نقاط نهاية Geocoding API. يكون هذا النطاق مفيدًا أثناء التطوير، ولكن ليس أثناء الإنتاج، لأنّه نطاق عام يتيح الوصول إلى جميع نقاط النهاية.
لمزيد من المعلومات والأمثلة، يُرجى الاطّلاع على استخدام بروتوكول OAuth.
ردّ البحث عن الوجهات
تقدّم استجابة "وجهات البحث" سياقًا غنيًا وعلى مستوى منطقة محلية صغيرة حول الموقع الجغرافي.
يوضّح هذا القسم حقول الاستجابة الرئيسية. للاطّلاع على التفاصيل الكاملة حول جميع حقول الرد، يُرجى الرجوع إلى مرجع واجهة برمجة التطبيقات.
primary
المكان الرئيسي الذي يحدّده طلب البحث في الطلب.
containingPlaces
تشير هذه السمة إلى الكيانات الأكبر التي يشكّل الوجهة الأساسية جزءًا منها (مثلاً، مركز تسوّق يضم متجرًا).
subDestinations
مواقع جغرافية أكثر تحديدًا ضمن الوجهة الأساسية (على سبيل المثال، شقق في مبنى)
entrances
تحتوي العناصر في مصفوفة entrances[] على الحقول التالية:
locationزوج إحداثيات خط العرض وخط الطول الفردي الذي يحدّد موقع نقطة الدخول والخروج من مكان.
entrance_tags[]تمثّل هذه السمة مصفوفة من علامات المداخل التي تصف خصائص المدخل. يمكن استخدام القيمة التالية:
"PREFERRED"تشير إلى أنّ هذا المدخل يوفّر على الأرجح إمكانية الوصول الفعلي إلى المكان الذي تم عرضه. يمكن أن يكون للمكان عدة مداخل مفضّلة. إذا لم يكن لأحد المداخل هذه العلامة، يعني ذلك أنّ المدخل يقع في المبنى نفسه، ولكنّه لا يتيح بالضرورة الوصول إلى المكان.
على سبيل المثال، إذا كان المكان الذي تم عرضه هو مطعم في قطاع مركز تجاري، ستكون
"PREFERRED"المداخل المعروضة هي تلك التي تؤدي إلى المطعم نفسه، بينما ستكون المداخل الأخرى المعروضة هي مداخل أخرى للمبنى، مثل المداخل المؤدية إلى مطاعم أخرى في قطاع المركز التجاري.إذا كان المكان الذي تم عرضه عبارة عن مبنى، ستكون المداخل
"PREFERRED"هي تلك التي تؤدي إلى الجزء "الرئيسي" من المبنى. على سبيل المثال، في مركز تسوّق، ستكون المداخل"PREFERRED"هي تلك التي تتيح الوصول إلى منطقة البهو الرئيسية، ولكن إذا كان المدخل يتيح الوصول إلى متجر على جانب المبنى فقط، فلن يكون مدخلاً"PREFERRED".
structureType
تمثّل هذه السمة نوع البنية التي يمثّلها هذا المكان.
POINTموقع جغرافي على شكل نقطة
SECTIONقسم فرعي من مبنى
BUILDINGمبنى
GROUNDSمساحة كبيرة تحتوي عادةً على مبانٍ متعددة، مثل مجمّع جامعي أو مجمّع سكني أو مركز تسوّق
navigationPoints
يحتوي الحقل navigationPoints ضمن استجابة الترميز الجغرافي على قائمة بنقاط مفيدة للتنقّل إلى المكان. على وجه التحديد، يجب استخدامها كنقاط بداية أو نهاية عند تحديد المسار على شبكة طرق من المكان أو إليه. تحتوي كل نقطة تنقّل على القيم التالية:
navigationPointTokenهو رمز مميّز يحتوي على المعلومات السياقية في الحقلnavigationPoints. يمكنك إرسال هذا الرمز المميّز إلى واجهات برمجة التطبيقات الخاصة بالتوجيه والتنقّل لتحسين تجربة التوجيه والتنقّل في الأنهار داخل تطبيقك. اطّلِع على التوجيه باستخدام الرموز المميّزة لنقاط التنقّل لمزيد من المعلومات.- يحتوي
locationعلى قيمة خط الطول والعرض لنقطة التنقّل. سيكون هذا الموقع الجغرافي دائمًا قريبًا جدًا من شبكة الطرق ويمثّل نقطة توقّف أو نقطة البداية المثالية للتنقّل من مكان وإليه. يتم إزاحة النقطة قليلاً عن قصد من خط المنتصف للطريق لتحديد الجانب الذي يقع فيه المكان بوضوح. travelModesهي قائمة بوسائل النقل التي يمكن الوصول إلى نقطة التنقّل من خلالها:"DRIVE"هو وضع السفر الذي يتوافق مع اتجاهات القيادة.-
"WALK"هي وسيلة النقل التي تتوافق مع اتجاهات المشي.
usagesهي قائمة بالاستخدامات التي تتيحها نقطة التنقّل. يمكن أن تكون حالات الاستخدام كما يلي:"DROPOFF""PICKUP""PARKING"
arrivalSummary
إحصاءات مستندة إلى الذكاء الاصطناعي للمساعدة في الوصول إلى الوجهة ملخّصات تستند إلى الذكاء الاصطناعي
landmarks
أماكن قريبة بارزة لمساعدة المستخدمين في فهم محيط الوجهة
تنسيق الردّ
تعرض SearchDestinations
SearchDestinationsResponse
بالتنسيق التالي:
{ "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/v4beta/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/v4beta/geocode/destinations - عزل المباني: استخدِم
الملاحظات
هذه نقطة نهاية تجريبية لواجهة Geocoding API. يسرّنا تلقّي ملاحظاتك على geocoding-feedback-channel@google.com.