The solution: When TravelTime API rejects your coordinates for being too far from roads, use OpenStreetMap's PBF files with highway attribute filtering instead of Shapefiles to find the nearest drivable road coordinates.
If you're building mapping applications with TravelTime's catchment area API, you've likely encountered an error where coordinates must be "close to a road."
OpenStreetMap data provides the answer.
By switching from Shapefile format to PBF files and filtering by highway attributes, you can reliably find road-adjacent coordinates that TravelTime accepts, even in remote areas where your original coordinates might be miles from the nearest drivable road.
The Modern Mapping Landscape and TravelTime Coordinates
Geographical mapping is one of those programming domains that used to be hard and required us to reinvent the wheel in a lot of cases. These days, though, so many resources are available.
While using TravelTime to find a catchment area that contains 60-minute commutes from a given location, I found that the service expects origin coordinates to be close to a road.
In other words, we can't drop a pin on the map that's in the middle of a remote area with no road service. Attempting to do so will result in an API error that requests the developer use more suitable coordinates.
But how do we know where the roads are? I'm sure there may be some APIs available in Google Maps or the like, but I opted to solve the problem using OpenStreetMap (OSM) files.
These files are available at many levels from the Geofabrik server: you can download entire countries' worth of road shapes or break the data down to the state level (and sometimes even more granular than that).
The First Attempt: ShapeFile Format
ShapeFile
At first, I used the Shapefile format. This format is easily transformed to GeoJSON, which is easily used in Python.
The trick there is to load the shapes from the file, then use geometry to find the closest point on a road to the target coordinates. That revised point may be very close to the original, or miles away, depending on how the road lies.
For the most part, using the Shapefile source worked. But I ran into a case where the original coordinates were within a national park.
Limitations of ShapeFiles
Hiking trails are among the shapes counted as "roads" of some kind in OSM. I was getting a road point on the hiking trail, but this was not sufficient for using the TravelTime service.
Observation of the Shapefile data showed that it didn’t have any type of qualifier to filter the road selection. Switching to the .osm.pbf files, the other data format available on Geofabrik, yielded better results.
The Solution: PBF Files with Highway Filtering
PBF Files
PBF files are binary files founded on Google protocol buffers. These have more attributes attached to the road shapes than the Shapefiles do, including a "highway" attribute.
While at first glance that piece of data would seem to indicate all of these roads are highways (which in the United States are the primary roads, such as interstates), instead, it is a classifier.
Filtering for Driveable Roads
Using the highway attribute, roads can be filtered to those most likely to be on TravelTime's grid. We can leave off the trails, unpaved roads, and even roads having no classification at all.
For what it's worth, this isn't a 100% solution. While using a better-crafted set of drivable roads helped immensely to cut down the problem cases, not every case was eliminated.
One case I found related to roads on a United States Army reserve, where a sufficiently-classed road was still not good enough. In that case, I had to manually find a close point further away, which resolved the issues for that set of data.
Future Improvements: Automated Validation
In the future, if computing another set of data results in similar issues, we could build a resolving command that makes an API call to TravelTime part of the verification.
Then, if a set of coordinates has proved problematic, drop that road from the filtered set and find the next best match. Rinse and repeat until the API call resolves.
We wouldn't want to do that for every point due to TravelTime rate limits, but the procedure would be much more palatable than manual intervention in each case.
Key Takeaways for Developers
The switch from Shapefiles to PBF files with highway attribute filtering solved most coordinate validation issues with TravelTime's API.
While not 100% perfect, this approach dramatically reduces manual intervention and provides a scalable solution for finding road-adjacent coordinates.
For developers working with location-based APIs that require road proximity, remember that data format choice matters.
The additional metadata in PBF files—particularly the highway classification system—provides the granular control needed to distinguish between actual drivable roads and pedestrian paths or trails that mapping APIs might reject.
Start with PBF files and highway filtering for any project requiring reliable road coordinate mapping. Your future self will thank you when you avoid the debugging rabbit holes that come with insufficient road data classification.