Interface to 'typeform' Results

An R interface to the 'typeform' < https://typeform.com> application program interface. Also provides functions for downloading your results.


BuildStatus Downloads CRAN_Status_Badge codecov.io

Typeform is a company that specializes in online form building. This R package allows users to download their form results through the exposed API (V2).

** The rtypeform package now uses V2. This is a breaking change from the previous version.**

Installation

The package can be installed from CRAN

install.packages("rtypeform")

and loaded in the usual way.

library("rtypeform")
#> This package now uses V2 of the typeform API.This update breaks ALL code (sorry, not my fault).The README provides some guidence on using the new functions.You will need to generate a new API. See the README for details.

Obtaining an API key

To use this package you need a V2 API key. It is fairly easy to obtain one. See typeform’s help page. The token will look something like

Whenever the package refers to api, this is the object it needs.

Using the package

Once you have this key, we can extract data from typeform

api = "XXXXX"
# Was get_typeforms() in V1 of the package
forms = get_forms(api)

The forms object is also contains attributes containing the total number of forms.

attr(forms, "total_items")
#> [1] 5

If you don’t pass your api key as an argument, it will attempt to read the variable typeform_api2 from your .Renviron file, via Sys.getenv("typeform_api2"). If this variable is set correctly, then you can omit the api argument

# See ?get_forms for further details
forms = get_forms()

In all function calls below, the api argument can be omitted if the environment variable is set (see Efficient R programming Chapter 2 for more details).

You can download data from a particular typeform via

# Most recent typeform
form_id = forms$form_id[1]
q = get_responses(form_id, completed = TRUE)

The object q is a list. The first element is meta that contain details on the user, such as, their platform and user_agent. The other list elements are responses to each question.

There are a number of options for downloading the data. For example

q = get_responses(form_id, completed = TRUE, page_size = 100)

See the ?get_responses() help page for other options.

Looking at the responses

Since the responses is list, we get to perform lots of map operations. I find using purrr and the tidyverse make this a bit easier. To see the question types we can use string a few map() commands together

library("tidyverse")
question_types = q[-1] %>% # Remove the meta
   map(~select(.x, type)) %>%
   map_df(~slice(.x, 1)) %>%
   pull()

Example: Multiple Filters / Order

Imagine we only want:

  • completed results, so we add the parameter completed = TRUE.
  • a maximum of 5 results, so we add the parameter page_size = 5.
  • results since 2018-01-01 11:00:00.
since = "2018-01-01 11:00:00"
# convert to date-time 
since = lubridate::ymd_hms(since)
q = get_responses(form_id, completed = TRUE, 
                  page_size = 5, since = since)

Other information

  • If you have any suggestions or find bugs, please use the github issue tracker.
  • Feel free to submit pull requests.

Development of this package was supported by Jumping Rivers

News

Version 2.0.0

  • Move to the new typeform API - breaking changes
  • Jumped to Version 2 to match the V2 API.

Version 0.4.0

  • Bug fix: Empty data frames now returned
  • Intended to the final version using the V1 data API. Added a start-up message.
  • Removed offset argument - seems to be broken at the typeform end.

Version 0.3.3

  • More consistent response with get_typeforms().
  • Bug fix: Return an empty data frame when there are no typeforms (very edge case).
  • Bug fix: typeform API insists on integers for times; so use times.

Version 0.3.2

  • Bug fix: Return an empty data frame when there are no completed responses.
  • Bug fix: Parse hidden fields correctly

Version 0.3.1

  • Improved error messages for http status codes.
  • More consistent response with get_questionnaire().

Version 0.3.0

  • Breaking changes to the API. get_results() now depreciated. Instead, use get_questionnaire(). This returns a list with http_status, question stats, questions, completed, and uncompleted responses (thanks to @hrbrmstr).

Version 0.2.1

  • Adding automatic type conversion in the get_results() function (thanks to @1beb).

Version 0.2.0

  • Adding user agent to API call.
  • Better error handling.
  • Export get_api function.

Version 0.1.1

  • Minor tweaks for CRAN.

Version 0.1.0

  • Initial release.

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.

install.packages("rtypeform")

2.0.0 by Colin Gillespie, 3 months ago


https://github.com/csgillespie/rtypeform


Report a bug at https://github.com/csgillespie/rtypeform/issues


Browse source code at https://github.com/cran/rtypeform


Authors: Colin Gillespie [aut, cre]


Documentation:   PDF Manual  


GPL-2 | GPL-3 license


Imports jsonlite, httr, purrr, utils, tibble, dplyr, glue, lubridate, tidyr

Suggests testthat


See at CRAN