Xem lại phản hồi về tuyến đường

Khi tính toán một tuyến đường, API Tuyến đường sẽ lấy điểm tham chiếu và tham số cấu hình mà bạn cung cấp làm dữ liệu đầu vào. Sau đó, API sẽ trả về một phản hồi chứa tuyến mặc định và một hoặc nhiều tuyến thay thế.

Phản hồi của bạn có thể bao gồm nhiều loại tuyến và dữ liệu khác, dựa trên các trường mà bạn yêu cầu:

Để đưa nội dung này vào câu trả lời Xem tài liệu này
Tuyến đường tiết kiệm nhiên liệu hoặc năng lượng nhất dựa trên loại động cơ của xe. Thiết lập tuyến đường thân thiện với môi trường
Tối đa 3 tuyến đường thay thế Yêu cầu tuyến đường thay thế
Hình nhiều đường cho toàn bộ tuyến đường, cho mỗi chặng của một tuyến đường và cho mỗi bước của một chặng. Yêu cầu hình nhiều đường cho tuyến đường
Mức phí cầu đường ước tính, có tính đến mọi khoản chiết khấu phí cầu đường hoặc thẻ và vé cho người lái xe hoặc xe. Tính phí cầu đường
Phản hồi được bản địa hoá theo mã ngôn ngữ và đơn vị đo lường (hệ Anh hoặc chỉ số). Yêu cầu giá trị được bản địa hoá
Để định dạng hướng dẫn điều hướng dưới dạng chuỗi văn bản HTML, hãy thêm HTML_FORMATTED_NAVIGATION_INSTRUCTIONS vào extraComputations. Tính toán bổ sung

Để biết danh sách đầy đủ các lựa chọn đầu vào, hãy xem Các lựa chọn tuyến đường có sẵnNội dung yêu cầu.

Bằng cách sử dụng phản hồi, bạn có thể cung cấp cho khách hàng thông tin cần thiết để chọn tuyến thích hợp cho yêu cầu của họ.

Giới thiệu về mặt nạ cho trường (field mask)

Khi gọi một phương thức để tính toán tuyến đường, bạn phải chỉ định một mặt nạ trường giúp xác định những trường bạn muốn trả về trong phản hồi. Không có danh sách mặc định chứa các trường được trả về. Nếu bạn bỏ qua danh sách này, các phương thức sẽ trả về lỗi.

Các ví dụ trong tài liệu này cho thấy toàn bộ đối tượng phản hồi mà không tính đến mặt nạ trường. Trong môi trường phát hành chính thức, phản hồi của bạn sẽ chỉ bao gồm các trường mà bạn chỉ định rõ ràng trong mặt nạ trường (field mask).

Để biết thêm thông tin, hãy xem phần Chọn thông tin cần trả về.

Giới thiệu về việc hiển thị thông tin bản quyền

Bạn phải bao gồm tuyên bố bản quyền sau đây khi hiển thị kết quả cho người dùng của mình:

Powered by Google, ©YEAR Google

Ví dụ:

Powered by Google, ©2023 Google

Giới thiệu về tuyến đường, chân và bước

Trước khi xem phản hồi do API Tuyến đường trả về, bạn cần hiểu rõ các thành phần tạo nên một tuyến:

Tuyến đường, chặng đường và bước đi.

Phản hồi của bạn có thể chứa thông tin về từng thành phần định tuyến sau:

  • Tuyến đường: Toàn bộ chuyến đi từ điểm tham chiếu gốc, qua bất kỳ điểm tham chiếu trung gian nào, tới điểm tham chiếu đích. Tuyến bao gồm một hoặc nhiều chân.

  • Chân: Đường dẫn từ một điểm tham chiếu trong tuyến đường đến điểm tham chiếu tiếp theo trong tuyến đường. Mỗi chân bao gồm một hoặc nhiều bước riêng biệt.

    Tuyến chứa một chân riêng cho con đường từ mỗi điểm tham chiếu đến điểm tiếp theo. Ví dụ: nếu tuyến chứa một điểm tham chiếu gốc và một điểm tham chiếu đích duy nhất, thì tuyến đường này chứa một chân duy nhất. Đối với mỗi điểm tham chiếu bổ sung mà bạn thêm vào tuyến đường sau điểm gốc và điểm đến, được gọi là điểm tham chiếu trung gian, API sẽ thêm một chân riêng.

    API không thêm chân cho điểm tham chiếu trung gian truyền qua. Ví dụ: một tuyến chứa điểm tham chiếu gốc, một điểm tham chiếu trung gian và một điểm tham chiếu đích chỉ chứa một chặng từ điểm gốc đến đích, trong khi đi qua điểm tham chiếu. Để biết thêm thông tin về điểm tham chiếu truyền, vui lòng xem phần Xác định điểm tham chiếu truyền qua.

  • Bước: Một hướng dẫn duy nhất dọc theo chân của một tuyến đường. Bước là đơn vị nguyên tử nhất của một tuyến đường. Ví dụ: một bước có thể cho biết "Rẽ trái trên Đường chính".

