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

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

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

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

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

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

درباره ماسک های میدانی

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

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

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

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

هنگام نمایش نتایج به کاربران خود باید عبارت حق چاپ زیر را درج کنید:

Powered by Google, © YEAR Google

به عنوان مثال:

Powered by Google, ©2023 Google

درباره مسیرها، پاها، و پله ها

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

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

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

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

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

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

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

آنچه در پاسخ است

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

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

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

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

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

{
  // 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 است که حاوی دستورالعمل step است. به عنوان مثال:

"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 برای بازگرداندن انتخاب می‌کند و ترتیب بازگشت آنها تأثیر بگذارد. geocoder بسته به زبان، اختصارات را متفاوت تفسیر می کند، مانند اختصارات انواع خیابان، یا مترادف هایی که ممکن است در یک زبان معتبر باشند اما در زبان دیگر معتبر نیستند. برای مثال، utca و tér مترادف خیابان در مجارستانی هستند.

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

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

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

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