Method: geocode.destinations.searchDestinations

این متد جستجوی مقصد را انجام می‌دهد و لیستی از مقصدها را برمی‌گرداند.

درخواست HTTP

POST https://geocode.googleapis.com/v4alpha/geocode/destinations

این URL از سینتکس Transcoding در gRPC استفاده می‌کند.

درخواست بدنه

بدنه درخواست شامل داده‌هایی با ساختار زیر است:

نمایش JSON 
{
  "travelModes": [
    enum (NavigationPoint.TravelMode)
  ],
  "languageCode": string,
  "regionCode": string,

  // Union field primary_query can be only one of the following:
  "place": string,
  "addressQuery": {
    object (SearchDestinationsRequest.AddressQuery)
  },
  "locationQuery": {
    object (SearchDestinationsRequest.LocationQuery)
  }
  // End of list of possible types for union field primary_query.
}
فیلدها
travelModes[]

enum ( NavigationPoint.TravelMode )

اختیاری. حالت‌های سفر برای فیلتر کردن نقاط ناوبری. این بر فیلد navigationPoints که در پاسخ برگردانده می‌شود تأثیر می‌گذارد. اگر خالی باشد، نقاط ناوبری همه حالت‌های سفر می‌توانند برگردانده شوند.

languageCode

string

اختیاری. زبانی که نتایج باید با آن برگردانده شوند.

regionCode

string

اختیاری. کد منطقه. کد منطقه، که به عنوان یک مقدار دو کاراکتری ccTLD ("دامنه سطح بالا") مشخص شده است. این پارامتر بر اساس قانون مربوطه بر نتایج تأثیر می‌گذارد. این پارامتر همچنین بر نتایج حاصل از سرویس تأثیر می‌گذارد، اما آنها را به طور کامل محدود نمی‌کند.

فیلد primary_query نوع Union. درخواست برای مقصد اصلی. این می‌تواند یک مکان، یک آدرس کاملاً مشخص یا یک مکان LatLng باشد. برخی از مکان‌ها و آدرس‌ها با حداقل اطلاعات، قابل تبدیل به مقصد نیستند.

مقصدها حول پرس‌وجوی اصلی مشخص‌شده ساخته می‌شوند.

توجه: فقط مکان‌ها و آدرس‌هایی که می‌توانند مقصد ناوبری داشته باشند پشتیبانی می‌شوند. به عنوان مثال، مکانی که نشان دهنده یک خانه یا یک مجتمع آپارتمانی است می‌تواند به عنوان پرس و جوی اصلی استفاده شود، اما مکان‌هایی که نشان دهنده یک منطقه یا یک منطقه اداری هستند نمی‌توانند به عنوان پرس و جوی اصلی استفاده شوند. primary_query فقط می‌تواند یکی از موارد زیر باشد:

place

string

نام منبع یک مکان، با فرمت places/{placeId} .

addressQuery

object ( SearchDestinationsRequest.AddressQuery )

آدرس خیابان.

locationQuery

object ( SearchDestinationsRequest.LocationQuery )

یک مکان دقیق.

بدنه پاسخ

پیام پاسخ برای DestinationService.SearchDestinations.

در صورت موفقیت، بدنه پاسخ شامل داده‌هایی با ساختار زیر است:

نمایش JSON 
{
  "destinations": [
    {
      object (Destination)
    }
  ]
}
فیلدها
destinations[]

object ( Destination )

فهرستی از مقاصد.

اگر بتوان مقصد اصلی را به طور واضح از پرس‌وجوی اصلی شناسایی کرد، این سرویس یک نتیجه را برمی‌گرداند. در غیر این صورت، این سرویس ممکن است چندین نتیجه برای رفع ابهام یا هیچ نتیجه‌ای را برنگرداند.

دامنه‌های مجوز

به یکی از حوزه‌های OAuth زیر نیاز دارد:

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/maps-platform.geocode

