README.md

In afsarchowdhury/g4sr: Go4Schools API Wrapper

g4sr

{g4sr} is an R API wrapper for Go4Schools. It allows you to manage your school’s data. Authentication is required for all requests. See your school’s administrator for an API key. It should look something like this:

thisISyourAPIkeyITlooksLIKEaLONGstringOFlettersANDnumbers

Note

I am in no way affiliated with Go4Schools. I am an end user of their API who happens to use R.

There are some API calls that are yet to be included. The only reason for their absence is that I have not needed to use them yet.

Installation

Install the development version using {devtools} by typing the following:

# Install devtools if needed
install.packages("devtools")

# Install g4sr using devtools
devtools::install_github("afsarchowdhury/g4sr")

A CRAN version is unavailable at this time.

Setup for beginners

If you have never used R before, or you only ever use it once or twice a year, the following is your best option:

# Load the g4sr package
library(g4sr)

# Run setup
gfs_setup()

You will be prompted to enter your API key in the console. This is needed before any of the functions can be used.

Setup for more advanced users

If you are a more advanced user, you may wish to store your API key so that you don’t have to re-enter it every time you start a new session. Best practice is to set the API key as an environment variable for your system and then call it in R using Sys.getenv(). If you set the parameter in .Renviron, it is permanently available to your R sessions. Be aware: if you are using version control, you do not want to commit the .Renviron file in your local directory. Either edit your global .Renviron file, or make sure that .Renviron is added to your .gitignore file.

Open the .Renviron file and add the following line:

G4SR_KEY=thisISyourAPIkeyITlooksLIKEaLONGstringOFlettersANDnumbers

Restart your R session and test to make sure the key has been added using the command:

Sys.getenv("G4SR_KEY")

You should see your API key printed in the console. If this works, you can do the following:

library(g4sr)
#> You will need a valid API key to access the functions in this pacakge.
#> Ask your school administrator to generate one for you.
#> Log errors and bugs at https://github.com/afsarchowdhury/g4sr/issues.
#> Type citation('g4sr') to cite g4sr in a publication.
#> 
#> 
gfs_setup(api_key = Sys.getenv("G4SR_KEY"))

Example 1

To return details of the school and the available academic years:

# Load g4sr if you have not already
library(g4sr)

# Setup g4sr using your chosen method
gfs_setup()

# Return list of available academic years
gfs_school()

You should see a printout in the console, looking something like this:

#> Status code: 200
#> $code
#> [1] "SCHOOLCODE"
#> 
#> $name
#> [1] "School Name"
#> 
#> $academic_years
#>  [1] 2021 2020 2019 2018 2017 2016 2015 2014 2013 2012
#> 
#> $current_academic_year
#> [1] 2021

Anything other than a status code 200 means there was an error along the way. See https://www.go4schools.com/Documentation/V1/APIDocumentation.html#errors to identify the error if you get one.

Example 2

To return the school calendar for the academic year 2020:

my_cal <- gfs_calendar(academicYear = 2020)
#> Request calendar for 2020
#> 
#> Status code: 200
#> 
head(my_cal)
#>   timetable_id week                 date day_type_code
#> 1         <NA> <NA> 2019-09-02T00:00:00Z      TRAINING
#> 2        10202    1 2019-09-03T00:00:00Z          OPEN
#> 3        10202    1 2019-09-04T00:00:00Z          OPEN
#> 4        10202    1 2019-09-05T00:00:00Z          OPEN
#> 5        10202    1 2019-09-06T00:00:00Z          OPEN
#> 6         <NA> <NA> 2019-09-07T00:00:00Z        CLOSED

License

{g4sr} is released on a GPLv3 license.

Citation

citation("g4sr")
#> To cite g4sr in publications use:
#> 
#>   Chowdhury, A. (2020). g4sr: Go4Schools R API Wrapper. version 0.7.5.
#>   https://github.com/afsarchowdhury/g4sr
#> 
#> A BibTeX entry for LaTeX users is
#> 
#>   @Manual{,
#>     title = {g4sr},
#>     author = {Afsar Chowdhury},
#>     year = {2020},
#>     url = {https://github.com/afsarchowdhury/g4sr},
#>   }

afsarchowdhury/g4sr documentation built on Dec. 31, 2024, 3:13 a.m.