پاسخ مسیر را مرور کنید

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

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

برای لیست کامل گزینه‌های ورودی، به گزینه‌های مسیر موجود و بدنه درخواست مراجعه کنید.

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

درباره ماسک‌های صحرایی

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

مثال‌های این سند کل شیء پاسخ را بدون در نظر گرفتن ماسک‌های فیلد نشان می‌دهند. در یک محیط عملیاتی، پاسخ شما فقط شامل فیلدهایی خواهد بود که صریحاً در ماسک فیلد مشخص کرده‌اید.

برای اطلاعات بیشتر، به «انتخاب اطلاعاتی که باید برگردانده شود» مراجعه کنید.

درباره نمایش حق نشر

هنگام نمایش نتایج به کاربران، باید عبارت کپی‌رایت زیر را درج کنید:

Powered by Google, © YEAR Google

برای مثال:

Powered by Google, ©2023 Google

درباره مسیرها، پاها و گام‌ها

قبل از بررسی پاسخی که توسط API مسیرها برگردانده می‌شود، باید با اجزایی که یک مسیر را تشکیل می‌دهند، آشنا باشید:

پاسخ شما ممکن است حاوی اطلاعاتی در مورد هر یک از این اجزای مسیر باشد:

• مسیر : کل سفر از نقطه مسیر مبدا، از طریق هر نقطه مسیر میانی، تا نقطه مسیر مقصد. یک مسیر شامل یک یا چند مرحله است.

• مرحله (leg) : مسیر از یک نقطه مسیر در یک مسیر به نقطه مسیر بعدی در مسیر. هر مرحله از یک یا چند مرحله گسسته تشکیل شده است.

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

  این API برای یک نقطه‌ی بین‌راهی میانیِ عبوری، مسیری اضافه نمی‌کند. برای مثال، مسیری که شامل یک نقطه‌ی بین‌راهی مبدأ، یک نقطه‌ی بین‌راهی میانیِ عبوری و یک نقطه‌ی بین‌راهی مقصد است، هنگام عبور از نقطه‌ی بین‌راهی، فقط یک مسیر از مبدأ به مقصد دارد. برای اطلاعات بیشتر در مورد نقاط بین‌راهی عبوری، به بخش تعریف نقطه‌ی بین‌راهی عبوری مراجعه کنید.

• گام (Step) : یک دستورالعمل واحد در امتداد شاخه یک مسیر. گام، جزئی‌ترین واحد یک مسیر است. برای مثال، یک گام می‌تواند نشان دهد که «در خیابان اصلی به چپ بپیچید».

چه چیزی در پاسخ آمده است؟

شیء JSON که نشان‌دهنده‌ی پاسخ API است، شامل ویژگی‌های سطح بالای زیر است:

• routes ، آرایه‌ای از عناصر از نوع Route . آرایه routes شامل یک عنصر برای هر مسیری است که توسط API برگردانده می‌شود. این آرایه می‌تواند حداکثر شامل پنج عنصر باشد: مسیر پیش‌فرض، مسیر سازگار با محیط زیست و حداکثر سه مسیر جایگزین.

• geocodingResults ، آرایه‌ای از عناصر از نوع GeocodingResults . برای هر مکان در درخواست (مبدا، مقصد یا نقطه مسیر میانی) که به عنوان یک رشته آدرس یا به عنوان یک کد پلاس مشخص کرده‌اید، API جستجوی شناسه مکان را انجام می‌دهد. هر عنصر از این آرایه شامل شناسه مکان مربوط به یک مکان است. مکان‌های موجود در درخواست که به عنوان شناسه مکان یا به عنوان مختصات عرض/طول جغرافیایی مشخص شده‌اند، شامل نمی‌شوند. اگر همه مکان‌ها را با استفاده از شناسه‌های مکان یا مختصات عرض و طول جغرافیایی مشخص کرده‌اید، این آرایه ارائه نمی‌شود.

• fallbackInfo ، از نوع FallbackInfo . اگر API قادر به محاسبه مسیری از تمام ویژگی‌های ورودی نباشد، ممکن است به استفاده از روش محاسبه متفاوتی متوسل شود. هنگامی که از حالت fallback استفاده می‌شود، این فیلد حاوی اطلاعات دقیقی در مورد پاسخ fallback است. در غیر این صورت، این فیلد تنظیم نشده است.

پاسخ به این شکل است:

{
  // The routes array.
  "routes": [
    {
      object (Route)
    }
  ],
  // The place ID lookup results.
  "geocodingResults": [
    {
      object (GeocodedWaypoint)
    }
  ],
  // The fallback property.
  "fallbackInfo": {
    object (FallbackInfo)
  }
}

رمزگشایی آرایه مسیرها

