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

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

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

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

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

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

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

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

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

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

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

Powered by Google, ©YEAR Google

برای مثال:

Powered by Google, ©2023 Google

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

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

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

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

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

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

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

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

محتویات پاسخ

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

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

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

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

پاسخ به‌صورت زیر است:

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

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

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

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

آشنایی با آرایه 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 را به‌صورت 49889.7 دریافت می‌کنید، اما همچنین نوشتاری بومی‌سازی‌شده که آن اندازه‌گیری فاصله را به زبان آلمانی و واحدهای امپراتوری ارائه می‌دهد، بنابراین «۳۱ مایل».

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

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

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

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