جستجوی مقصدهادرخواست.پرسش آدرس

آدرس خیابانی که می‌خواهید جستجو کنید. آدرس‌ها را مطابق با قالب مورد استفاده توسط سرویس پستی ملی کشور مربوطه مشخص کنید.

نمایش JSON 
{

  // Union field kind can be only one of the following:
  "address": {
    object (PostalAddress)
  },
  "addressQuery": string
  // End of list of possible types for union field kind.
}
فیلدها
فیلد Union kind . kind پرس و جوی آدرس فقط می‌تواند یکی از موارد زیر باشد:
address

object ( PostalAddress )

آدرس خیابان در قالب آدرس پستی.

addressQuery

string

آدرس خیابان که به صورت تک خطی قالب‌بندی شده است.

جستجوی مقصدهادرخواست.جستجوی موقعیت مکانی

یک درخواست موقعیت مکانی برای شناسایی یک مقصد اصلی نزدیک.

نکته: اگر درخواست موقعیت مکانی در داخل ساختمانی باشد که شامل ساختمان‌های فرعی است، ممکن است مکان اصلی برگردانده شده یک ساختمان فرعی باشد. در این موارد، فیلد containingPlaces شامل ساختمان نیز خواهد بود.

نمایش JSON 
{
  "placeFilter": {
    object (SearchDestinationsRequest.LocationQuery.PlaceFilter)
  },

  // Union field kind can be only one of the following:
  "location": {
    object (LatLng)
  }
  // End of list of possible types for union field kind.
}
فیلدها
placeFilter

object ( SearchDestinationsRequest.LocationQuery.PlaceFilter )

اختیاری. فیلترهایی که برای کاندیداهای مقصد اعمال می‌شوند.

kind فیلد Union. kind پرس و جوی مکان فقط می‌تواند یکی از موارد زیر باشد:
location

object ( LatLng )

یک مکان دقیق LatLng.

درخواست جستجوی مقصد.جستجوی موقعیت مکانی.فیلتر مکان

فیلترهایی که باید برای کاندیداهای مقصد اعمال شوند.

نمایش JSON 
{
  "structureType": enum (PlaceView.StructureType),
  "addressability": enum (SearchDestinationsRequest.LocationQuery.PlaceFilter.Addressability)
}
فیلدها
structureType

enum ( PlaceView.StructureType )

اختیاری. در صورت مشخص شدن، تضمین می‌شود که همه مقصدها با این نوع ساختار، یک مکان اصلی داشته باشند. این می‌تواند منجر به فیلتر کردن برخی از مقصدها یا درشت/اصلاح کردن مقصدهای برگشتی شود.

برای مثال، اگر GROUNDS مشخص شده باشد، تمام مقصدهای برگشتی یک مکان اصلی با نوع ساختار GROUNDS خواهند داشت. این می‌تواند منجر به فیلتر کردن برخی از مقصدهایی شود که بخشی از یک grounds نیستند، یا منجر به کاهش تعداد مقصدهای برگشتی به سطح grounds شود.

یکی دیگر از کاربردهای این فیلد، استخراج آسان‌تر چندضلعی‌های نمایش ساختمان است. برای مثال، اگر BUILDING مشخص شده باشد، چندضلعی نمایش مکان اصلی، ساختمان واقع در مکان مشخص شده خواهد بود.

addressability

enum ( SearchDestinationsRequest.LocationQuery.PlaceFilter.Addressability )

اختیاری. در صورت مشخص شدن، فقط مقصدهایی را برمی‌گرداند که معیارهای آدرس‌پذیری مربوطه را برآورده می‌کنند.

نوع ساختار PlaceView

نوع ساختاری که این مکان نشان می‌دهد.