پاسخ شامل آرایه routes است که در آن هر عنصر آرایه از نوع Route است. هر عنصر آرایه نشان دهنده یک مسیر کامل از مبدا به مقصد است. API همیشه حداقل یک مسیر را برمی‌گرداند که مسیر پیش‌فرض نامیده می‌شود.

شما می‌توانید مسیرهای اضافی درخواست کنید. اگر یک مسیر سازگار با محیط زیست درخواست کنید، آرایه می‌تواند شامل دو عنصر باشد: مسیر پیش‌فرض و مسیر سازگار با محیط زیست. یا می‌توانید computeAlternativeRoutes در درخواست روی true تنظیم کنید تا حداکثر سه مسیر جایگزین به پاسخ اضافه شود.

هر مسیر در آرایه با ویژگی آرایه routeLabels شناسایی می‌شود:

آرایه legs شامل تعریف هر بخش از مسیر است. ویژگی‌های باقی‌مانده، مانند distanceMeters ، duration و polyline, حاوی اطلاعاتی در مورد کل مسیر هستند:

{
  "routeLabels": [
    enum (RouteLabel)
  ],
  "legs": [
    {
      object (RouteLeg)
    }
  ],
  "distanceMeters": integer,
  "duration": string,
  "routeLabels": [string],
  "staticDuration": string,
  "polyline": {
    object (Polyline)
  },
  "description": string,
  "warnings": [
    string
  ],
  "viewport": {
    object (Viewport)
  },
  "travelAdvisory": {
    object (RouteTravelAdvisory)
  }
  "routeToken": string
}

به دلیل شرایط رانندگی فعلی و سایر عوامل، مسیر پیش‌فرض و مسیر سازگار با محیط زیست می‌توانند یکسان باشند. در این حالت، آرایه routeLabels شامل هر دو برچسب است: DEFAULT_ROUTE و FUEL_EFFICIENT .

{
  "routes": [
    {
      "routeLabels": [
        "DEFAULT_ROUTE",
        "FUEL_EFFICIENT"
      ],
     …
    }
  ]
}

آرایه پاها را درک کنید

هر route در پاسخ شامل یک آرایه legs است که در آن هر عنصر legs از نوع RouteLeg است. هر پا در آرایه، مسیر را از یک نقطه مسیر به نقطه مسیر بعدی در طول مسیر تعریف می‌کند. یک مسیر همیشه حداقل شامل یک پا است.

ویژگی legs شامل تعریف هر گام در امتداد پایه در آرایه steps است. ویژگی‌های باقی‌مانده، مانند distanceMeters ، duration و polyline حاوی اطلاعاتی در مورد پایه هستند.

{
  "distanceMeters": integer,
  "duration": string,
  "staticDuration": string,
  "polyline": {
    object (Polyline)
  },
  "startLocation": {
    object (Location)
  },
  "endLocation": {
    object (Location)
  },
  "steps": [
    {
      object (RouteLegStep)
    }
  ],
  "travelAdvisory": {
    object (RouteLegTravelAdvisory)
  }
}

آرایه مراحل (steps) را درک کنید

هر پا در پاسخ شامل یک آرایه steps است که در آن هر عنصر آرایه steps از نوع RouteLegStep است. یک step مربوط به یک دستورالعمل واحد در امتداد آن پا است. یک leg همیشه حداقل شامل یک step است.

هر عنصر در آرایه steps شامل ویژگی navigationInstruction از نوع NavigationInstruction است که شامل دستورالعمل مرحله است. برای مثال:

"navigationInstruction": {
  "maneuver": "TURN_LEFT",
  "instructions": "Turn left toward Frontage Rd"
}

instructions ممکن است حاوی اطلاعات اضافی در مورد مرحله باشند. برای مثال:

"navigationInstruction": {
  "maneuver": "TURN_SLIGHT_LEFT",
  "instructions": "Slight left (signs for I-90 W/Worcester)nParts of this road may be closed at certain times or days"
}

ویژگی‌های باقی‌مانده در هر مرحله، اطلاعاتی در مورد آن مرحله، مانند distanceMeters ، duration و polyline را توصیف می‌کنند:

{
  "distanceMeters": integer,
  "staticDuration": string,
  "polyline": {
    object (Polyline)
  },
  "startLocation": {
    object (Location)
  },
  "endLocation": {
    object (Location)
  },
  "navigationInstruction": {
    object (NavigationInstruction)
  }
}

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

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

• از پارامتر languageCode یک درخواست برای تنظیم صریح زبان مسیر از لیست زبان‌های پشتیبانی‌شده استفاده کنید. گوگل اغلب زبان‌های پشتیبانی‌شده را به‌روزرسانی می‌کند، بنابراین این لیست ممکن است جامع نباشد.

• اگر نامی به زبان مشخص شده موجود نباشد، API از نزدیکترین مورد منطبق استفاده می‌کند.

