進階概念

注意：下列範例會使用 Google 地圖服務的 Java 用戶端中的 Roads API。您可以將這些概念改編成所選語言。Python 用戶端 Go 用戶端和 Node.js 用戶端 GitHub。

取得資料

取得位置資料的方法有很多種。以下將說明兩種取得資料的技術，以便搭配 Roads API 的貼齊道路功能使用。

GPX

GPX 是一種開放的 XML 格式，可分享路線、歷程和路線控點 GPS 裝置擷取的影片。本範例使用 XmlPull 剖析器 Java 伺服器和行動環境都提供輕量級 XML 剖析器。

/**
 * Parses the waypoint (wpt tags) data into native objects from a GPX stream.
 */
private List<LatLng> loadGpxData(XmlPullParser parser, InputStream gpxIn)
        throws XmlPullParserException, IOException {
    // We use a List<> as we need subList for paging later
    List<LatLng> latLngs = new ArrayList<>();
    parser.setInput(gpxIn, null);
    parser.nextTag();

    while (parser.next() != XmlPullParser.END_DOCUMENT) {
        if (parser.getEventType() != XmlPullParser.START_TAG) {
            continue;
        }

        if (parser.getName().equals("wpt")) {
            // Save the discovered latitude/longitude attributes in each <wpt>.
            latLngs.add(new LatLng(
                    Double.valueOf(parser.getAttributeValue(null, "lat")),
                    Double.valueOf(parser.getAttributeValue(null, "lon"))));
        }
        // Otherwise, skip irrelevant data
    }

    return latLngs;
}

以下是載入至地圖的部分原始 GPX 資料。

Android 定位服務

從 Android 裝置擷取 GPS 資料的最佳方法會因用途而異。請瀏覽「接收位置資訊」中的 Android 訓練課程 更新內容，以及 Google Play 位置範例： GitHub。

正在處理長路徑

「留到道路」功能會根據完整路徑推斷位置， 而非個別積分 路徑。

為了將個別要求視為一條長路徑，您應加入一些重疊，讓前一個要求的最後一個點，成為後續要求的第一個點。要納入的點數取決於資料的準確度。您應為低精確度要求加入更多點。

這個範例會使用 Google 地圖服務適用的 Java 用戶端傳送分頁要求，然後將資料 (包括內插點) 重新加入傳回清單。

/**
 * Snaps the points to their most likely position on roads using the Roads API.
 */
private List<SnappedPoint> snapToRoads(GeoApiContext context) throws Exception {
    List<SnappedPoint> snappedPoints = new ArrayList<>();

    int offset = 0;
    while (offset < mCapturedLocations.size()) {
        // Calculate which points to include in this request. We can't exceed the API's
        // maximum and we want to ensure some overlap so the API can infer a good location for
        // the first few points in each request.
        if (offset > 0) {
            offset -= PAGINATION_OVERLAP;   // Rewind to include some previous points.
        }
        int lowerBound = offset;
        int upperBound = Math.min(offset + PAGE_SIZE_LIMIT, mCapturedLocations.size());

        // Get the data we need for this page.
        LatLng[] page = mCapturedLocations
                .subList(lowerBound, upperBound)
                .toArray(new LatLng[upperBound - lowerBound]);

        // Perform the request. Because we have interpolate=true, we will get extra data points
        // between our originally requested path. To ensure we can concatenate these points, we
        // only start adding once we've hit the first new point (that is, skip the overlap).
        SnappedPoint[] points = RoadsApi.snapToRoads(context, true, page).await();
        boolean passedOverlap = false;
        for (SnappedPoint point : points) {
            if (offset == 0 || point.originalIndex >= PAGINATION_OVERLAP - 1) {
                passedOverlap = true;
            }
            if (passedOverlap) {
                snappedPoints.add(point);
            }
        }

        offset = upperBound;
    }

    return snappedPoints;
}

以下是對道路提出比對要求之後的資料。紅色的 是原始資料，藍線是已接合的資料。

有效率地使用配額

snap to roads 要求的回應包含地點 ID 清單，這些 ID 會對應至您提供的點，如果您設定 interpolate=true，則可能會包含其他點。

為了有效運用允許的配額來處理速限要求， 在要求中，只能查詢專屬地點 ID。這個範例使用 Google 地圖服務適用的 Java 用戶端，從地點 ID 清單中查詢速限。

/**
 * Retrieves speed limits for the previously-snapped points. This method is efficient in terms
 * of quota usage as it will only query for unique places.
 *
 * Note: Speed limit data is only available for requests using an API key enabled for a
 * Google Maps APIs Premium Plan license.
 */
private Map<String, SpeedLimit> getSpeedLimits(GeoApiContext context, List<SnappedPoint> points)
        throws Exception {
    Map<String, SpeedLimit> placeSpeeds = new HashMap<>();

    // Pro tip: Save on quota by filtering to unique place IDs.
    for (SnappedPoint point : points) {
        placeSpeeds.put(point.placeId, null);
    }

    String[] uniquePlaceIds =
            placeSpeeds.keySet().toArray(new String[placeSpeeds.keySet().size()]);

    // Loop through the places, one page (API request) at a time.
    for (int i = 0; i < uniquePlaceIds.length; i += PAGE_SIZE_LIMIT) {
        String[] page = Arrays.copyOfRange(uniquePlaceIds, i,
                Math.min(i + PAGE_SIZE_LIMIT, uniquePlaceIds.length));

        // Execute!
        SpeedLimit[] placeLimits = RoadsApi.speedLimits(context, page).await();
        for (SpeedLimit sl : placeLimits) {
            placeSpeeds.put(sl.placeId, sl);
        }
    }

    return placeSpeeds;
}

以上資料，其中包含各專屬地點 ID 的速限標示。

與其他 API 互動

將地點 ID 傳回道路的其中一項好處 您可將地點 ID 用於 Google 地圖平台 API。本範例使用 Google 地圖服務適用的 Java 用戶端 ，為上述 中 傳回的地點對齊道路要求。

/**
 * Geocodes a snapped point using the place ID.
 */
private GeocodingResult geocodeSnappedPoint(GeoApiContext context, SnappedPoint point) throws Exception {
    GeocodingResult[] results = GeocodingApi.newRequest(context)
            .place(point.placeId)
            .await();

    if (results.length > 0) {
        return results[0];
    }
    return null;
}

這裡的速限標記已標註 Geocoding API 的地址。

程式碼範例

注意事項

本文支援的程式碼是以單一 Android 應用程式的形式提供 說明用途。實際上，您不應該將 Android 應用程式中的 API 金鑰，因為無法防止金鑰受到未經授權的侵擾 允許第三方存取相反地，為了保護金鑰安全，您應該 以伺服器端 Proxy 的形式處理 API 的程式碼，並讓您的 Android 應用程式傳送要求 透過 Proxy 傳送要求，確保要求經過授權。

下載

從 GitHub 下載程式碼。