انوم‌ها
STRUCTURE_TYPE_UNSPECIFIED استفاده نشده.
POINT یک موقعیت نقطه‌ای.
SECTION بخشی فرعی از یک ساختمان.
BUILDING یک ساختمان.
GROUNDS یک منطقه بزرگ که معمولاً شامل چندین ساختمان است، مانند یک دانشگاه، یک مجتمع آپارتمانی یا یک مرکز خرید.

جستجوی مقصدهادرخواست.جستجوی موقعیت مکانی.فیلتر مکان.آدرس پذیری

گزینه‌هایی برای فیلتر کردن آدرس‌پذیری تعریف می‌کند. مقادیر جدید ممکن است در آینده اضافه شوند.

انوم‌ها
ADDRESSABILITY_UNSPECIFIED وقتی مشخص نشده باشد، سرویس یک پیش‌فرض معقول را انتخاب می‌کند.
ANY آدرس‌پذیری معیار فیلترینگ نیست. مقصدها صرف نظر از آدرس‌پذیری‌شان برگردانده می‌شوند.
PRIMARY تمام مقاصد برگردانده شده دارای یک مکان اصلی با آدرس یا نام در سطح خیابان خواهند بود.
WEAK تمام مقصدهای برگردانده شده یا یک مکان اصلی یا یک مقصد فرعی با آدرس یا نام خیابان خواهند داشت.

مقصد

یک مقصد. این شامل مکان اصلی، مکان‌های مرتبط، ورودی‌ها و نقاط ناوبری می‌شود.

نمایش JSON 
{
  "primary": {
    object (PlaceView)
  },
  "containingPlaces": [
    {
      object (PlaceView)
    }
  ],
  "subDestinations": [
    {
      object (PlaceView)
    }
  ],
  "landmarks": [
    {
      object (Landmark)
    }
  ],
  "entrances": [
    {
      object (Entrance)
    }
  ],
  "navigationPoints": [
    {
      object (NavigationPoint)
    }
  ],
  "arrivalSummary": {
    object (Destination.ArrivalSummary)
  }
}
فیلدها
primary

object ( PlaceView )

مکان اصلی که توسط primary_query در درخواست مشخص شده است.

containingPlaces[]

object ( PlaceView )

مکان‌های کم‌اهمیت‌تری که مکان اصلی در آن‌ها قرار دارد. برای مثال، مجتمع آپارتمانی که این ساختمان را در بر می‌گیرد.

subDestinations[]

object ( PlaceView )

زیرمقصدهای دقیق‌تر مکان اصلی. برای مثال، واحدهای موجود در یک ساختمان.

نکته: در مقایسه با SubDestination که توسط Places API برگردانده می‌شود، این لیست از زیرمقصدها جامع‌تر است و هر زیرمقصد شامل اطلاعات بیشتری است.

landmarks[]

object ( Landmark )

نشانه‌هایی که می‌توانند برای اطلاع‌رسانی در مورد محل مقصد یا کمک به رسیدن به مقصد استفاده شوند.

entrances[]

object ( Entrance )

ورودی‌های این مقصد.

navigationPoints[]

object ( NavigationPoint )

نقاط ناوبری برای این مقصد.

arrivalSummary

object ( Destination.ArrivalSummary )

خلاصه‌ای از تجربه ورود به مقصد که توسط هوش مصنوعی تولید شده است.

نمای مکان

نمایی از یک مکان را در API مکان‌ها نشان می‌دهد. همچنین اطلاعات اضافی مخصوص مقصدها، مانند نوع ساختار و چندضلعی نمایش را ارائه می‌دهد.

در برخی موارد، یک PlaceView با شناسه مکان یکسان ممکن است با آنچه توسط Places API برای فیلدهای types و displayName برگردانده می‌شود، متفاوت باشد.

نمایش JSON 
{
  "place": string,
  "displayName": {
    object (LocalizedText)
  },
  "primaryType": string,
  "types": [
    string
  ],
  "formattedAddress": string,
  "postalAddress": {
    object (PostalAddress)
  },
  "structureType": enum (PlaceView.StructureType),
  "location": {
    object (LatLng)
  },
  "displayPolygon": {
    object
  }
}
فیلدها
place

