بررسی پاسخ مسیر

توسعه‌دهندگان منطقه اقتصادی اروپا (EEA)

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

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

برای گنجاندن این مورد در پاسخ این سند را ببینید
مسیر با بیشترین بهره‌وری سوخت یا انرژی براساس نوع موتور خودرو. پیکربندی مسیرهای بوم‌سازگار
حداکثر سه مسیر جایگزین درخواست مسیرهای جایگزین
چندخطی برای کل مسیر، برای هر بخش از مسیر، و برای هر مرحله از بخش. درخواست چندخطی‌های مسیر
عوارض تخمینی، با درنظر گرفتن هرگونه تخفیف قیمت عوارض یا گذربلیت‌های دردسترس برای راننده یا خودرو. محاسبه عوارض
پاسخ‌های بومی‌سازی‌شده براساس کدهای زبان و واحد اندازه‌گیری (امپریال یا متریک). درخواست مقادیر بومی‌سازی‌شده
برای قالب‌بندی دستورالعمل‌های پیمایش به‌صورت رشته نوشتاری HTML،‏ HTML_FORMATTED_NAVIGATION_INSTRUCTIONS را به extraComputations اضافه کنید. محاسبات اضافی

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

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

درباره پوشش‌های فیلد

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

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

برای اطلاعات بیشتر، انتخاب اطلاعات برای برگرداندن را ببینید.

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

هنگام نمایش نتایج به کاربران، باید بیانیه حق نشر زیر را اضافه کنید:

Powered by Google, ©YEAR Google

برای مثال:

Powered by Google, ©2023 Google

درباره مسیرها، بخش‌ها، و مراحل

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

مسیر، بخش، و مرحله.

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

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

  • بخش: مسیر از یک نقطه‌مسیر در مسیر به نقطه‌مسیر بعدی در مسیر. هر بخش از یک یا چند مرحله مجزا تشکیل شده است.

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

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

  • مرحله: یک دستورالعمل درطول بخش مسیر. مرحله، اتمی‌ترین واحد مسیر است. برای مثال، یک مرحله می‌تواند نشان دهد «در خیابان اصلی به چپ بپیچید».

محتوای پاسخ چیست؟

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

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

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

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

پاسخ این فرم را دارد:

{
  // 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 شناسایی می‌شود:

مقدار شرح
DEFAULT_ROUTE مسیر پیش‌فرض را مشخص می‌کند.
FUEL_EFFICIENT مسیر بوم‌سازگار را مشخص می‌کند.
DEFAULT_ROUTE_ALTERNATE نشان‌دهنده مسیر جایگزین است.

آرایه 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 از نوع RouteLegStep است. هر مرحله مربوط به یک دستورالعمل درطول مسیر است. هر بخش همیشه شامل حداقل یک مرحله است.

هر عنصر در آرایه 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 درخواست برای تنظیم صریح زبان مسیر از فهرست زبان‌های پشتیبانی‌شده استفاده کنید. Google اغلب زبان‌های پشتیبانی‌شده را به‌روز می‌کند، بنابراین ممکن است این فهرست کامل نباشد.

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

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

آشنایی با آرایه geocodingResults

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

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

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

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

  • intermediates: آرایه‌ای حاوی شناسه مکان هر نقطه‌مسیر میانی که به‌عنوان رشته نشانی یا Plus Code مشخص شده است. اگر نقطه‌مسیر میانی را بااستفاده از شناسه مکان یا مختصات طول و عرض جغرافیایی مشخص کنید، از پاسخ حذف می‌شود. از ویژگی 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 را به‌صورت ۴۹۸۸۹٫۷ دریافت می‌کنید، اما نوشتار بومی‌سازی‌شده‌ای نیز دریافت می‌کنید که آن اندازه‌گیری فاصله را به زبان آلمانی و واحدهای امپراتوری ارائه می‌دهد، یعنی «31 Meile».

در اینجا نمونه‌ای از آنچه برای مقادیر بومی‌سازی‌شده خواهید دید آورده شده است:

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

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

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