- درخواست اچتیتیپی
- بدنه درخواست
- متن پاسخ
- گسترههای مجوز
- 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.ParkingOptions.ParkingFacility
- Destination.ArrivalSummary
این روش جستجوی مقصد را انجام میدهد و فهرستی از مقصدها را برمیگرداند.
درخواست HTTP
POST https://geocode.googleapis.com/v4alpha/geocode/destinations
نشانی وب از نحو تراتبدیل gRPC استفاده میکند.
متن درخواست
بدنه درخواست حاوی دادههایی با ساختار زیر است:
| نمایش JSON |
|---|
{ "travelModes": [ enum ( |
| فیلدها | |
|---|---|
travelModes[] |
اختیاری. حالتهای سفر برای فیلتر کردن نقاط پیمایش. این بر فیلد |
languageCode |
اختیاری. زبان نتایجی که باید برگردانده شود. |
regionCode |
اختیاری. کد منطقه. کد منطقه، که بهعنوان مقدار دو نویسهای ccTLD («دامنه سطح بالا») مشخص شده است. این پارامتر براساس قانون ذیربط بر نتایج تأثیر میگذارد. این پارامتر همچنین بر نتایج سرویس تأثیر میگذارد، اما آنها را کاملاً محدود نمیکند. |
پرسمان برای مقصد اصلی. این میتواند یک مکان، یک نشانی کاملاً مشخص، یا یک مکان LatLng باشد. برخیاز مکانها و نشانیها با اطلاعات حداقلی نمیتوانند به مقصد تبدیل شوند. مقصدها براساس پُرسمان اصلی مشخصشده ساخته میشوند. توجه: فقط مکانها و نشانیهایی که میتوانند مقصد ناوبری داشته باشند پشتیبانی میشوند. برای مثال، مکانی که نشاندهنده خانه یا مجتمع آپارتمانی است میتواند بهعنوان پُرسمان اصلی استفاده شود، اما مکانهایی که نشاندهنده محل یا تقسیمات کشوری هستند نمیتوانند بهعنوان پُرسمان اصلی استفاده شوند. در زیر فهرستی از فیلدهای متقابلاً انحصاری آمده است. حداکثر یکی از فیلدها در پاسخ تنظیم خواهد شد: |
|
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 |
|---|
{
// The following is a list of mutually exclusive fields. At most one of the
// fields will be set in a response:
"address": {
object ( |
| فیلدها | |
|---|---|
| پُرسمان نشانی. در زیر فهرستی از فیلدهای متقابلاً انحصاری آمده است. حداکثر یکی از فیلدها در پاسخ تنظیم خواهد شد: | |
address |
نشانی خیابان در قالب نشانی پستی. |
addressQuery |
نشانی خیابان که بهصورت یک خط قالببندی شده است. |
| پایان فیلدهای متقابلاً انحصاری. | |
SearchDestinationsRequest.LocationQuery
پُرسمان مکان برای شناسایی مقصد اصلی در اطراف.
توجه: اگر پُرسمان مکان در ساختمانی باشد که دارای زیرمکان است، ممکن است مکان اصلی برگرداندهشده یک زیرمکان باشد. در این موارد، فیلد containingPlaces شامل ساختمان خواهد بود.
| نمایش JSON |
|---|
{ "placeFilter": { object ( |
| فیلدها | |
|---|---|
placeFilter |
اختیاری. فیلترهایی که باید برای مقصدهای احتمالی اعمال شود. |
| پُرسمان مکان. در زیر فهرستی از فیلدهای متقابلاً انحصاری آمده است. حداکثر یکی از فیلدها در پاسخ تنظیم خواهد شد: | |
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, "placeId": string, "displayName": { object ( |
| فیلدها | |
|---|---|
place |
نام منبع این «مکان»، در قالب |
placeId |
شناسه یکتای مکان. |
displayName |
شرح مکان قابلخواندن برای انسان. برای مثال، «دروازه ب»، «مکدونالد» |
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[] |
آرایهای که نوع(انواع) مؤلفه نشانی را نشان میدهد. این مقادیر از جدول انواع نشانی و انواع مؤلفه نشانی که Places API از آن استفاده میکند گرفته شده است: https://developers.google.com/maps/documentation/places/web-service/place-types#address-types |
languageCode |
زبانی که برای قالببندی این مؤلفه استفاده میشود، در نماد CLDR. |
نشانگر مکانی
از نشانگرهای مکانی برای اطلاعرسانی درباره محل مقصد یا کمک به رسیدن به مقصد استفاده میشود.
| نمایش JSON |
|---|
{ "relationalDescription": { object ( |
| فیلدها | |
|---|---|
relationalDescription |
شرحی قابلخواندن برای انسان درباره اینکه مقصد چه ارتباطی با نشانگر مکانی دارد. برای مثال: «نزدیک امپایر استیت» یا «روبهروی کاخ سفید». |
tags[] |
برچسبهایی که نحوه استفاده از مکان دیدنی را در بافت مقصد توصیف میکنند. |
straightLineDistanceMeters |
فقط خروجی. فاصله مستقیم از این مکان دیدنی تا مقصد به متر. |
travelDistanceMeters |
فقط خروجی. فاصله پیادهروی از این مکان دیدنی تا مقصد به متر. |
| نشانگر مکانی. در زیر فهرستی از فیلدهای متقابلاً انحصاری آمده است. حداکثر یکی از فیلدها در پاسخ تنظیم خواهد شد: | |
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 |
|---|
{ "displayName": { object ( |
| فیلدها | |
|---|---|
displayName |
نام قابلخواندن برای انسان، مثلاً «دروازه ب»، «ورودی جنوبی»، «ورودی خیابان پنجم». |
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». از این پارامترها میتوان برای درخواست تصویر نمای خیابان از Street View Static API استفاده کرد. 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 API استفاده شوند تا اطمینان حاصل شود که مختصات حاشیهنویسی بهدرستی با تصویر همتراز شدهاند. |
headingDegree |
جهت افقی دوربین برحسب درجه. محدوده [۰، ۳۶۰). عدد ۰ نشاندهنده شمال و عدد ۹۰ نشاندهنده شرق است. |
pitchDegree |
جهت عمودی دوربین به درجه. محدوده [۹۰-، ۹۰]. ۰ افق است، +۹۰ مستقیماً بالا است، -۹۰ مستقیماً پایین است. |
fovDegree |
میدان دید افقی برحسب درجه. محدوده (0، 180]. سطح بزرگنمایی را کنترل میکند. میدان دید کوچکتر بهمعنای بزرگنمایی بیشتر است. |
ImageAnnotation
حاشیهنویسی روی ریزعکس تصویر، مثل چندضلعیای که ورودی را مشخص میکند.
| نمایش JSON |
|---|
{
"coordinates": [
{
object ( |
| فیلدها | |
|---|---|
coordinates[] |
فهرستی از مختصات که چندضلعی را روی تصویر تشکیل میدهند. مختصاتها بهصورت پادساعتگرد مرتب شدهاند. |
ImageAnnotation.Coordinate
مختصات پیکسل نقطهای روی تصویر. مبدأ (0,0) گوشه بالا سمت چپ پیکسل بالا سمت چپ تصویر است، که محور x به سمت راست و محور y به سمت پایین اشاره میکند.
| نمایش JSON |
|---|
{ "xPx": number, "yPx": number } |
| فیلدها | |
|---|---|
xPx |
مختصات X. |
yPx |
مختصات Y. |
Destination.ParkingOptions
اطلاعات مربوط به گزینههای پارکینگ برای مقصد.
| نمایش JSON |
|---|
{ "availability": enum ( |
| فیلدها | |
|---|---|
availability |
دردسترس بودن پارکینگ برای این مقصد. |
parkingFacilities[] |
تسهیلات پارکینگ برای این مقصد. |
onsiteParking |
پارکینگ درمحل در مقصد وجود دارد. |
freeParkingLot |
پارکینگ سرباز رایگان ارائه میدهد. |
paidParkingLot |
پارکینگ سرباز پولی ارائه میدهد. |
freeStreetParking |
پارکینگ رایگان کنار خیابان ارائه میدهد. |
paidStreetParking |
پارکینگ پولی کنار خیابان ارائه میدهد. |
valetParking |
سرویس پارکینگ با پیشکار ارائه میدهد. |
freeGarageParking |
پارکینگ رایگان در گاراژ ارائه میدهد. |
paidGarageParking |
پارکینگ پولی در گاراژ ارائه میدهد. |
Destination.ParkingOptions.Availability
معیاری انبوهشی از میزان دشواری پیدا کردن پارکینگ هنگام بازدید از این مکان.
ممکن است در آینده مقادیر جدیدی اضافه شود.
| شمارشیها | |
|---|---|
AVAILABILITY_UNSPECIFIED |
دردسترس بودن پارکینگ دردسترس نیست. |
PLENTY |
جای پارک زیادی دردسترس است. |
SOMEWHAT_DIFFICULT |
پیدا کردن جای پارک تاحدی سخت است. |
DIFFICULT |
پیدا کردن جای پارک بسیار سخت است. |
Destination.ParkingOptions.ParkingFacility
یک گزینه پارکینگ مجزا و مشخص (مثلاً یک پارکینگ یا گاراژ خاص) که با مقصد مرتبط است. این پیام اطلاعات دقیقی درباره یک پارکینگ خاص ارائه میدهد، درحالیکه پیام اصلی ParkingOptions خلاصهای تجمیعی از همه پارکینگهای دردسترس ارائه میدهد.
| نمایش JSON |
|---|
{
"place": {
object ( |
| فیلدها | |
|---|---|
place |
نمایش مکان این پارکینگ خاص. |
onsite |
اینکه این پارکینگ در محل مقصد اصلی واقع شده است یا نه. اگر این فیلد تنظیم نشده باشد، وضعیت در محل نامشخص است. |
popular |
اینکه آیا این پارکینگ انتخاب پرطرفداری برای بازدیدکنندگانی است که به مقصد اصلی سفر میکنند یا نه. اگر این فیلد تنظیم نشده باشد، وضعیت محبوبیت نامشخص است. |
straightLineDistanceMeters |
فاصله خط مستقیم برحسب متر از مقصد اصلی تا این پارکینگ. |
Destination.ArrivalSummary
خلاصه تولیدشده با هوش مصنوعی از تجربه ورود به مقصد.
| نمایش JSON |
|---|
{ "text": { object ( |
| فیلدها | |
|---|---|
text |
خلاصه تجربه ورود به مقصد. |
flagContentUrl |
پیوندی که کاربران میتوانند ازطریق آن مشکلات خلاصه را پرچمگذاری کنند. |
disclosureText |
فقط خروجی. حاوی نوشتار شفافسازی برای خلاصه ورود است. |