Isochrones API best practices

Smoothing and fidelity

You can customize the appearance and precision of the output polygons using the polygon_fidelity and enable_smoothing parameters. While these options are independent, they work together to determine the final shape.

  • polygonFidelity (polygon_fidelity): Resolution. Controls the size of the underlying spatial grid cells used to calculate the reachable area.

    • LOW: Uses the largest grid cells (several hundred meters across). Best for covering large areas without gaps and minimizing vertex count, resulting in a generalized shape that can overestimate the reachable area along narrow road corridors.
    • MEDIUM: Balanced precision and payload size.
    • HIGH: Uses the smallest grid cells (roughly 100-150 meters across). Results in a tighter fit to the road network, with more vertices, but might produce interior holes where the road network is sparse.
    • Default (POLYGON_FIDELITY_UNSPECIFIED): If unspecified, the service selects the resolution automatically based on the travel mode and duration, using finer cells for short durations and for WALK, and coarser cells for long durations. To compare isochrones across different durations or travel modes, set polygonFidelity explicitly so that they use the same resolution.

    Cell sizes are approximate. Very large isochrones might be generalized further to keep the response size manageable.

  • enableSmoothing (enable_smoothing): The aesthetic. Controls whether the stepped edges of the grid cells defined by the fidelity are rounded off.
    • false (Raw): Returns the grid-aligned boundary. Edges appear jagged or stepped, reflecting the grid cells. Best for analytical accuracy, such as strict point-in-polygon tests.
    • true (Smoothed): Rounds off the corners while approximately preserving the area of each ring. Best for visual display on maps. Because the boundary no longer follows the grid cells, don't use it for strict point-in-polygon tests.

How they interact: Fidelity sets the baseline detail that the smoothing algorithm acts upon.

  • High Fidelity + Smoothing: Produces a detailed, organic-looking shape that closely follows road endings.
  • Low Fidelity + Smoothing: Produces a broad, generalized "blob" shape.

Payload size and rendering

Large isochrones (especially long-duration requests with HIGH fidelity) can contain tens of thousands of coordinates, and the uncompressed JSON response can be several hundred kilobytes or more.

  • Bandwidth: Be aware that the JSON response size is significant for maximum duration requests with high fidelity.
  • Rendering: Rendering extremely detailed polygons impacts client performance. To reduce vertex count and payload size, choose polygonFidelity: MEDIUM or LOW, or simplify the geometry on the client before rendering by using a line-simplification algorithm such as Douglas-Peucker.

Latency and client timeouts

Response latency grows with the size of the road network traversed: short durations and the WALK and BICYCLE modes are fastest, while long DRIVE and TWO_WHEELER requests (especially with TRAFFIC_AWARE) take the longest.

  • Recommended client timeout: Configure HTTP or gRPC client deadlines to at least 30 seconds so that long requests aren't aborted early by a short client timeout.

Error handling

Implement retry logic with exponential backoff and jitter for 429 RESOURCE_EXHAUSTED rate-limit responses and 5xx server errors. Don't retry 400, 403, or 404 client errors without changing your request:

  • INVALID_ARGUMENT (400): Check that travelDuration is between 1s and 3600s (DRIVE/TWO_WHEELER) or 7200s (WALK/BICYCLE), location isn't omitted and isn't (0, 0) (or place is a valid place ID), and TRAFFIC_AWARE is only used with DRIVE or TWO_WHEELER. An omitted latitude or longitude is treated as 0.0, so omitting only one of them usually doesn't cause a 400 error (unless the other value is also 0.0). Double-check both values if the isochrone appears in the wrong place.
  • PERMISSION_DENIED (403): Verify that your API key or OAuth token is included and that the Isochrones API and billing are enabled on your Google Cloud project.
  • NOT_FOUND (404): The place couldn't be resolved to a location, or the origin couldn't be snapped to a nearby road usable by the travel mode (within about 200 meters, or less for WALK and BICYCLE).
  • RESOURCE_EXHAUSTED (429): Your project exceeded the per-minute request quota (default 300 QPM). Retry with exponential backoff.