Nội dung trong câu trả lời

Đối tượng JSON đại diện cho phản hồi của API có các thuộc tính cấp cao nhất sau đây:

  • routes, một mảng các phần tử thuộc loại Route. Mảng routes chứa một phần tử cho mỗi tuyến mà API trả về. Mảng này có thể chứa tối đa 5 phần tử: tuyến mặc định, tuyến đường thân thiện với môi trường và tối đa 3 tuyến đường thay thế.

  • geocodingResults, một mảng các phần tử thuộc loại GeocodingResults. Đối với mọi vị trí trong yêu cầu (điểm gốc, điểm đến hoặc điểm tham chiếu trung gian) mà bạn đã chỉ định làm chuỗi địa chỉ hoặc dưới dạng Mã cộng, API sẽ thực hiện việc tra cứu mã địa điểm. Mỗi phần tử của mảng này chứa mã địa điểm tương ứng với một vị trí. Các vị trí trong yêu cầu được chỉ định dưới dạng mã địa điểm hoặc vĩ độ/kinh độ sẽ không được đưa vào. Nếu bạn đã chỉ định tất cả các vị trí bằng mã địa điểm hoặc toạ độ (vĩ độ và kinh độ), thì mảng này sẽ không được cung cấp.

  • fallbackInfo, thuộc loại FallbackInfo. Nếu không thể tính toán tuyến đường từ tất cả thuộc tính đầu vào, thì API có thể chuyển sang dùng một cách tính toán khác. Khi sử dụng chế độ dự phòng, trường này chứa thông tin chi tiết về phản hồi dự phòng. Nếu không, trường này sẽ không được đặt.

Phản hồi này có dạng:

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

Giải mã mảng tuyến đường

Phản hồi chứa mảng routes, trong đó mỗi phần tử mảng thuộc loại Route. Mỗi phần tử mảng đại diện cho toàn bộ một tuyến đường từ điểm gốc đến điểm đến. API luôn trả về ít nhất một tuyến, được gọi là tuyến mặc định.

Bạn có thể yêu cầu các tuyến đường khác. Nếu bạn yêu cầu một tuyến đường thân thiện với môi trường, thì mảng này có thể chứa 2 phần tử: tuyến đường mặc định và tuyến đường thân thiện với môi trường. Hoặc đặt computeAlternativeRoutes thành true trong yêu cầu để thêm tối đa 3 tuyến thay thế cho phản hồi.

Mỗi tuyến trong mảng được xác định bằng thuộc tính mảng routeLabels:

Giá trị Nội dung mô tả
DEFAULT_ROUTE Xác định tuyến đường mặc định.
FUEL_EFFICIENT Xác định tuyến đường thân thiện với môi trường.
DEFAULT_ROUTE_ALTERNATE Tôi chỉ ra một tuyến đường thay thế.

Mảng legs chứa định nghĩa về từng chặng của tuyến đường. Các thuộc tính còn lại, chẳng hạn như distanceMeters, durationpolyline, chứa thông tin tổng thể về tuyến đường:

{
  "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
}

Do điều kiện lái xe hiện tại và các yếu tố khác, tuyến đường mặc định và tuyến đường thân thiện với môi trường có thể giống nhau. Trong trường hợp này, mảng routeLabels chứa cả nhãn: DEFAULT_ROUTEFUEL_EFFICIENT.

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

Tìm hiểu về mảng chân

Mỗi route trong phản hồi chứa một mảng legs, trong đó mỗi phần tử mảng legs đều thuộc loại RouteLeg. Mỗi chân trong mảng xác định đường dẫn từ điểm tham chiếu này đến điểm tham chiếu tiếp theo dọc theo tuyến đường. Tuyến đường luôn chứa ít nhất một chặng.

Thuộc tính legs chứa định nghĩa về từng bước dọc theo chân trong mảng steps. Các thuộc tính còn lại, chẳng hạn như distanceMeters, durationpolyline chứa thông tin về chân.

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

Tìm hiểu về mảng bước

Mỗi chân trong phản hồi chứa một mảng steps, trong đó mỗi phần tử mảng steps thuộc loại RouteLegStep. Một bước tương ứng với một hướng dẫn duy nhất dọc theo chân. Một chân luôn chứa ít nhất một bước.

Mỗi phần tử trong mảng steps bao gồm thuộc tính navigationInstruction, thuộc loại NavigationInstruction, chứa hướng dẫn từng bước. Ví dụ:

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

instructions có thể chứa thông tin bổ sung về bước này. Ví dụ:

"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"
}

Các thuộc tính còn lại trong bước này mô tả thông tin về bước này, chẳng hạn như distanceMeters, durationpolyline:

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

Chỉ định ngôn ngữ của phần hướng dẫn bước

