Type: Package
Title: Access 'Google Charts' Map Data
Version: 1.0.1
Description: Connects to the 'Google Charts' geographic data resources described in https://developers.google.com/chart/interactive/docs/gallery/geochart, allowing the user to download contents to use as a reference for related services like 'Google Trends'.
License: GPL-3
URL: https://github.com/odeleongt/gchartsmap
Imports: httr, jsonlite, sf, tigris
Encoding: UTF-8
RoxygenNote: 7.3.2
Depends: R (≥ 4.2.0)
Suggests: testthat (≥ 3.0.0)
Config/testthat/edition: 3
BugReports: https://github.com/odeleongt/gchartsmap/issues
NeedsCompilation: no
Packaged: 2025-07-19 13:25:26 UTC; r11665
Author: Oscar de Leon ORCID iD [aut, cre, cph]
Maintainer: Oscar de Leon <odeleon@emory.edu>
Repository: CRAN
Date/Publication: 2025-07-19 13:50:02 UTC

gchartsmap: Access 'Google Charts' Map Data

Description

Connects to the 'Google Charts' geographic data resources described in https://developers.google.com/chart/interactive/docs/gallery/geochart, allowing the user to download contents to use as a reference for related services like 'Google Trends'.

Author(s)

Maintainer: Oscar de Leon odeleon@emory.edu (ORCID) [copyright holder]

See Also

Useful links:

Get available areas

Description

Get a list of areas that have been downloaded

Usage

gchart_available_areas(
  type = c("countries", "us-areas"),
  cache = gchart_get_cache_path()
)

Arguments

type

Type of geo-resource. Defaults to countries.

cache

Path where the downloaded data is stored.

Verify cache directory

Description

Ensure that the cache directory exists

Usage

gchart_cache_dir(
  path = tools::R_user_dir(package = "gchartsmap", which = "cache")
)

Arguments

path

Path to verify

Extracts the list of available countries from the Google Charts documentation

Description

Extracts the list of available countries from the Google Charts documentation

Usage

gchart_countries(
  server = "https://developers.google.com/chart/interactive/docs/gallery/geochart",
  cache = gchart_get_cache_path(),
  format = c("rds", "rda"),
  update = FALSE,
  verbose = TRUE
)

Arguments

server

Location for the relevant Google Charts documentation. Use the default.

cache

Path to store downloaded data.

format

Which format to use for storing the countries table.

update

Whether to update the table even if it is cached.

verbose

Whether to show messages during processing.

Details

Extracts the information of countries available in the Google Charts geochart service from the online documentation

Value

A data.frame with information for all countries available in the service.

Generate Google Charts spatial data for all countries

Description

This function queries 'Google Charts' resources to identify countries for which geographical data is available, and generates the simple features for local use.

Usage

gchart_generate_countries(
  countries = "all",
  server = "https://www.gstatic.com/charts/geochart/10/mapfiles/",
  cache = gchart_get_cache_path(),
  verbose = TRUE
)

Arguments

countries

Which countries to process. Defaults to "all". Use country codes from gchartsmap::gchart_countries()

server

Google geochart server to access.

cache

Path to store downloaded data.

verbose

Whether to show messages during processing.

Value

Returns a simple features 'data.frame' with class 'sf', representing the spatial data for all countries from the Google Charts servers, using the WGS84 (epsg = 4326) coordinate reference system. You need to first run 'gchart_set_cache()' so the package knows where to store the downloaded data.

Examples


library(package = "gchartsmap")

# set the cache path to your system's cache path
gchartsmap::gchart_set_cache(path = tempdir())

# GET and process all countries
gchartsmap::gchart_generate_countries(countries = "GT")

# clean up
list.files(
  tempdir(), all.files = TRUE, full.names = TRUE, recursive = TRUE
)

Generate Google Charts spatial data for US areas

Description

This function queries 'Google Charts' resources to identify the US geographic areas used in services like Google Trends, and uses geographic data from the US Census Bureau to provide those areas with subdivisions at the county level.

Usage

gchart_generate_us_areas(areas = 1:1000L, limit = 1000)

Arguments

areas

Area codes to get. Should be integers.

limit

Maximum number of areas to look for.

Value

Returns a simple features 'data.frame' with class 'sf', representing the spatial data for all areas with a valid id between 1 and a 1000 from the Google Charts servers, using the WGS84 (epsg = 4326) coordinate reference system. You need to first run 'gchart_set_cache()' so the package knows where to store the downloaded data.

