- درخواست اچتیتیپی
- بدنه درخواست
- متن پاسخ
- گسترههای مجوز
- SearchDestinationsRequest.AddressQuery
- SearchDestinationsRequest.LocationQuery
- SearchDestinationsRequest.LocationQuery.PlaceFilter
- PlaceView.StructureType
- SearchDestinationsRequest.LocationQuery.PlaceFilter.Addressability
- NavigationPoint.TravelMode
- مقصد
- PlaceView
- PlaceView.AddressComponent
- نشانگر مکانی
- Landmark.Tag
- ورودی
- Entrance.Tag
- StreetViewThumbnail
- ImageAnnotation
- ImageAnnotation.Coordinate
- NavigationPoint
- NavigationPoint.Usage
- Destination.ParkingOptions
- Destination.ParkingOptions.Availability
- Destination.ArrivalSummary
این روش جستجوی مقصد را انجام میدهد و فهرستی از مقصدها را برمیگرداند.
درخواست HTTP
POST https://geocode.googleapis.com/v4alpha/geocode/destinations
نشانی وب از نحو تراتبدیل gRPC استفاده میکند.
متن درخواست
بدنه درخواست حاوی دادههایی با ساختار زیر است:
| نمایش JSON |
|---|
{ "travelModes": [ enum ( |
| فیلدها | |
|---|---|
travelModes[] |
اختیاری. حالتهای سفر برای فیلتر کردن نقاط پیمایش. این کار بر فیلد |
languageCode |
اختیاری. زبان نتایجی که باید برگردانده شود. |
regionCode |
اختیاری. کد منطقه. کد منطقه، که بهعنوان مقدار دو نویسهای ccTLD («دامنه سطح بالا») مشخص شده است. این پارامتر براساس قانون ذیربط بر نتایج تأثیر میگذارد. این پارامتر همچنین بر نتایج سرویس تأثیر میگذارد، اما آنها را کاملاً محدود نمیکند. |
فیلد اتحادیه مقصدها براساس پُرسمان اصلی مشخصشده ساخته میشوند. توجه: فقط مکانها و نشانیهایی که میتوانند مقصد ناوبری داشته باشند پشتیبانی میشوند. برای مثال، مکانی که نشاندهنده خانه یا مجتمع آپارتمانی است میتواند بهعنوان پُرسمان اصلی استفاده شود، اما مکانهایی که نشاندهنده محل یا تقسیمات کشوری هستند نمیتوانند بهعنوان پُرسمان اصلی استفاده شوند. |
|
place |
نام منبع مکان، در قالب |
addressQuery |
نشانی خیابان. |
locationQuery |
مکان دقیق. |
متن پاسخ
پیام پاسخ برای DestinationService.SearchDestinations.
اگر موفقیتآمیز باشد، بدنه پاسخ حاوی دادههایی با ساختار زیر است:
| نمایش JSON |
|---|
{
"destinations": [
{
object ( |
| فیلدها | |
|---|---|
destinations[] |
فهرستی از مقصدها. اگر مقصد اصلی را بتوان بهطور واضح از پُرسمان اصلی شناسایی کرد، این سرویس یک نتیجه برمیگرداند. درغیراینصورت، ممکن است سرویس چندین نتیجه برای ابهامزدایی یا صفر نتیجه برگرداند. |
دامنههای مجوز
به یکی از دامنههای OAuth زیر نیاز دارد:
https://www.googleapis.com/auth/cloud-platformhttps://www.googleapis.com/auth/maps-platform.geocodehttps://www.googleapis.com/auth/maps-platform.destinations
SearchDestinationsRequest.AddressQuery
نشانی خیابانی که میخواهید جستجو کنید. نشانیها را مطابق با قالب مورداستفاده خدمات پستی ملی کشور مربوطه مشخص کنید.
| نمایش JSON |
|---|
{ // Union field |
| فیلدها | |
|---|---|
فیلد اتحادیه kind. پُرسمان نشانی. kind فقط میتواند یکی از موارد زیر باشد: |
|
address |
نشانی خیابان در قالب نشانی پستی. |
addressQuery |
نشانی خیابان که بهعنوان یک خط قالببندی شده است. |
SearchDestinationsRequest.LocationQuery
پُرسمان مکان برای شناسایی مقصد اصلی در اطراف.
توجه: اگر پُرسمان مکان در ساختمانی باشد که شامل زیرمکان است، ممکن است مکان اصلی برگرداندهشده یک زیرمکان باشد. در این موارد، فیلد containingPlaces ساختمان را دربر خواهد گرفت.
| نمایش JSON |
|---|
{ "placeFilter": { object ( |
| فیلدها | |
|---|---|
placeFilter |
اختیاری. فیلترهایی که باید برای مقصدهای احتمالی اعمال شود. |
فیلد اتحادیه kind. پُرسمان مکان. kind فقط میتواند یکی از موارد زیر باشد: |
|
location |
مکان دقیق طول و عرض جغرافیایی. |
SearchDestinationsRequest.LocationQuery.PlaceFilter
فیلترهایی که باید برای مقصدهای احتمالی اعمال شود.
| نمایش JSON |
|---|
{ "structureType": enum ( |
| فیلدها | |
|---|---|
structureType |
اختیاری. اگر مشخص شده باشد، تضمین میشود که همه مقصدها مکان اصلی با این نوع ساختار داشته باشند. این امر میتواند منجر به فیلتر شدن برخیاز مقصدها یا درشتنمایی/پالایش مقصدهای برگرداندهشده شود. برای مثال، اگر استفاده دیگر از این فیلد، استخراج آسانتر چندضلعیهای نمایش ساختمان است. برای مثال، اگر |
addressability |
اختیاری. اگر مشخص شده باشد، فقط مقصدهایی را برمیگرداند که معیارهای آدرسپذیری مربوطه را برآورده میکنند. |
PlaceView.StructureType
نوع ساختاری که این مکان نشان میدهد.
| شمارشیها | |
|---|---|
STRUCTURE_TYPE_UNSPECIFIED |
استفادهنشده. |
POINT |
مکان نقطهای. |
SECTION |
زیربخشی از ساختمان. |
BUILDING |
ساختمان. |
GROUNDS |
منطقه بزرگی که معمولاً شامل چندین ساختمان میشود، مثل پردیس دانشگاه، مجموعه آپارتمانی، یا مرکز خرید. |
SearchDestinationsRequest.LocationQuery.PlaceFilter.Addressability
گزینههایی را برای فیلتر کردن آدرسپذیری تعریف میکند. ممکن است مقادیر جدیدی در آینده اضافه شود.
| شمارشیها | |
|---|---|
ADDRESSABILITY_UNSPECIFIED |
اگر مشخص نشده باشد، سرویس یک پیشفرض معقول را انتخاب خواهد کرد. |
ANY |
آدرسپذیری جزو معیارهای فیلتر کردن نیست. مقصدها صرفنظر از آدرسپذیر بودنشان برگردانده میشوند. |
PRIMARY |
همه مقصدهای برگرداندهشده دارای مکانی اصلی با نام یا نشانی در سطح خیابان خواهند بود. |
WEAK |
همه مقصدهای برگرداندهشده یا مکان اصلی خواهند داشت یا مقصد فرعی با نام یا نشانی سطح خیابان. |
مقصد
مقصد. این شامل مکان اصلی، مکانهای مرتبط، ورودیها، و نقاط ناوبری میشود.
| نمایش JSON |
|---|
{ "primary": { object ( |
| فیلدها | |
|---|---|
primary |
مکان اصلی که |
containingPlaces[] |
مکانهای با دقت کمتر که مکان اصلی در آنها قرار دارد. برای مثال، مجتمع آپارتمانی که این ساختمان در آن قرار دارد. |
subDestinations[] |
مقصد فرعی دقیقتر از مکان اصلی. برای مثال، واحدهای موجود در یک ساختمان. توجه: درمقایسه با SubDestination که Places API برمیگرداند، این فهرست مقصدهای فرعی جامعتر است و هر مقصد فرعی حاوی اطلاعات بیشتری است. |
landmarks[] |
نشانگرهای مکانی که میتوانند برای اطلاعرسانی درباره مکان مقصد یا کمک به رسیدن به آن استفاده شوند. |
entrances[] |
ورودیهای این مقصد. |
navigationPoints[] |
نقاط ناوبری برای این مقصد. |
parkingOptions |
گزینههای پارکینگ برای این مقصد. |
arrivalSummary |
خلاصه تولیدشده با هوش مصنوعی از تجربه ورود به مقصد. |
PlaceView
نمای Place را در Places API نشان میدهد. همچنین اطلاعات بیشتری را که مختص مقصدها است، مانند نوع ساختار و چندضلعی نمایش، ارائه میدهد.
در برخی موارد، PlaceView با همان شناسه مکان ممکن است با آنچه توسط Places API برای فیلدهای types و displayName برگردانده میشود متفاوت باشد.
| نمایش JSON |
|---|
{ "place": string, "displayName": { object ( |
| فیلدها | |
|---|---|
place |
نام منبع این «مکان»، در قالب |
placeId |
شناسه یکتای مکان. |
displayName |
شرح مکان قابلخواندن برای انسان. برای مثال، «دروازه B»، «مکدونالد» |
primaryType |
نوع مکان اصلی این مکان. برای مشاهده فهرست مقادیر ممکن، به https://developers.google.com/maps/documentation/places/web-service/place-types مراجعه کنید. توجه: این فیلد همیشه درج نمیشود. برای استفاده از فیلد |
types[] |
همه انواع مکانهای مرتبط با این مکان. برای فهرست مقادیر ممکن، https://developers.google.com/maps/documentation/places/web-service/place-types را ببینید. |
formattedAddress |
نشانی یکخطی. |
postalAddress |
نشانی ساختارمند. |
structureType |
نوع ساختار مربوط به این مکان. |
location |
مکان این مکان. برای مکانهایی که چندضلعی نمایشی دارند، این میتواند نقطه خوبی برای قرار دادن نشانگر روی نقشه باشد. |
displayPolygon |
طرح کلی چندضلعی مکان در قالب GeoJSON، بااستفاده از قالب RFC 7946: https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.6. توجه: قالب RFC 7946 از MultiPolygons پشتیبانی میکند، بنابراین یک شیء |
addressComponents[] |
مؤلفههای تکراری برای هر سطح محلی. |
PlaceView.AddressComponent
عناصر ساختاری که نشانی قالببندیشده را تشکیل میدهند، درصورتیکه این اطلاعات دردسترس باشد.
| نمایش JSON |
|---|
{ "longText": string, "shortText": string, "types": [ string ], "languageCode": string } |
| فیلدها | |
|---|---|
longText |
شرح نوشتاری کامل یا نام مؤلفه نشانی. برای مثال، مؤلفه نشانی برای کشور استرالیا ممکن است نام طولانی «استرالیا» را داشته باشد. |
shortText |
نام نوشتاری مخفف برای عنصر نشانی، درصورت وجود. برای مثال، عنصر نشانی مربوط به کشور استرالیا ممکن است نام کوتاهی بهصورت «AU» داشته باشد. |
types[] |
آرایهای که نوع(انواع) مؤلفه نشانی را نشان میدهد. برای جزئیات بیشتر، https://developers.google.com/maps/documentation/geocoding/requests-geocoding#Types را ببینید. |
languageCode |
زبانی که برای قالببندی این مؤلفه استفاده میشود، در نماد CLDR. |
نشانگر مکانی
از نشانگرهای مکانی برای اطلاعرسانی درباره مکان مقصد یا کمک به رسیدن به مقصد استفاده میشود.
| نمایش JSON |
|---|
{ "relationalDescription": { object ( |
| فیلدها | |
|---|---|
relationalDescription |
شرحی قابلخواندن برای انسان درباره اینکه مقصد چه ارتباطی با نشانگر مکانی دارد. برای مثال: «نزدیک ساختمان امپایر استیت» یا «روبهروی کاخ سفید». |
tags[] |
برچسبهایی که نحوه استفاده از مکان دیدنی را در بافت مقصد توصیف میکنند. |
straightLineDistanceMeters |
فقط برونداد. فاصله مستقیم از این مکان دیدنی تا مقصد برحسب متر. |
travelDistanceMeters |
فقط خروجی. فاصله پیادهروی از این مکان دیدنی تا مقصد به متر. |
فیلد اتحادیه landmark. نشانگر مکانی. landmark فقط میتواند یکی از موارد زیر باشد: |
|
place |
مکانی که این مکان دیدنی را نشان میدهد. |
Landmark.Tag
فهرست همه برچسبهای ممکن که نحوه استفاده از مکان دیدنی را در بافت مقصد توصیف میکند.
اگر نشانی هم برچسب ADDRESS و هم برچسب ARRIVAL را داشته باشد، یعنی نشانگر مکانی هم در سطح محلی برجسته است و هم به مقصد نزدیک است.
| شمارشیها | |
|---|---|
TAG_UNSPECIFIED |
استفادهنشده. |
ADDRESS |
مکان برجسته محلی که میتواند برای شناسایی مکان کلی مقصد استفاده شود. معمولاً در چند صد متری مقصد. اینها شبیه به نشانهای بازگرداندهشده توسط ویژگی «توصیفکنندههای نشانی» در Geocoding API هستند: https://developers.google.com/maps/documentation/geocoding/address-descriptors/requests-address-descriptors. |
ARRIVAL |
مکانی که میتواند برای کمک به رسیدن به مقصد استفاده شود. وقتی به مقصد نزدیک هستید، برای ناوبری مفید است. برای مثال، این مکان شاخص ممکن است جایی باشد که در آنطرف خیابان مقصد قرار دارد. نشانگر مکانی با این برچسب معمولاً به مقصد نزدیکتر از نشانگرهای مکانی با برچسب ADDRESS است. |
ورودی
ورودی یک جفت مختصات عرض/طول جغرافیایی است که مکان نقطه ورود و خروج یک مکان را تعریف میکند.
| نمایش JSON |
|---|
{ "location": { object ( |
| فیلدها | |
|---|---|
location |
مکان ورودی. |
tags[] |
فهرستی از برچسبهایی که ورودی را توصیف میکنند. |
place |
ساختمانی که این ورودی بهصورت فیزیکی در آن قرار دارد، در قالب |
streetViewThumbnail |
تصویر ریزعکس «نمای خیابان» که ورودی را نشان میدهد. تصویر را میتوان از Street View Static API درخواست کرد. https://developers.google.com/maps/documentation/streetview/request-streetview را ببینید. |
streetViewAnnotation |
حاشیهنویسی ورودی در |
Entrance.Tag
مشخصاتی که ورودی را توصیف میکند.
| شمارشیها | |
|---|---|
TAG_UNSPECIFIED |
استفاده نمیشود. |
PREFERRED |
ورودی احتمالاً دسترسی فیزیکی به مکان اصلی در مقصد برگشتی را فراهم میکند. یک مکان میتواند چندین ورودی ترجیحی داشته باشد. اگر ورودی این برچسب را نداشته باشد، یعنی ورودی ازنظر فیزیکی در همان ساختمان مکان اصلی قرار دارد، اما لزوماً دسترسی به مکان را فراهم نمیکند. برای مثال، اگر مکان اصلی رستورانی در مرکز خریدی ردیفی باشد، ورودیهای «ترجیحی» ورودیهایی خواهند بود که احتمالاً به خود رستوران منتهی میشوند، درحالیکه ورودیهای برگشتی دیگر ورودیهای دیگر ساختمان، مثل ورودیهای دیگر رستورانهای مرکز خرید ردیفی، خواهند بود. اگر مکان اصلی خود ساختمان باشد، ورودیهای توجه: ورودی |
StreetViewThumbnail
پارامترهای نمایش ریزعکس «نمای خیابان Google». از این پارامترها میتوان برای درخواست تصویر نمای خیابان از «میانای برنامهسازی کاربردی ایستا برای نمای خیابان» استفاده کرد. https://developers.google.com/maps/documentation/streetview/request-streetview را ببینید.
| نمایش JSON |
|---|
{ "pano": string, "widthPx": integer, "heightPx": integer, "headingDegree": number, "pitchDegree": number, "fovDegree": number } |
| فیلدها | |
|---|---|
pano |
شناسه تمامنمای خاص. |
widthPx |
عرض تصویر ریزعکس برونداد به پیکسل. توجه: هنگام درخواست حاشیهنویسی در کنار ریزعکس، این مقادیر ارتفاع و عرض باید در درخواست Street View API استفاده شوند تا اطمینان حاصل شود که مختصات حاشیهنویسی بهدرستی با تصویر همتراز شدهاند. |
heightPx |
ارتفاع تصویر ریزعکس برونداد به پیکسل. توجه: هنگام درخواست کردن گلچینها در کنار ریزعکس، باید از این مقادیر ارتفاع و عرض در درخواست «میانای برنامهسازی کاربردی Street View» استفاده شود تا مختصات گلچین بهدرستی با تصویر تراز شود. |
headingDegree |
جهت افقی دوربین برحسب درجه. محدوده [۰، ۳۶۰). عدد ۰ نشاندهنده شمال و عدد ۹۰ نشاندهنده شرق است. |
pitchDegree |
جهت عمودی دوربین به درجه. محدوده [۹۰-، ۹۰]. ۰ افق است، +۹۰ مستقیماً بالا است، -۹۰ مستقیماً پایین است. |
fovDegree |
«میدان دید افقی» برحسب درجه. محدوده (0، 180]. سطح بزرگنمایی را کنترل میکند. «زاویه دید» کوچکتر به معنی زوم بیشتر است. |
ImageAnnotation
یک گلچین روی ریزعکس تصویر، مانند چندضلعی که ورودی را مشخص میکند.
| نمایش JSON |
|---|
{
"coordinates": [
{
object ( |
| فیلدها | |
|---|---|
coordinates[] |
فهرستی از مختصات که چندضلعی را روی تصویر تشکیل میدهند. مختصاتها بهصورت پادساعتگرد مرتب شدهاند. |
ImageAnnotation.Coordinate
مختصات پیکسل نقطهای روی تصویر. مبدأ (۰،۰) گوشه بالا سمت راست پیکسل بالا سمت راست تصویر است، با محور x که به سمت راست و محور y که به سمت پایین اشاره میکند.
| نمایش JSON |
|---|
{ "xPx": number, "yPx": number } |
| فیلدها | |
|---|---|
xPx |
مختصات X. |
yPx |
مختصات Y. |
Destination.ParkingOptions
اطلاعات مربوط به گزینههای پارکینگ برای مقصد.
| نمایش JSON |
|---|
{
"availability": enum ( |
| فیلدها | |
|---|---|
availability |
دردسترس بودن پارکینگ برای این مقصد. |
onsiteParking |
در مقصد پارکینگ درمحل وجود دارد. |
freeParkingLot |
پارکینگ سرباز رایگان دارد. |
paidParkingLot |
پارکینگ سرباز پولی ارائه میدهد. |
freeStreetParking |
پارکینگ رایگان کنار خیابان ارائه میدهد. |
paidStreetParking |
پارکینگ پولی کنار خیابان ارائه میدهد. |
valetParking |
پارکینگ با پیشکار ارائه میدهد. |
freeGarageParking |
پارکینگ رایگان در گاراژ ارائه میدهد. |
paidGarageParking |
پارکینگ پولی در گاراژ ارائه میدهد. |
Destination.ParkingOptions.Availability
معیاری تجمیعی از میزان دشواری پیدا کردن جای پارک هنگام بازدید از این مکان.
ممکن است مقادیر جدیدی در آینده اضافه شود.
| شمارشیها | |
|---|---|
AVAILABILITY_UNSPECIFIED |
دردسترس بودن پارکینگ دردسترس نیست. |
PLENTY |
جای پارک زیادی دردسترس است. |
SOMEWHAT_DIFFICULT |
پیدا کردن جای پارک تاحدی سخت است. |
DIFFICULT |
پیدا کردن جای پارک بسیار سخت است. |
Destination.ArrivalSummary
خلاصه تولیدشده با هوش مصنوعی از تجربه ورود به مقصد.
| نمایش JSON |
|---|
{ "text": { object ( |
| فیلدها | |
|---|---|
text |
خلاصه تجربه ورود به مقصد. |
flagContentUrl |
پیوندی که کاربران میتوانند ازطریق آن مشکلی را در خلاصه پرچمگذاری کنند. |
disclosureText |
فقط خروجی. حاوی نوشتار شفافسازی برای خلاصه ورود است. |