## How do I calculate an inbound "commute-to-work" isochrone (traveling *to* a destination) versus an outbound isochrone (traveling *from* an origin)? Both inbound and outbound calculations are supported in the v1 API using the `travelDirection` (`travel_direction`) parameter: - `FROM` (Outbound): Calculates the area reachable `from` the origin point within the specified time limit. This is suitable for use cases like delivery zones or service coverage. - `TO` (Inbound): Calculates the area from which you can travel `to` the origin point within the specified time limit. This is suitable for applications like commute-to-work features or determining catchment zones around a central office or transit hub. > [!NOTE] > **Note:** `FROM` and `TO` polygons for the same origin and duration can be asymmetric in every mode. For `DRIVE`, `TWO_WHEELER`, and `BICYCLE`, causes include one-way streets and turn restrictions. For `DRIVE` and `TWO_WHEELER`, highway on-ramps, off-ramps, and directional traffic congestion also contribute. For `WALK` and `BICYCLE`, slope also matters because travel uphill is slower than downhill. ## How do the four travel modes (`DRIVE`, `TWO_WHEELER`, `BICYCLE`, and `WALK`) differ? Each mode uses its own road network access rules, turn costs, and speed model: - `DRIVE`: Traverses drivable roads using posted or free-flow speeds or live traffic speeds (`TRAFFIC_AWARE`), up to 3,600 seconds (60 minutes). - `TWO_WHEELER`: Traverses roads accessible to motorized two-wheelers with lower modeled speeds than `DRIVE` on high-speed roads and optional `TRAFFIC_AWARE` routing, up to 3,600 seconds (60 minutes). As a result, a `TWO_WHEELER` isochrone is larger than `BICYCLE` but smaller than `DRIVE` along high-speed highways. - `BICYCLE`: Traverses bike-accessible streets, bike lanes, and paths with speeds adjusted for road type and slope (excluding motorways and freeways), up to 7,200 seconds (120 minutes). - `WALK`: Traverses pedestrian sidewalks, trails, and streets with walking speed adjusted for slope (ignoring one-way vehicular restrictions), up to 7,200 seconds (120 minutes). ## Does the Isochrones API include ferries or water crossings? No. The Isochrones API traverses road, bridge, tunnel, and pathway connections only. Ferry routes and water transit crossings are excluded across all travel modes. Islands or peninsulas connected only by ferry won't be included in an isochrone generated from the mainland. ## Sometimes the returned polygon looks blocky or has jagged, stepped edges, especially for longer durations. Why does the level of detail change? Isochrones API dynamically adjusts the resolution of its spatial calculation grid based on the requested `travel_duration` and `travel_mode`: - Shorter Durations: Use a highly refined, high-resolution grid because the total area is small, resulting in a detailed boundary. - Longer Durations: Transition to a coarser, lower-resolution grid to cover the vast geographic area efficiently without causing severe latency. You can set the optional `polygon_fidelity` to `HIGH`, `MEDIUM`, or `LOW` if you require a specific, consistent level of detail regardless of duration. ## Why does requesting an isochrone for a coordinate inside a park, lake, or large industrial complex sometimes return a "Not Found" error? Isochrones API calculates travel times using roads and pathways. The API must "snap" the point to the nearest compatible segment before starting the calculation if your requested origin coordinates are not located on a recognized road. Each travel mode has a maximum snapping distance of about 200 meters or less. `WALK` and `BICYCLE` use shorter distances than `DRIVE` and `TWO_WHEELER`, and `DRIVE` and `TWO_WHEELER` ignore pedestrian-only paths. If your origin coordinate lies further from a valid, mode-compatible road segment than this distance, snapping fails, and the API returns a `NOT_FOUND` error. To resolve this, ensure your coordinates are positioned close to a public street or pathway. ## Why do I get an error when requesting traffic-aware routing for walking or cycling? Live traffic conditions (`TRAFFIC_AWARE`) are supported for the `DRIVE` and `TWO_WHEELER` travel modes. If you attempt to request an isochrone for `WALK` or `BICYCLE` with `routingPreference` set to `TRAFFIC_AWARE`, the API returns a `400 INVALID_ARGUMENT` error. ## When I render the GeoJSON response on my map, the shape is displayed in the wrong place, is distorted, or fails to render. What is causing this? This is almost always caused by a coordinate order mismatch. Following the GeoJSON standard (RFC 7946), Isochrones API returns coordinates in the order of `[longitude, latitude]`. However, many mapping SDKs and custom geometry objects expect coordinates in the order of `[latitude, longitude]`. If your map rendering is incorrect, check how your map SDK handles GeoJSON: - **Google Maps JavaScript API:** If you are using the Data Layer (`map.data.addGeoJson()`), this order is handled natively and no action is required. - **Custom objects or other SDKs:** If you are manually parsing the response into `LatLng` objects, you must loop through the coordinates in the GeoJSON payload and transpose the `[lng, lat]` values into `[lat, lng]` pairs before rendering. ## Why are there hollow "holes" inside my isochrone polygon, and can I get a solid shape instead? Holes represent areas with no reachable roads within the time limit. This is common in regions with large forests, water bodies, airports, or private properties where vehicles or pedestrians cannot travel. The external v1 API does not expose a parameter to automatically remove holes. If your application requires a solid boundary, for example, to perform point-in-polygon containment checks, you can: - Set the `polygon_fidelity` parameter to `MEDIUM` or `LOW` to encourage the algorithm to generalize and merge over these internal gaps. - Use a client-side GIS library (such as Turf.js) to parse the GeoJSON and extract only the first coordinate ring (the exterior shell), discarding any subsequent interior rings (the holes). ## Should I enable the enable_smoothing option for backend spatial analysis? No. The `enable_smoothing` parameter is designed purely for visual aesthetics. It rounds off the sharp corners of the underlying calculation grid to make the shape look organic on a map. Smoothing is not recommended for precise spatial analysis because it alters the vertices and shifts the boundaries slightly. For backend calculations, database queries, or point-in-polygon tests, keep `enable_smoothing` set to `false` to ensure you're using the mathematically precise calculated boundary.