API này trả về thông tin tuyến đường bằng ngôn ngữ cục bộ, được chuyển tự sang một tập lệnh mà người dùng có thể đọc (nếu cần) trong khi quan sát ngôn ngữ ưu tiên. Tất cả các thành phần địa chỉ đều được trả về bằng cùng một ngôn ngữ.

  • Sử dụng tham số languageCode của một yêu cầu để đặt ngôn ngữ định tuyến một cách rõ ràng trong danh sách ngôn ngữ được hỗ trợ. Google thường cập nhật các ngôn ngữ được hỗ trợ, vì vậy, danh sách này có thể chưa đầy đủ.

  • Nếu không có tên bằng ngôn ngữ được chỉ định, thì API sẽ sử dụng kết quả khớp nhất.

  • Ngôn ngữ đã chỉ định có thể ảnh hưởng đến tập hợp kết quả mà API chọn để trả về và thứ tự trả về các kết quả đó. Bộ mã hoá địa lý này diễn giải các chữ viết tắt theo cách khác nhau tuỳ theo ngôn ngữ, chẳng hạn như từ viết tắt cho các loại đường phố hoặc từ đồng nghĩa có thể hợp lệ ở một ngôn ngữ nhưng không hợp lệ trong ngôn ngữ khác. Ví dụ: utca và tér là các từ đồng nghĩa với đường phố trong tiếng Hungary.

Tìm hiểu mảng mã hoá địa lý

Đối với mọi vị trí trong yêu cầu (điểm gốc, điểm đến hoặc điểm tham chiếu trung gian) được chỉ định dưới dạng chuỗi địa chỉ hoặc dưới dạng Mã cộng, API sẽ cố gắng tìm vị trí phù hợp nhất có mã địa điểm tương ứng. Mỗi phần tử của mảng geocodingResults chứa trường placeID chứa vị trí làm mã địa điểm và trường type chỉ định loại vị trí, chẳng hạn như street_address, premise hoặc airport.

Mảng geocodingResults chứa 3 trường:

  • origin: Nếu được chỉ định dưới dạng chuỗi địa chỉ hoặc mã Plus, thì mã vị trí của điểm khởi hành. Nếu không, trường này sẽ bị bỏ qua trong phản hồi.

  • destination: Nếu được chỉ định là chuỗi địa chỉ hoặc dưới dạng Plus Code, thì mã địa điểm của đích đến. Nếu không, trường này sẽ bị bỏ qua trong phản hồi.

  • intermediates: Một mảng chứa mã địa điểm của mọi điểm tham chiếu trung gian được chỉ định dưới dạng chuỗi địa chỉ hoặc mã Plus. Nếu bạn chỉ định một điểm tham chiếu trung gian bằng mã địa điểm hoặc vĩ độ và kinh độ, thì điểm này sẽ bị loại khỏi phản hồi. Sử dụng thuộc tính intermediateWaypointRequestIndex trong phản hồi để xác định điểm tham chiếu trung gian nào trong yêu cầu tương ứng với mã địa điểm trong phản hồi.

"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
        }
    ]
}

Tìm hiểu các giá trị câu trả lời đã bản địa hoá

Giá trị phản hồi đã bản địa hoá là một trường phản hồi bổ sung cung cấp văn bản đã bản địa hoá cho các giá trị tham số được trả về. Văn bản đã bản địa hoá được cung cấp cho thời lượng chuyến đi, khoảng cách và hệ thống đơn vị (hệ mét hoặc hệ đo lường Anh). Bạn yêu cầu các giá trị đã bản địa hoá bằng cách sử dụng mặt nạ trường (field mask), đồng thời có thể chỉ định ngôn ngữ và hệ thống đơn vị hoặc sử dụng các giá trị do API suy ra. Để biết thông tin chi tiết, hãy xem LocalizedValues.

Ví dụ: nếu chỉ định mã ngôn ngữ cho đơn vị tiếng Đức (de) và hệ đo lường Anh, bạn sẽ nhận được giá trị cho distanceMeters là 49889, 7, nhưng văn bản đã bản địa hoá cung cấp thông tin đo lường khoảng cách đó theo đơn vị tiếng Đức và hệ Anh, tức là "31 Meile".

Dưới đây là ví dụ về những gì bạn sẽ thấy đối với các giá trị đã bản địa hoá:

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

Nếu bạn không chỉ định ngôn ngữ hoặc hệ thống đơn vị, thì API sẽ suy ra ngôn ngữ và đơn vị như sau:

  • Phương thức ComputeRoutes dự đoán vị trí và đơn vị khoảng cách từ điểm tham chiếu gốc. Vì vậy, đối với một yêu cầu định tuyến ở Hoa Kỳ, API sẽ suy ra ngôn ngữ en-US và các đơn vị IMPERIAL.
  • Theo mặc định, phương thức ComputeRouteMatrix sử dụng ngôn ngữ "en-US" và đơn vị METRIC.