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

هنگامی که 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 است.
،

هنگامی که 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 است.
،

هنگامی که 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 استفاده کنید. برای جزئیات بیشتر ، به BoalizedValues ​​مراجعه کنید.

به عنوان مثال ، اگر کد زبانی را برای واحدهای آلمانی (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 از مکان و واحدهای مسافت از نقطه راه Origin استفاده می کند. بنابراین برای یک درخواست مسیریابی در ایالات متحده ، API en-US زبان و واحدهای IMPERIAL استفاده می کند.
  • روش ComputeRouteMatrix به واحدهای "en-us" و واحدهای متریک پیش فرض می کند.
،

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

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

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

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

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

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

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

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

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

در مورد نمایش کپی رایت

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

Powered by Google, © YEAR Google

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

Powered by Google, ©2023 Google

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

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

مسیر ، پا و مرحله.

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

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

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

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

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

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

چه چیزی در پاسخ است

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

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

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

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

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

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

آرایه مسیرها را رمزگشایی کنید

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

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

هر مسیر در آرایه با خاصیت آرایه 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
}

به دلیل شرایط فعلی رانندگی و سایر عوامل ، مسیر پیش فرض و مسیر سازگار با محیط زیست می تواند یکسان باشد. در این حالت ، Array 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 یک درخواست استفاده کنید. گوگل اغلب زبانهای پشتیبانی شده را به روز می کند ، بنابراین این لیست ممکن است جامع نباشد.

  • اگر یک نام به زبان مشخص در دسترس نباشد ، 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 استفاده کنید. برای جزئیات بیشتر ، به BoalizedValues ​​مراجعه کنید.

به عنوان مثال ، اگر کد زبانی را برای واحدهای آلمانی (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 از مکان و واحدهای مسافت از نقطه راه Origin استفاده می کند. بنابراین برای یک درخواست مسیریابی در ایالات متحده ، API en-US زبان و واحدهای IMPERIAL استفاده می کند.
  • روش ComputeRouteMatrix به واحدهای "en-us" و واحدهای متریک پیش فرض می کند.