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.

  • polygon_fidelity: Resolution. Controls the size of the underlying grid cells (S2 cells) used to calculate the reachable area.
    • LOW: Uses larger grid cells. Best for covering large areas without gaps, resulting in a generalized shape.
    • MEDIUM: Balanced precision.
    • HIGH: Uses smaller grid cells. Results in a tighter fit to the road network but may produce empty areas or "holes" where the road network is sparse.
    • Default: If unspecified, the service dynamically selects the fidelity based on the requested travel duration.
  • enable_smoothing: The aesthetic. Controls whether the sharp edges of the grid cells defined by the fidelity are rounded off.
    • false (Raw): Returns the exact geometric calculation. Edges appear jagged or stepped, reflecting the grid cells. Best for analytical accuracy, such as strict point-in-polygon tests.
    • true (Smoothed): Applies a post-processing algorithm to round off the corners. Best for visual display on maps.

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 can contain thousands of coordinates and payloads can be between 300 and 500 kilobytes.

  • Bandwidth: Be aware that the JSON response size is significant for maximum duration requests.
  • Rendering: Rendering extremely detailed polygons impacts performance. Consider using the enable_smoothing parameter or client-side simplification libraries to reduce the vertex count for display.

Error handling

Implement retry logic with exponential backoff for 5xx server errors. However, do not retry 4xx client errors without changing your parameters:

  • INVALID_ARGUMENT (400): Check that your duration is positive and within the limit for the selected mode, which is at most 3,600 seconds for DRIVE, or 7,200 seconds for other modes.
  • NOT_FOUND (404): The origin point failed to snap to a road. Try moving the coordinate closer to a known street or ensuring the region is supported.