Advanced Concepts

Acquiring data

There are many ways to obtain collected location data. Here we describe two techniques for acquiring data to use with thesnap to roadsfeature of theRoads API.

GPX

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

/**
*Parsesthewaypoint(wpttags)dataintonativeobjectsfromaGPXstream.
*/
privateList<LatLng>loadGpxData(XmlPullParserparser,InputStreamgpxIn)
throwsXmlPullParserException,IOException{
//WeuseaList<>asweneedsubListforpaginglater
List<LatLng>latLngs=newArrayList<>();
parser.setInput(gpxIn,null);
parser.nextTag();

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

if(parser.getName().equals("wpt")){
//Savethediscoveredlatitude/longitudeattributesineach<wpt>.
latLngs.add(newLatLng(
Double.valueOf(parser.getAttributeValue(null,"lat")),
Double.valueOf(parser.getAttributeValue(null,"lon"))));
}
//Otherwise,skipirrelevantdata
}

returnlatLngs;
}

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

Raw GPX data on 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 onReceiving Location Updates,as well as theGoogle Play Location samples on GitHub.

Processing long paths

As thesnap to roadsfeature 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 theJava Client for Google Maps Servicesto send paged requests and then rejoins the data, including interpolated points, into the returned list.

/**
*SnapsthepointstotheirmostlikelypositiononroadsusingtheRoadsAPI.
*/
privateList<SnappedPoint>snapToRoads(GeoApiContextcontext)throwsException{
List<SnappedPoint>snappedPoints=newArrayList<>();

intoffset=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.
}
intlowerBound=offset;
intupperBound=Math.min(offset+PAGE_SIZE_LIMIT,mCapturedLocations.size());

// Get the data we need for this page.
LatLng[]page=mCapturedLocations
.subList(lowerBound,upperBound)
.toArray(newLatLng[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();
booleanpassedOverlap=false;
for(SnappedPointpoint:points){
if(offset==0||point.originalIndex>=PAGINATION_OVERLAP-1){
passedOverlap=true;
}
if(passedOverlap){
snappedPoints.add(point);
}
}

offset=upperBound;
}

returnsnappedPoints;
}

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

Efficient use of quota

The response to asnap to roadsrequest includes a list of place IDs that map to the points you provided, potentially with additional points if you setinterpolate=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 theJava Client for Google Maps Servicesto query speed limits from a list of place IDs.

/**
*Retrievesspeedlimitsforthepreviously-snappedpoints.Thismethodisefficientinterms
*ofquotausageasitwillonlyqueryforuniqueplaces.
*
*Note:SpeedlimitdataisonlyavailableforrequestsusinganAPIkeyenabledfora
*GoogleMapsAPIsPremiumPlanlicense.
*/
privateMap<String,SpeedLimit>getSpeedLimits(GeoApiContextcontext,List<SnappedPoint>points)
throwsException{
Map<String,SpeedLimit>placeSpeeds=newHashMap<>();

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

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

// Loop through the places, one page (API request) at a time.
for(inti=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(SpeedLimitsl:placeLimits){
placeSpeeds.put(sl.placeId,sl);
}
}

returnplaceSpeeds;
}

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

Speed limit signs on a map

Interplay with other APIs

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

/**
*GeocodesasnappedpointusingtheplaceID.
*/
privateGeocodingResultgeocodeSnappedPoint(GeoApiContextcontext,SnappedPointpoint)throwsException{
GeocodingResult[]results=GeocodingApi.newRequest(context)
.place(point.placeId)
.await();

if(results.length>0){
returnresults[0];
}
returnnull;
}

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

Geocoded address shown on a marker

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 fromGitHub.