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

Khi tính toán một tuyến đường, Routes API sẽ lấy các điểm tham chiếu và thông 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 đường mặc định và một hoặc nhiều tuyến đường thay thế.

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

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

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

Giới thiệu về mặt nạ trường

Khi gọi một phương thức để tính toán một tuyến đường, bạn phải chỉ định một mặt nạ trường xác định những trường mà bạn muốn trả về trong phản hồi. Không có danh sách mặc định về 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 cần xem xét mặt nạ trường. Trong môi trường phát hành công khai, phản hồi của bạn sẽ chỉ bao gồm những trường mà bạn chỉ định rõ ràng trong mặt nạ trường.

Để 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 thêm tuyên bố bản quyền sau đây khi hiển thị kết quả cho người dùng:

Powered by Google, ©YEAR Google

Ví dụ:

Powered by Google, ©2023 Google

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

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

Câu trả lời của bạn có thể chứa thông tin về từng thành phần sau đây của tuyến đường:

• Tuyến đường: Toàn bộ hành trình từ điểm đánh dấu khởi hành, qua mọi điểm đánh dấu trung gian, đến điểm đánh dấu đích đến. Một tuyến đường bao gồm một hoặc nhiều chặng.

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

  Một tuyến đường chứa một chặng riêng cho đường đi từ mỗi điểm tham chiếu đến điểm tham chiếu tiếp theo. Ví dụ: nếu tuyến đường chứa một điểm đánh dấu điểm khởi hành duy nhất và một điểm đánh dấu điểm đến duy nhất, thì tuyến đường đó sẽ chứa một chặng 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 xuất phát và điểm đến (gọi là điểm tham chiếu trung gian), API sẽ thêm một chặng riêng.

  API này không thêm một chặng cho một điểm tham chiếu trung gian truyền qua. Ví dụ: một tuyến đường có chứa một điểm đánh dấu điểm khởi hành, một điểm đánh dấu trung gian xuyên suốt và một điểm đánh dấu điểm đến chỉ chứa một chặng từ điểm khởi hành đến điểm đến, trong khi đi qua điểm đánh dấu. Để biết thêm thông tin về điểm tham chiếu trung gian, hãy xem phần Xác định điểm tham chiếu trung gian.

• Bước: Một chỉ dẫn duy nhất dọc theo chặng của một tuyến đường. Bước là đơn vị nhỏ nhất của một tuyến đường. Ví dụ: một bước có thể cho biết "Rẽ trái vào đường Main Street".

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

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

• routes, một mảng gồm 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 đường do API trả về. Mảng này có thể chứa tối đa 5 phần tử: tuyến đường 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 khởi hành, điểm đến hoặc điểm tham chiếu trung gian) mà bạn chỉ định là chuỗi địa chỉ hoặc là Mã cộng, API sẽ thực hiện một thao tá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 là mã địa điểm hoặc toạ độ vĩ độ/kinh độ 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 một tuyến đường từ tất cả các thuộc tính đầu vào, thì API có thể chuyển sang sử dụng một cách tính toán khác. Khi chế độ dự phòng được dù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 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ộ tuyến đường từ điểm khởi hành đến điểm đến. API này luôn trả về ít nhất một tuyến đường, được gọi là tuyến đường mặc định.

Bạn có thể yêu cầu thêm 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 đường thay thế vào phản hồi.

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

Mảng legs chứa định nghĩa của từng chặng trong tuyến đường. Các thuộc tính còn lại, chẳng hạn như distanceMeters, duration và polyline, chứa thông tin về toàn bộ 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ả hai nhãn: DEFAULT_ROUTE và FUEL_EFFICIENT.

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

Tìm hiểu về mảng legs

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

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

{
  "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 mảng bước

Mỗi chặng 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 chỉ dẫn duy nhất dọc theo chặng đường. Một chặng luôn có ít nhất một bước.

Mỗi phần tử trong mảng steps đều có thuộc tính navigationInstruction, thuộc loại NavigationInstruction, chứa chỉ dẫn về bước. Ví dụ:

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

instructions có thể chứa thêm thông tin 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, chẳng hạn như distanceMeters, duration và polyline:

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

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

API này trả về thông tin về tuyến đường bằng ngôn ngữ địa phương, được chuyển tự sang một kịch bản mà người dùng có thể đọc được (nếu cần), đồng thời tuân thủ 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 rõ ràng ngôn ngữ của tuyến đường trong danh sách ngôn ngữ được hỗ trợ. Google thường xuyên 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, API sẽ sử dụng tên gần giống nhất.

• Ngôn ngữ được 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ề. Trình mã hoá địa lý diễn giải các từ viết tắt theo nhiều cách tuỳ thuộc vào ngôn ngữ, chẳng hạn như từ viết tắt cho các loại đường hoặc từ đồng nghĩa có thể hợp lệ trong 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à từ đồng nghĩa với đường trong tiếng Hungary.

Tìm hiểu mảng geocodingResults

Đối với mọi vị trí trong yêu cầu (điểm xuất phát, điểm đến hoặc điểm tham chiếu trung gian) được chỉ định là chuỗi địa chỉ hoặc là 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 đều chứa trường placeID chứa vị trí dưới dạng 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 là một chuỗi địa chỉ hoặc là một Plus Code, thì mã địa điểm 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à một chuỗi địa chỉ hoặc là một 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 dưới dạng Mã cộng. Nếu bạn chỉ định một điểm tham chiếu trung gian bằng cách sử dụng mã địa điểm hoặc toạ độ vĩ độ và kinh độ, thì điểm tham chiếu đó sẽ bị bỏ qua trong 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 về các giá trị phản hồi được 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ệ thống đo lường bằng mét hoặc hệ thống đo lường của Hoa Kỳ). Bạn yêu cầu các giá trị được bản địa hoá bằng cách sử dụng một mặt nạ trường và có thể chỉ định ngôn ngữ cũng như hệ thống đơn vị hoặc sử dụng các giá trị mà API suy luận. Để biết thông tin chi tiết, hãy xem LocalizedValues.

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

Sau đâ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ị, API sẽ suy luận ngôn ngữ và đơn vị như sau:

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