5 Practical KMLCircle Examples for Mapping Projects

KMLCircle: Creating Accurate Map Circles in KML

When displaying geographic data on maps, circles are a common and useful geometry — for marking buffer zones, area-of-effect radii, or proximity searches. KML (Keyhole Markup Language) does not include a native circle primitive, but you can create accurate map circles in KML by approximating them with polygons made of many points placed along the circle’s circumference. This article explains the math, implementation details, and practical tips to generate precise KML circles for use in Google Earth, Google Maps (via KML support), and other KML-capable viewers.

Why KML needs an approximation

KML supports Polygons and LinearRings, which are closed sequences of latitude/longitude coordinates. To represent a circle, you compute a set of coordinates around a center point at equally spaced bearings and a fixed distance (the circle radius), then connect them to form a polygon. More vertices produce a smoother, more accurate circle at the cost of larger KML files.

Spherical vs. planar calculations

Earth is (approximately) a sphere/oblate spheroid. For small radii (under a few kilometers), planar approximations can be acceptable, but for larger radii or high-precision needs, compute coordinates using great-circle (geodesic) formulas (haversine/inverse formulas) or use a library that supports geodesic direct problems (e.g., GeographicLib). This article uses the spherical Earth great-circle direct formula for clarity and wide compatibility.

Constants and notation:

• R = 6371000 meters (mean Earth radius)
• φ1 = center latitude in radians
• λ1 = center longitude in radians
• d = radius (meters)
• θ = bearing (radians), from 0 to 2π

Direct (forward) great-circle formula to compute destination point given start point, bearing, and distance:

• φ2 = asin( sin φ1cos(d/R) + cos φ1 * sin(d/R) * cos θ )
• λ2 = λ1 + atan2( sin θ * sin(d/R) * cos φ1, cos(d/R) − sin φ1 * sin φ2 )

Convert φ2 and λ2 back to degrees for KML.

Step-by-step algorithm

1. Choose center latitude and longitude (degrees) and radius d (meters).
2. Decide number of segments N — more segments = smoother circle. Reasonable defaults:
   • 36 (every 10°) for coarse circles
   • 72 (every 5°) for medium quality
   • 180 (every 2°) or higher for high quality or large radii
3. Convert center lat/lon to radians.
4. For i from 0 to N (inclusive) compute θ = 2π * i / N and apply the direct formula to get φ2, λ2.
5. Convert φ2, λ2 to degrees and append as “lon,lat,alt” coordinate strings for the KML LinearRing (alt optional; use 0 or leave blank).
6. Close the ring by repeating the first coordinate at the end.
7. Wrap coordinates in KML Polygon and style as desired.

Example: JavaScript function

javascript
Copy CodeCopied
// Uses radians/degrees helpers
function toRad(deg){return degMath.PI/180;}
function toDeg(rad){return rad180/Math.PI;}

function kmlCircleCoordinates(lat, lon, radiusMeters, segments=72){
  const R = 6371000; // earth radius in meters
  const φ1 = toRad(lat);
  const λ1 = toRad(lon);
  const dR = radiusMeters / R;
  const coords = [];
  for(let i=0;i<=segments;i++){
    const θ = 2Math.PI  i / segments;
    const φ2 = Math.asin(Math.sin(φ1)Math.cos(dR) + Math.cos(φ1)Math.sin(dR)Math.cos(θ));
    const λ2 = λ1 + Math.atan2(Math.sin(θ)Math.sin(dR)Math.cos(φ1),
                               Math.cos(dR)-Math.sin(φ1)Math.sin(φ2));
    coords.push(</span><span class="token template-string interpolation interpolation-punctuation" style="color: rgb(57, 58, 52);">${</span><span class="token template-string interpolation" style="color: rgb(57, 58, 52);">toDeg</span><span class="token template-string interpolation" style="color: rgb(57, 58, 52);">(</span><span class="token template-string interpolation">λ</span><span class="token template-string interpolation" style="color: rgb(54, 172, 170);">2</span><span class="token template-string interpolation" style="color: rgb(57, 58, 52);">)</span><span class="token template-string interpolation interpolation-punctuation" style="color: rgb(57, 58, 52);">}</span><span class="token template-string" style="color: rgb(163, 21, 21);">,</span><span class="token template-string interpolation interpolation-punctuation" style="color: rgb(57, 58, 52);">${</span><span class="token template-string interpolation" style="color: rgb(57, 58, 52);">toDeg</span><span class="token template-string interpolation" style="color: rgb(57, 58, 52);">(</span><span class="token template-string interpolation">φ</span><span class="token template-string interpolation" style="color: rgb(54, 172, 170);">2</span><span class="token template-string interpolation" style="color: rgb(57, 58, 52);">)</span><span class="token template-string interpolation interpolation-punctuation" style="color: rgb(57, 58, 52);">}</span><span class="token template-string" style="color: rgb(163, 21, 21);">,0</span><span class="token template-string template-punctuation" style="color: rgb(163, 21, 21);">);
  }
  return coords.join(’ ‘);
}

Example KML polygon snippet

xml
Copy CodeCopied
<Placemark>
  <name>Circle: 1 km radius</name>
  <Style>
    <LineStyle><color>ff0000ff</color><width>2</width></LineStyle>
    <PolyStyle><color>7fff0000</color></PolyStyle>
  </Style>
  <Polygon>
    <outerBoundaryIs>
      <LinearRing>
        <coordinates>
          
          -122.084,37.422,0 -122.083,37.423,0 … -122.084,37.422,0         </coordinates>
      </LinearRing>
    </outerBoundaryIs>
  </Polygon>
</Placemark>

Practical tips

• Segment count: increase with circle radius and latitude (meridians converge near poles). For most uses, 72–180 segments balance smoothness and file size.
• Performance: for many circles, consider simplifying small ones when zoomed out, or render circles client-side (e.g., with Canvas or vector tiles) instead of shipping large KML files.
• Altitude: if you use altitudeMode=“relativeToGround” or absolute, include an altitude value and set tessellate appropriately if you want the polygon to follow terrain.
• Precision: use double precision in calculations and output coordinates with at least 6 decimal places for meter-level accuracy.
• Libraries: for highest accuracy over long distances, use geodesic libraries (GeographicLib, PROJ, pyproj) which account for ellipsoidal Earth.

Troubleshooting

• Holes or self-intersections: ensure points are ordered consistently (clockwise/counterclockwise) and ring is closed. Use N≥36 to avoid visible faceting.
• Distortion near poles: limit usage or switch to appropriate map projections or geodesic libraries.
• KML viewers show straight-line interpolation: KML linear rings connect points directly; add more points to smooth curved appearance.

Conclusion

Creating accurate circles in KML is straightforward: compute geodesic points around a center and output a closed LinearRing as a Polygon. Choose an appropriate segment count and geodesic method for the desired accuracy. Use client-side rendering or geodesic libraries for large-scale or high-precision needs.