• زبان مشخص شده می‌تواند بر مجموعه نتایجی که API برای برگرداندن انتخاب می‌کند و ترتیب برگرداندن آنها تأثیر بگذارد. ژئوکودر بسته به زبان، اختصارات را به طور متفاوتی تفسیر می‌کند، مانند اختصارات مربوط به انواع خیابان، یا مترادف‌هایی که ممکن است در یک زبان معتبر باشند اما در زبان دیگر معتبر نباشند. به عنوان مثال، utca و tér مترادف خیابان در زبان مجارستانی هستند.

آرایه geocodingResults را درک کنید

برای هر مکانی در درخواست (مبدا، مقصد یا نقطه مسیر میانی) که به عنوان یک رشته آدرس یا به عنوان یک کد پلاس مشخص شده باشد، API تلاش می‌کند تا مرتبط‌ترین مکان را که دارای شناسه مکان مربوطه است، پیدا کند. هر عنصر از آرایه geocodingResults شامل فیلد placeID است که شامل مکان به عنوان شناسه مکان و یک فیلد type است که نوع مکان را مشخص می‌کند، مانند street_address ، premise یا airport .

آرایه geocodingResults شامل سه فیلد است:

• origin : اگر به عنوان یک رشته آدرس یا به عنوان یک کد پلاس مشخص شده باشد، شناسه مکان origin است. در غیر این صورت، این فیلد از پاسخ حذف می‌شود.

• destination : اگر به عنوان یک رشته آدرس یا به عنوان یک کد پلاس مشخص شده باشد، شناسه مکان مقصد است. در غیر این صورت، این فیلد از پاسخ حذف می‌شود.

• intermediates : آرایه‌ای شامل شناسه مکان هر نقطه مسیر میانی که به صورت رشته آدرس یا به صورت کد پلاس مشخص شده است. اگر یک نقطه مسیر میانی را با استفاده از شناسه مکان یا مختصات طول و عرض جغرافیایی مشخص کنید، از پاسخ حذف می‌شود. از ویژگی intermediateWaypointRequestIndex در پاسخ استفاده کنید تا مشخص شود کدام نقطه مسیر میانی در درخواست با شناسه مکان در پاسخ مطابقت دارد.

"geocodingResults": {
    "origin": {
        "geocoderStatus": {},
        "type": [
             enum (Type)
        ],
        "placeId": string
    },
    "destination": {
        "geocoderStatus": {},
        "type": [
            enum (Type)
        ],
        "placeId": string
    },
    "intermediates": [
        {
            "geocoderStatus": {},
            "intermediateWaypointRequestIndex": integer,
            "type": [
                enum (Type)
            ],
            "placeId": string
        },
        {
           "geocoderStatus": {},
           "intermediateWaypointRequestIndex": integer,
            "type": [
                enum (Type)
            ],
            "placeId": string
        }
    ]
}

درک مقادیر پاسخ محلی

مقادیر پاسخ محلی‌شده، یک فیلد پاسخ اضافی هستند که متن محلی‌شده را برای مقادیر پارامترهای برگشتی ارائه می‌دهند. متن محلی‌شده برای مدت زمان سفر، مسافت و سیستم واحد (متریک یا امپریال) ارائه می‌شود. شما با استفاده از یک ماسک فیلد، مقادیر محلی‌شده را درخواست می‌کنید و می‌توانید زبان و سیستم واحد را مشخص کنید یا از مقادیر استنباط‌شده توسط API استفاده کنید. برای جزئیات بیشتر، به LocalizedValues ​​مراجعه کنید.

برای مثال، اگر کد زبانی را برای واحدهای آلمانی (de) و امپریال مشخص کنید، مقداری برای distanceMeters برابر با ۴۹۸۸۹.۷ دریافت می‌کنید، اما متن محلی‌شده‌ای را نیز دریافت می‌کنید که اندازه‌گیری فاصله را در واحدهای آلمانی و امپریال ارائه می‌دهد، بنابراین "۳۱ Meile".

در اینجا مثالی از آنچه برای مقادیر محلی مشاهده خواهید کرد، آورده شده است:

{ "localized_values":
  {
    "distance": { "text": "31,0 Meile/n" },
    "duration": { "text": 38 Minuten}.
    "static_duration": { "text": 36 Minuten}.
  }
}

اگر زبان یا سیستم واحد را مشخص نکنید، API زبان و واحدها را به صورت زیر استنباط می‌کند:

• متد ComputeRoutes واحدهای مکان و مسافت را از نقطه مسیر مبدا استنباط می‌کند. بنابراین برای یک درخواست مسیریابی در ایالات متحده، API زبان en-US و واحدهای IMPERIAL را استنباط می‌کند.
• متد ComputeRouteMatrix به صورت پیش‌فرض زبان و واحدهای متریک را به صورت 'en-US' تنظیم می‌کند.