A convenient interface for making requests directly to the 'Civis Platform API' < https://www.civisanalytics.com/platform/>. Full documentation available 'here' < https://civisanalytics.github.io/civis-r/>.
civis is an R package that helps analysts and developers interact with
the Civis Platform. The package includes a set of tools around common
workflows as well as a convenient interface to make requests directly to
the Civis Data Science API.
Installing and using
civis requires an API key. Instructions
for creating an API key can be found here.
All API keys have a set expiration date and so a new key will need to be
created at least every 30 days.
Once you have created an API key, you will then need to add it to your
.Renviron so the
civis package can access it.
touch ~/.Renvironopen -t ~/.Renviron
Then add the following line replacing the fake key
sadf8sadf9jasdf with the API key from your Civis Platform Profile:
After saving the
.Renviron file, you'll need to restart R/Rstudio.
.Renviron file can be created in the R user home directory,
Sys.getenv("R_USER"). Typically this is
"C:/username/Documents". Open or create
notepad and add the key as above. Save with type
all files, not
.txt. Restart R/Rstudio.
❗️ You must keep your API key secret. If you use version
control tools, ensure you do not commit
.Renviron or any scripts in which
you have hard-coded an API key.
civis package automatically generates R functions and documentation to interact with the Civis Platform when the package installs. From time to time, new API functions are added. These can be obtained immediately by re-installing the package from github:
If the dependencies are already installed (such as in docker containers), skipping dependency upgrades will be considerably faster:
devtools::install_github("civisanalytics/civis-r", upgrade_dependencies = FALSE)
civis includes functionality for both
Many useful tasks will require making multiple direct calls to the API.
civis includes a number of wrapper functions to make common tasks like IO
and modeling easier. For example, reading data from a table in
Platform is as easy as
library(civis)# Read an entire table in to memorymy_table <- "schema.tablename"df <- read_civis(my_table, database="my_database")# Run a query and read the results into memoryquery <- sql("SELECT a, b, c FROM schema.tablename WHERE b > 42")df2 <- read_civis(query, database="my_database")
civis includes many more functions for tasks like writing data to tables
and files as well as for creating reports. For more detailed documentation,
see the included vignettes:
Functions which make direct calls to the API are prefixed with the name of the
resource that the function accesses. For example, the
encapsulates all the functionality of Platform regarding users. We can make
various calls to the
users resource to get information about ourselves and our
# Data about mecivis::users_list_me()<civis_api>List of 14$ id : int 971$ name : chr "A User"$ email : chr "[email protected]"$ username : chr "a_user"$ initials : chr "AU"# ...
# Data about my teammy_team <- civis::users_list()team_members <- sapply(my_team, function(x) x$name)print(team_members) "Jean-Luc Picard" "Beverly Crusher" "Q"
Contributions to the code are very welcome! Issues and bug reports can filed through the standard Github issue interface.
R CMD checkmust pass, i.e. using
Adding the environment variable
R_CLIENT_DEV = "TRUE" to
.Renviron will prevent new API functions and documentation from being generated based on your API Key. The default generated API functions included in the package are only updated when this package releases to CRAN.
For major, potentially breaking changes, integration tests should be run with
cd tools/integration_testsRscript smoke_test.R
Note, integration tests require a valid API key to run, and my be slow.
All contributors of code should include themselves in
DESCRIPTION by adding
the following object in the
[email protected] section:
person("FirstName", "LastName", email = "[email protected]", role = "ctb")
This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.