> [!NOTE]
> **Note:** The examples below use the Roads API in the [Java Client for Google Maps Services](https://github.com/googlemaps/google-maps-services-java). You can adapt the concepts to your language of choice. The [Python Client](https://github.com/googlemaps/google-maps-services-python) , [Go Client](https://github.com/googlemaps/google-maps-services-go) and [Node.js Client](https://github.com/googlemaps/google-maps-services-js) are also available on GitHub.

## Acquire 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](https://developers.google.com/maps/documentation/roads/snap.md.txt) 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](http://www.xmlpull.org/) 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.

![Raw GPX data on a map](https://developers.google.com/static/maps/documentation/roads/images/gpxdata.png)

### 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](https://developer.android.com/training/location/receive-location-updates.html),
as well as the
[Google Play Location samples on GitHub](https://github.com/googlesamples/android-play-location).

## Process long paths

As the [snap to roads](https://developers.google.com/maps/documentation/roads/snap.md.txt) 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](https://github.com/googlemaps/google-maps-services-java)
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.

![Example of data that has been snapped to roads](https://developers.google.com/static/maps/documentation/roads/images/snapped.png)

## Efficient use of quota

The response to a [snap to roads](https://developers.google.com/maps/documentation/roads/snap.md.txt) 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](https://github.com/googlemaps/google-maps-services-java)
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.

![Speed limit signs on a map](https://developers.google.com/static/maps/documentation/roads/images/speeds.png)

## Interplay with other APIs

One of the benefits of having place IDs returned in the [snap to roads](https://developers.google.com/maps/documentation/roads/snap.md.txt)
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](https://github.com/googlemaps/google-maps-services-java)
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.

![Geocoded address shown on a marker](https://developers.google.com/static/maps/documentation/roads/images/geocoded.png)

## Sample code

### Considerations

The code supporting this document is available as a single Android app for
illustrative purposes. In practice you shouldn't 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
using the proxy, to be sure requests are authorized.

### Download

Download the code from [GitHub](https://github.com/googlemaps/roads-api-samples).