Destination
به مکان یا جای خاصی اشاره دارد که کاربر قصد دارد به آنجا برسد یا بهسمت آن پیمایش کند. Destination همچنین شامل مجموعهای از اطلاعات مربوط به مکان یا جا میشود، مثل نقاط ناوبری، نشانگرهای مکانی، ورودیها، و طرح کلی ساختمان.
روش
SearchDestinations
در Geocoding API به شما امکان میدهد اطلاعات دقیقی درباره مقصدهای مختلف براساس معیارهای ورودی متفاوت، مانند نشانی، شناسه مکان، یا مختصات طول و عرض جغرافیایی، بازیابی کنید.
درخواست جستجوی مقصدها
درخواست مقصد جستجو درخواست HTTP POST به نشانی وبی با این قالب است:
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" |
| مفاهیم یا محدودیتهای بسیار زیاد، مانند نام چندین مکان، جاده، یا شهر در یک پُرسمان | «Market Street San Francisco San Jose Airport» |
| عناصر نشانی پستی که در Google Maps نشان داده نمیشود |
«C/O John Smith 123 Main Street» «P.O. Box 13 San Francisco» |
| نام کسبوکارها، زنجیرهها، یا دستههایی که با مکانهایی ترکیب شدهاند که این نهادها در آنها دردسترس نیستند | «Tesco near Dallas, Texas» (تسکو نزدیک دالاس، تگزاس) |
| پرسمانهای مبهم با چند تفسیر | «تحویل شارژر» |
| نامهای قدیمی که دیگر استفاده نمیشوند | "Middlesex United Kingdom" |
| عناصر یا هدف غیرزمینمکانی | «چند قایق در بندر ونتورا وجود دارد؟» |
| نامهای غیررسمی یا نامهای سفارشی |
«برج هیجان» «سرسره مارپیچ» |
| نهادهای سیاسی بزرگ (شهرها، ایالتها، کشورها) |
"New York City" "California" "USA" |
| مسیرهای بدون نشانی مشخص |
«خیابان اول، 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/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
معمولاً هنگام پردازش مؤلفههای نشانی ضبطشده در فرم HTML، از قالب postalAddress استفاده میکنید.
جستجوی مقصد با شناسه مکان
میتوانید مقصد را با ارائه شناسه مکان بازیابی کنید:
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 معمولاً
پشتیبانی میشوند. شناسههای مکانی که مکانهای مجزا را نشان نمیدهند، مانند شناسههایی که از محدودههای نشانی استنباط میشوند (برای مثال، «خیابان اصلی ۱۰-۲۰»)، بخشهایی از یک مسیر بدون شماره خاص، یا کدهای پلاس، پشتیبانی نمیشوند. شناسههای مکان برای
نتایجی که منطقه بسیار بزرگی را پوشش میدهند (برای مثال، «اقیانوس آرام») نیز
پشتیبانی نمیشوند.
استفاده از «تکمیل خودکار» (جدید) با «جستجوی مقصدها»
برای اطمینان از سازگاری، از تکمیل خودکار (جدید) برای پیدا کردن «شناسههای مکان» برای استفاده با «مقاصد جستجو» استفاده کنید. هنگام استفاده از «تکمیل خودکار» (جدید)، باید نتایج را براساس نوع بااستفاده از پارامتر
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 نسخه ۴ از 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 مراجعه کنید.
پاسخ جستجوی مقصدها
پاسخ Search Destinations بافت غنی و بسیار محلی درباره مکان ارائه میدهد.
اشیا PlaceView در پاسخ «مقاصد جستجو» (مثل primary، موارد در containingPlaces، و landmarks) از فیلدهایی برای نشان دادن نوع مکان استفاده میکنند:
types: آرایهای از رشتهها که نوع(های) مکان را نشان میدهد.primaryType: رشتهای که نوع اصلی مکان را نشان میدهد.
مقادیر رشتهای ممکن برای types و primaryType از جدول الف و جدول ب در صفحه «انواع مکان (جدید)» گرفته شده است.
این بخش فیلدهای پاسخ کلیدی را شرح میدهد. برای جزئیات کامل درباره همه فیلدهای پاسخ، به مرجع میانای برنامهسازی کاربردی مراجعه کنید.
primary
مکان اصلی شناساییشده توسط پُرسمان در درخواست.
addressComponents
آرایهای حاوی عناصر جداگانه مربوط به این نشانی.
هر عنصر نشانی معمولاً شامل فیلدهای زیر است:
types[]آرایهای است که نوع مؤلفه نشانی را نشان میدهد. فهرست انواع پشتیبانیشده را ببینید.longTextشرح نوشتاری کامل یا نام عنصر نشانی است که توسط «کدبند» برگردانده میشود.shortTextنام متنی اختصاری برای مؤلفه نشانی است، درصورت وجود. برای مثال، عنصر نشانی برای ایالت آلاسکا ممکن استlongTextآن «آلاسکا» وshortTextآن «AK» باشد که از مخفف دوحرفی پستی استفاده میکند.-
languageCodeزبانی است که برای قالببندی این عنصر استفاده میشود، با نماد CLDR.
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 در پاسخ «زمینکدیابی» حاوی فهرستی از
نقطههایی است که برای پیمایش به مکان مفید هستند. بهطور دقیق، این مکانها باید
هنگام مسیریابی در شبکه جادهای از
یا به مکان، بهعنوان نقطه شروع یا پایان استفاده شوند.
هر نقطه پیمایش حاوی مقادیر زیر است:
-
navigationPointTokenکدی است که حاوی اطلاعات زمینهای در فیلدnavigationPointsاست. میتوانید این توکن را به میاناهای برنامهسازی کاربردی مسیریابی و ناوبری ارسال کنید تا تجربه مسیریابی و رانندگی را در برنامهتان بهبود بخشید. برای اطلاعات بیشتر، مسیریابی بااستفاده از توکنهای نقطه ناوبری را ببینید. locationحاوی مقدار عرض جغرافیایی و طول جغرافیایی نقطه پیمایش است. این مکان همیشه بسیار نزدیک به شبکه جادهای خواهد بود و نقطه توقف یا شروع ایدهآلی برای پیمایش به و از یک مکان را نشان میدهد. این نقطه عمداً کمی از خط مرکزی جاده فاصله دارد تا طرف جادهای که مکان در آن قرار دارد بهوضوح مشخص شود.-
travelModesفهرستی از حالتهای سفر است که نقطه پیمایش از آنها قابلدسترس است:"DRIVE"حالت سفر مربوط به مسیرهای رانندگی است."WALK"حالت سفر مربوط به مسیرهای پیادهروی است.
-
usagesفهرستی از کاربردهای پشتیبانیشده توسط نقطه پیمایش است. موارد استفاده میتواند اینها باشد:"DROPOFF""PICKUP""PARKING"
برای تحویل گرفتن و تحویل دادن، از نقطه پیمایش استفاده کنید که در آن حالت سفر DRIVE
و استفاده PICKUP یا DROPOFF باشد. اگر نقاط سوار کردن یا پیاده کردن دردسترس نیست،
از نقطه ناوبری رانندگی بالا استفاده کنید.
streetViewThumbnailوentranceAnnotationپارامترهایی برای Street View Static API ارائه میدهند که به شما امکان میدهد تصاویر مربوط به این مکانها را نمایش دهید. درباره این فیلدها بیشتر بدانید.
altitude_metersحاوی ارتفاع نقطه پیمایش به متر نسبت به بیضوی WGS-84 است. در مواردی که بخشهای جاده بهصورت عمودی روی هم قرار گرفتهاند، از فیلدaltitude_metersاستفاده کنید تا بهترین بخش جاده را برای سیستم خود انتخاب کنید تا به آن پیمایش کند.
landmarks
مکانهای قابلتوجه در این اطراف برای کمک به کاربران در درک محیط مقصد.
هر نقطه عطف شامل فیلدهای زیر است:
placePlaceViewشیء است که این نشانگر مکانی را نشان میدهد.relationalDescriptionشرحی قابلخواندن برای انسان است که نشان میدهد مقصد چه ارتباطی با نشانگر مکانی دارد، مثلاً «نزدیک ساختمان امپایر استیت» یا «روبهروی کاخ سفید».tags[]آرایهای از برچسبها است که نحوه استفاده از نشانگر مکانی را در بافت مقصد شرح میدهد:-
"ADDRESS": مکان برجسته محلی که میتوان از آن برای شناسایی مکان کلی مقصد استفاده کرد. "ARRIVAL": مکانی که میتواند برای کمک به رسیدن به مقصد استفاده شود، برای ناوبری در نزدیکی مقصد مفید است.
-
straightLineDistanceMetersفاصله مستقیم از این نشانگر مکانی تا مقصد به متر است.travelDistanceMetersفاصله پیادهروی از این مکان دیدنی تا مقصد به متر است.
arrivalSummary
اطلاعات آماری با بهرهگیری از هوش مصنوعی برای کمک به رسیدن به مقصد. خلاصههای با پشتیبانی هوش مصنوعی را ببینید.
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" ] } ] } ] }
پارامترهای الزامی
- یکی از ۳ پارامتر زیر باید در درخواست API باشد، که
نشانی، مکان، یا موقعیت مکانی را برای جستجوی مقصد مشخص میکند:
-
addressQuery- نشانیای که باید جستجو شود. place- شناسه مکان مکانی که باید جستجو شود.locationQuery- مختصات طول و عرض جغرافیایی مکان موردنظر برای جستجو.
-
FieldMask
با ایجاد پوشش فیلد پاسخ، فهرست فیلدهای برگشتی در پاسخ را مشخص کنید. ماسک فیلد پاسخ را بااستفاده از پارامتر نشانی وب
$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ارائه نشده باشد، API بهطور پیشفرض از زبان محلی و نویسههای مکان استفاده میکند. اگر کد زبان نامعتبری را مشخص کنید، میانای برنامهسازی کاربردی خطایINVALID_ARGUMENTرا برمیگرداند. - این میانای برنامهسازی کاربردی تمام تلاش خود را میکند تا نشانی خیابانی ارائه دهد که هم برای کاربر و هم برای افراد محلی قابلخواندن باشد. برای دستیابی به این هدف، نشانیهای خیابان را به زبان محلی برمیگرداند و درصورت لزوم، با رعایت زبان ترجیحی، آنها را به نویسهای که برای کاربر خوانا باشد نویسهگردانی میکند. همه نشانیهای دیگر به زبان ترجیحی برگردانده میشوند. اجزای نشانی همه به یک زبان برگردانده میشوند که از اولین جزء انتخاب میشود.
- اگر نامی به زبان ترجیحی دردسترس نباشد، API از نزدیکترین مطابقت استفاده میکند.
- زبان ترجیحی تأثیر کمی بر مجموعه نتایجی دارد که میانای برنامهسازی کاربردی برای برگرداندن انتخاب میکند و ترتیبی که در آن برگردانده میشوند. زمینکدیاب اختصارات را بسته به زبان بهطور متفاوتی تفسیر میکند، مانند اختصارات برای انواع خیابانها، یا مترادفهایی که ممکن است در یک زبان معتبر باشند اما در زبان دیگر معتبر نباشند.
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 - جداسازی ساختمانها: از