Skip to contents

Parse a response into a more useful form

parse_parquet2df.Rd

The collection of parse_ functions helps package developers return the desired data structure from an API response.

Usage

parse_parquet2df(response)

parse_url2df(response)

parse_url(response)

parse_json2list(response, ...)

parse_json2tibble(
  response,
  df = TRUE,
  elements = "data",
  null_action = "drop",
  validate = TRUE,
  debug = FALSE
)

parse_multi2tibble(resp)

Arguments

response

the response from the API

...

other arguments to pass to httr2::resp_body_json()

df

logical, if TRUE, we are expecting a complex structure with multiple items in the json response, see details

elements

the elements to pluck from list created by parsing json, defaults to "data"

null_action

[Deprecated] No longer used.

validate

logical, if TRUE (default), validate the response using the schema returned by the API, see details

debug

logical, if TRUE, print the request to the console, default is FALSE

resp

An httr2 response from a /multiple endpoint.

Value

desired data structure as indicated by function name

Details

The parse_ functions are designed to be used in conjunction with the api_perform function. The parse_ functions are used to convert the raw response from the API into a more useful form.

  • Convert parquet to a data.frame/tibble: parse_parquet2df

  • Download a parquet file from an export URL and return a data.frame/tibble: parse_url2df

  • Convert a URL to a string: parse_url

  • Convert JSON to a list: parse_json2list

  • Convert JSON to a tibble: parse_json2tibble

The df argument and validate will likely work together. For example, if a call is made to the counts api then we expect for most endpoints that list items schema, data, and message will be returned. We can use validate = TRUE along with df = TRUE to not only extract the data element, but to validate and coerce every column using the schema definition. If a call to a different api is made and the response is simpler then df = FALSE will likely produce the desired result.

In the case of includes or appends being part of the original function call the result will return a list column for each includes or appends element.

See also

api_get(), api_post(), api_export() for making requests

Examples

if (FALSE) { # \dontrun{
# JSON to tibble with schema validation
resp <- api_get("counts", "projects")
parse_json2tibble(resp)

# JSON to list
parse_json2list(resp)

# Parquet response to tibble
parse_parquet2df(resp)

# Export URL: prints details, returns URL invisibly
resp <- api_export("counts", "surveys", format = "parquet")
url <- parse_url(resp)

# Download parquet from an export URL
parse_url2df(resp)
} # }
if (FALSE) { # \dontrun{
resp <- api_post_multi("counts", "projects/age-classes/multiple",
  body = my_data,
  nm = "age_classes"
)
parse_multi2tibble(resp)
} # }