string

نام منبع این مکان، با فرمت places/{placeId} .

displayName

object ( LocalizedText )

توضیحات مکان قابل خواندن توسط انسان. به عنوان مثال، "دروازه B"، "مک دونالد"

primaryType

string

نوع مکان اصلی این مکان. برای مشاهده لیست مقادیر ممکن به https://developers.google.com/maps/documentation/places/web-service/place-types مراجعه کنید.

توجه: این فیلد همیشه پر نمی‌شود. در چنین شرایطی آماده باشید که از فیلد types استفاده کنید.

types[]

string

همه انواع مکان‌های مرتبط با این مکان. برای مشاهده فهرست مقادیر ممکن به https://developers.google.com/maps/documentation/places/web-service/place-types مراجعه کنید.

formattedAddress

string

آدرس تک خطی.

postalAddress

object ( PostalAddress )

آدرس ساختار یافته

structureType

enum ( PlaceView.StructureType )

نوع سازه مربوط به این مکان.

location

object ( LatLng )

موقعیت مکانی این مکان. برای مکان‌هایی که چندضلعی‌های نمایشی دارند، این می‌تواند نقطه خوبی برای قرار دادن نشانگر روی نقشه باشد.

displayPolygon

object ( Struct format)

طرح کلی چندضلعی مکان در قالب GeoJSON، با استفاده از قالب RFC 7946: https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.6 .

نکته: فرمت RFC 7946 از MultiPolygons پشتیبانی می‌کند، بنابراین یک شیء displayPolygon می‌تواند چندین چندضلعی را نمایش دهد.

نقطه عطف

از نشانه‌های جغرافیایی برای اطلاع‌رسانی در مورد محل مقصد یا کمک به رسیدن به مقصد استفاده می‌شود.

نمایش JSON 
{
  "relationalDescription": {
    object (LocalizedText)
  },
  "tags": [
    enum (Landmark.Tag)
  ],
  "straightLineDistanceMeters": number,
  "travelDistanceMeters": number,

  // Union field landmark can be only one of the following:
  "place": {
    object (PlaceView)
  }
  // End of list of possible types for union field landmark.
}
فیلدها
relationalDescription

object ( LocalizedText )

توضیحی خوانا برای انسان از چگونگی ارتباط مقصد با مکان دیدنی. برای مثال: «نزدیک ساختمان امپایر استیت» یا «روبروی کاخ سفید».

tags[]

enum ( Landmark.Tag )

برچسب‌هایی که نحوه استفاده از آن بنای تاریخی را در متن مقصد توصیف می‌کنند.

straightLineDistanceMeters

number

فقط خروجی. فاصله مستقیم از این نقطه عطف تا مقصد بر حسب متر.

travelDistanceMeters

number

فقط خروجی. فاصله شبکه جاده‌ای از این نقطه عطف تا مقصد بر حسب متر.

landmark میدان یونیون. علامت مشخصه. landmark می‌تواند فقط یکی از موارد زیر باشد:
place

object ( PlaceView )

مکانی که نمایانگر این بنای تاریخی است.

برچسب برجسته

فهرست تمام برچسب‌های ممکن که نحوهٔ استفاده از یک نشان تاریخی را در متن یک مقصد توصیف می‌کنند.

اگر آدرسی هم برچسب ADDRESS و هم ARRIVAL داشته باشد، به این معنی است که آن مکان هم از نظر محلی برجسته است و هم به مقصد نزدیک.

