Advanced Concepts

Note: The examples below use the Roads API in the Java Client for Google Maps Services. You can adapt the concepts to your language of choice. The Python Client, Go Client and Node.js Client are also available on GitHub.

Acquiring data

There are many ways to obtain collected location data. Here we describe two techniques for acquiring data to use with the snap to roads feature of the Roads API.

GPX

GPX is an open XML-based format for sharing routes, tracks and waypoints captured by GPS devices. This example uses the XmlPull parser, a lightweight XML parser available for both Java server and mobile environments.

/**
 * 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;
}

Here's some raw GPX data loaded onto a map.

Android location services

The best way to capture GPS data from an Android device varies depending on your use case. Take a look at the Android training class on Receiving Location Updates, as well as the Google Play Location samples on GitHub.

Processing long paths

As the snap to roads feature infers the location based on the full path, rather than individual points, you need to take care when processing long paths (that is, paths over the 100-point-per-request limit).

In order to treat the individual requests as one long path, you should include some overlap, such that the final points from the previous request are included as the first points of the subsequent request. The number of points to include depends on the accuracy of your data. You should include more points for low-accuracy requests.

This example uses the Java Client for Google Maps Services to send paged requests and then rejoins the data, including interpolated points, into the returned list.

/**
 * 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;
}

Here's the data from above after running the snap to roads requests. The red line is the raw data and the blue line is the snapped data.

Efficient use of quota

The response to a snap to roads request includes a list of place IDs that map to the points you provided, potentially with additional points if you set interpolate=true.

In order to make efficient use of your allowed quota for a speed limits request, you should only query for unique place IDs in your request. This example uses the Java Client for Google Maps Services to query speed limits from a list of place IDs.

/**
 * 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;
}

Here's the data from above with speed limits marked at each unique place ID.

Interplay with other APIs

One of the benefits of having place IDs returned in the snap to roads responses is that you can use the place ID across many of the Google Maps Platform APIs. This example uses the Java Client for Google Maps Services to geocode a place returned from the above snap to road request.

/**
 * 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;
}

Here the speed limit marker has been annotated with the address from the Geocoding API.

Sample code

Considerations

The code supporting this article is available as a single Android app for illustrative purposes. In practice you should not distribute your server-side API keys in an Android app as your key cannot be secured against unauthorized access from a third party. Instead, to secure your keys you should deploy the API-facing code as a server-side proxy and have your Android app send requests via the proxy, ensuring requests are authorized.

Download

Download the code from GitHub.