1 Getting Started

1.1 Installation

gePoints is hosted on GitHub. Install it with devtools:

# install.packages("devtools")
devtools::install_github("kimbridges/gePoints")

The package depends on xml2 for KML generation, readr for data import, and rlang for internal utilities. These will be installed automatically.

1.2 Your first KML file

The core workflow is three steps: build a data frame, call create_kml(), and open the output in Google Earth.

library(gePoints)
library(readr)
library(gt)

locations <- read_csv(
"text,          lat,       lon
New York City,  40.7484,  -73.9857
Paris,          48.8584,    2.2945
Sydney,        -33.8568,  151.2153"
)

gt(locations) |>
  tab_caption(caption = "Three World Cities") |>
  tab_source_note(source_note = "Coordinates: Google Maps")

create_kml(locations, "three_cities.kml")

This produces a file called three_cities.kml. Double-click it to open in Google Earth. You will see three red pushpin markers — one in Manhattan, one near the Eiffel Tower, one at the Sydney Opera House — each labeled with the city name.

1.3 What just happened

The create_kml() function did several things:

Read the data frame and found the required columns: lat and lon
Applied default styling (red pushpin, scale 1.2, white text label) to every row because no styling columns were provided
Generated the KML XML with one <Placemark> element per row
Wrote the result to three_cities.kml

The only required columns are lat and lon. Everything else — labels, colors, marker types, scaling — is optional with sensible defaults.

1.4 Required and optional columns

Column	Required	Default	Description
`lat`	yes	—	Latitude in decimal degrees
`lon`	yes	—	Longitude in decimal degrees
`text`	no	—	Label displayed next to the marker
`comment`	no	—	Text shown in the popup balloon
`color`	no	`"red"`	Marker color
`symbol`	no	`"pushpin"`	Marker type: `"pushpin"` or `"paddle"`
`symbol_scale`	no	`1.2`	Marker size (0.5–2.0 typical)
`text_color`	no	`"white"`	Label text color
`text_scale`	no	`1.0`	Label text size

1.5 Adding a comment column

The comment column populates the popup balloon that appears when you double click a marker in Google Earth:

locations <- read_csv(
"text,          lat,       lon,      comment
New York City,  40.7484,  -73.9857, Empire State Building
Paris,          48.8584,    2.2945, Eiffel Tower
Sydney,        -33.8568,  151.2153, Opera House"
)

gt(locations) |>
  tab_caption(caption = "Three Cities with Landmarks") |>
  tab_source_note(source_note = "Coordinates: Google Maps")

create_kml(locations, "cities_with_comments.kml")

preview_map(locations)

The preview_map() function produces a satellite-view Google Maps widget showing the same points that create_kml() writes to KML. Click a marker to see its comment in a popup. This is a preview — the KML file opened in Google Earth provides the full 3D experience.

Now clicking on the Paris marker in Google Earth displays “Eiffel Tower” in the information balloon. This is useful for attaching metadata — site descriptions, measurement values, dates — to individual points without cluttering the map labels.

1.6 Next steps

The next two chapters cover the full range of marker styling: symbol types and colors (Chapter 2), and text label formatting (Chapter 3). After that, Chapter 4 discusses strategies for organizing your data before calling create_kml().