## 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. > [!NOTE] > **Tip: Reducing holes in polygons** > Because isochrones calculate reachability using the actual road network, areas with sparse roads, such as large parks, unmapped private areas, or industrial zones, can naturally appear as inaccessible "holes" inside the generated polygon. If your use case requires a solid, generalized coverage area without these gaps, explicitly set the `polygonFidelity` to `MEDIUM` or `LOW`. - **`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.