Examples


library(package = "gchartsmap")

# set the cache path to your system's cache path
gchartsmap::gchart_set_cache(path = tempdir())

# GET and process area 500
gchartsmap::gchart_generate_us_areas(500L)

# clean up
list.files(
  tempdir(), all.files = TRUE, full.names = TRUE, recursive = TRUE
)

Get the cache path

Description

Get the saved cache path

Usage

gchart_get_cache_path(path = NULL)

Arguments

path

Path to use as cache

Value

Returns the path to the local cache as set in the 'R_GOOGLE_CHART_CACHE' environment variable. If that is not set, gets the system's default cache path for the package as provided by 'tools::R_user_dir()'.

Examples


library(package = "gchartsmap")

# set the cache path to a temp folder
gchartsmap::gchart_set_cache(path = tempdir())

# check the set cache
gchartsmap::gchart_get_cache_path()

Get Google Charts data for countries

Description

Access the Google Charts geochart data for countries

Usage

gchart_get_countries(
  countries = "all",
  server = "https://www.gstatic.com/charts/geochart/10/mapfiles/",
  cache = gchart_get_cache_path(),
  verbose = FALSE
)

Arguments

countries

Country codes to get.

server

Google geochart server to access.

cache

Path to store downloaded data.

verbose

Whether to show messages during processing.

Details

The function invisibly returns the file path for successful requests or the response status code for failed requests, in a character vector with the country code for each element.

Get Google Charts data for US areas

Description

Access the Google Charts geochart data for US areas

Usage

gchart_get_us_areas(
  areas,
  server = "https://www.gstatic.com/charts/geochart/10/mapfiles/",
  cache = gchart_get_cache_path(),
  limit = 1000
)

Arguments

areas

Area codes to get. Should be integers.

server

Google geochart server to access.

cache

Path to store downloaded data.

limit

Maximum number of areas to look for

Details

The function invisibly returns the file path for successful requests or the response status code for failed requests, in a character vector with the area name for each element.

Process Google Charts data for US areas

Description

Process the downloaded Google Charts geochart data for US areas

Usage

gchart_process_areas(
  areas,
  type = c("countries", "us-areas"),
  cache = gchart_get_cache_path()
)

Arguments

areas

Area codes to get. Should be integers. If not provided, all available areas are processed.

type

Type of geo-resource. Defaults to countries.

cache

Path where the downloaded data is stored.

Details

Google Charts data is served as JavaScript code that defines objects with the desired data. This function processes the locally-available Google Charts js files to generate spatial objects.

Delete a saved cache path

Description

This function will uninstall the cache path from the environment variables. If a path is provided, it will be used to remove the variable from .Renviron file in that path.

Usage

gchart_remove_cache_path(remove = FALSE, path = NULL)

Arguments

remove

Whether to remove the path.

path

Path to look for an .Renviron file.

Set up a cache directory

Description

Ensures that the directory exists and sets the environment variable for access.

Usage

gchart_set_cache(
  path = tools::R_user_dir(package = "gchartsmap", which = "cache"),
  install = FALSE,
  overwrite = FALSE,
  home = "HOME"
)

Arguments

path

Path to use for the package cache.

install

if TRUE, will install the cache path in your .Renviron file for use in future sessions. Defaults to FALSE.

overwrite

If this is set to TRUE, it will overwrite an existing cache path that you already have in your .Renviron file.

home

Path for the .Renviron file. Defaults to "HOME".

Value

Sets and returns the path to the cache where downloaded data will be stored. Is used for the side effect of setting the 'R_GOOGLE_CHART_CACHE' environment variable, and can store the path in '.Renviron' for use in future R sessions if requested.

Examples


library(package = "gchartsmap")

# set the cache path to a temp folder
gchartsmap::gchart_set_cache(path = tempdir())


# save the cache path in a temporary folder
# if you want to save the cache path in your default .Renviron,
# use the default for path
gchartsmap::gchart_set_cache(
  install = TRUE, path = tempdir(), overwrite = TRUE, home = tempdir()
)

# clean up
list.files(
  tempdir(), all.files = TRUE, full.names = TRUE, pattern = ".Renv"
) |>
 unlink()

Find existing path

Description

Find the deepest path component that exists.

Usage

path_existing_root(path)

Arguments

path

Path to analyze.