انوم‌ها
TAG_UNSPECIFIED استفاده نشده.
ADDRESS یک مکان برجسته محلی که می‌تواند برای شناسایی موقعیت کلی مقصد استفاده شود. معمولاً در فاصله چند صد متری از مقصد. این مکان‌ها مشابه نشانه‌هایی هستند که توسط ویژگی Address Descriptors از Geocoding API برگردانده می‌شوند: https://developers.google.com/maps/documentation/geocoding/address-descriptors/requests-address-descriptors .
ARRIVAL مکانی که می‌تواند برای کمک به رسیدن به مقصد استفاده شود. برای ناوبری زمانی که به مقصد نزدیک هستید مفید است. برای مثال، این مکان دیدنی ممکن است مکانی باشد که در آن سوی خیابان از مقصد قرار دارد. یک مکان دیدنی با این برچسب معمولاً به مقصد نزدیک‌تر از مکان‌های دیدنی با برچسب ADDRESS است.

ورودی

ورودی یک جفت مختصات طول و عرض جغرافیایی است که موقعیت نقطه ورود و خروج یک مکان را مشخص می‌کند.

نمایش JSON 
{
  "location": {
    object (LatLng)
  },
  "tags": [
    enum (Entrance.Tag)
  ],
  "place": string
}
فیلدها
location

object ( LatLng )

محل قرارگیری ورودی.

tags[]

enum ( Entrance.Tag )

فهرستی از برچسب‌ها که ورودی را توصیف می‌کنند.

place

string

ساختاری که این ورودی به صورت فیزیکی روی آن قرار دارد، با فرمت places/{placeId} .

برچسب ورودی

ویژگی‌هایی که یک ورودی را توصیف می‌کنند.

انوم‌ها
TAG_UNSPECIFIED استفاده نشده.
PREFERRED

احتمالاً ورودی، دسترسی فیزیکی به مکان اصلی در مقصد بازگردانده شده را فراهم می‌کند. یک مکان می‌تواند چندین ورودی ترجیحی داشته باشد. اگر ورودی این برچسب را نداشته باشد، به این معنی است که ورودی از نظر فیزیکی در همان ساختمان مکان اصلی قرار دارد، اما لزوماً دسترسی به آن مکان را فراهم نمی‌کند.

برای مثال، اگر مکان اصلی یک رستوران در یک مرکز خرید باشد، ورودی‌های «ترجیحی» ورودی‌هایی خواهند بود که احتمالاً به خود رستوران منتهی می‌شوند، در حالی که سایر ورودی‌های برگشتی، ورودی‌های دیگری برای ساختمان، مانند ورودی‌های رستوران‌های دیگر در مرکز خرید، خواهند بود.

اگر مکان اصلی خود یک ساختمان باشد، ورودی‌های PREFERRED ورودی‌هایی خواهند بود که به قسمت «اصلی» ساختمان منتهی می‌شوند. برای مثال، در یک مرکز خرید، ورودی‌های PREFERRED ، ورودی‌هایی هستند که امکان دسترسی به فضای اصلی سرسرا را فراهم می‌کنند، اما اگر یک ورودی فقط دسترسی به یک فروشگاه در کنار ساختمان را فراهم کند، ورودی PREFERRED نخواهد بود.

توجه: یک ورودی PREFERRED ممکن است دسترسی به مکان اصلی را فراهم نکند و یک ورودی غیر PREFERRED ممکن است دسترسی به مکان اصلی را فراهم کند.

خلاصه مقصد.ورود

خلاصه‌ای از تجربه ورود به مقصد که توسط هوش مصنوعی تولید شده است.

نمایش JSON 
{
  "text": {
    object (LocalizedText)
  },
  "flagContentUrl": string,
  "disclosureText": {
    object (LocalizedText)
  }
}
فیلدها
text

object ( LocalizedText )

خلاصه‌ای از تجربه ورود به مقصد.

flagContentUrl

string

پیوندی که کاربران می‌توانند در آن مشکل خلاصه را علامت‌گذاری کنند.

disclosureText

object ( LocalizedText )

فقط خروجی. شامل متن افشا برای خلاصه ورود است.