jsonlite: fromJSON – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

fromJSON

Convert R objects to/from JSON

Description

These functions are used to convert between JSON data and R objects. The toJSON and fromJSON functions use a class based mapping, which follows conventions outlined in this paper: https://arxiv.org/abs/1403.2805 (also available as vignette).

Usage

fromJSON(
  txt,
  simplifyVector = TRUE,
  simplifyDataFrame = simplifyVector,
  simplifyMatrix = simplifyVector,
  flatten = FALSE,
  ...
)

toJSON(
  x,
  dataframe = c("rows", "columns", "values"),
  matrix = c("rowmajor", "columnmajor"),
  Date = c("ISO8601", "epoch"),
  POSIXt = c("string", "ISO8601", "epoch", "mongo"),
  factor = c("string", "integer"),
  complex = c("string", "list"),
  raw = c("base64", "hex", "mongo", "int", "js"),
  null = c("list", "null"),
  na = c("null", "string"),
  auto_unbox = FALSE,
  digits = 4,
  pretty = FALSE,
  force = FALSE,
  ...
)

Arguments

`txt`	a JSON string, URL or file
`simplifyVector`	coerce JSON arrays containing only primitives into an atomic vector
`simplifyDataFrame`	coerce JSON arrays containing only records (JSON objects) into a data frame
`simplifyMatrix`	coerce JSON arrays containing vectors of equal mode and dimension into matrix or array
`flatten`	automatically `flatten` nested data frames into a single non-nested data frame
`...`	arguments passed on to class specific `print` methods
`x`	the object to be encoded
`dataframe`	how to encode data.frame objects: must be one of 'rows', 'columns' or 'values'
`matrix`	how to encode matrices and higher dimensional arrays: must be one of 'rowmajor' or 'columnmajor'.
`Date`	how to encode Date objects: must be one of 'ISO8601' or 'epoch'
`POSIXt`	how to encode POSIXt (datetime) objects: must be one of 'string', 'ISO8601', 'epoch' or 'mongo'
`factor`	how to encode factor objects: must be one of 'string' or 'integer'
`complex`	how to encode complex numbers: must be one of 'string' or 'list'
`raw`	how to encode raw objects: must be one of 'base64', 'hex' or 'mongo'
`null`	how to encode NULL values within a list: must be one of 'null' or 'list'
`na`	how to print NA values: must be one of 'null' or 'string'. Defaults are class specific
`auto_unbox`	automatically `unbox` all atomic vectors of length 1. It is usually safer to avoid this and instead use the `unbox` function to unbox individual elements. An exception is that objects of class `AsIs` (i.e. wrapped in `I()`) are not automatically unboxed. This is a way to mark single values as length-1 arrays.
`digits`	max number of decimal digits to print for numeric values. Use `I()` to specify significant digits. Use `NA` for max precision.
`pretty`	adds indentation whitespace to JSON output. Can be TRUE/FALSE or a number specifying the number of spaces to indent. See `prettify`
`force`	unclass/skip objects of classes with no defined JSON mapping

Details

The toJSON and fromJSON functions are drop-in replacements for the identically named functions in packages rjson and RJSONIO. Our implementation uses an alternative, somewhat more consistent mapping between R objects and JSON strings.

The serializeJSON and unserializeJSON functions in this package use an alternative system to convert between R objects and JSON, which supports more classes but is much more verbose.

A JSON string is always unicode, using UTF-8 by default, hence there is usually no need to escape any characters. However, the JSON format does support escaping of unicode characters, which are encoded using a backslash followed by a lower case "u" and 4 hex characters, for example: "Z\u00FCrich". The fromJSON function will parse such escape sequences but it is usually preferable to encode unicode characters in JSON using native UTF-8 rather than escape sequences.

References

Jeroen Ooms (2014). The jsonlite Package: A Practical and Consistent Mapping Between JSON Data and R Objects. arXiv:1403.2805. https://arxiv.org/abs/1403.2805

Examples

# Stringify some data
jsoncars <- toJSON(mtcars, pretty=TRUE)
cat(jsoncars)

# Parse it back
fromJSON(jsoncars)

# Parse escaped unicode
fromJSON('{"city" : "Z\\u00FCrich"}')

# Decimal vs significant digits
toJSON(pi, digits=3)
toJSON(pi, digits=I(3))

## Not run: 
#retrieve data frame
data1 <- fromJSON("https://api.github.com/users/hadley/orgs")
names(data1)
data1$login

# Nested data frames:
data2 <- fromJSON("https://api.github.com/users/hadley/repos")
names(data2)
names(data2$owner)
data2$owner$login

# Flatten the data into a regular non-nested dataframe
names(flatten(data2))

# Flatten directly (more efficient):
data3 <- fromJSON("https://api.github.com/users/hadley/repos", flatten = TRUE)
identical(data3, flatten(data2))

## End(Not run)

jsonlite

A Simple and Robust JSON Parser and Generator for R

v1.7.2

MIT + file LICENSE

Authors

Jeroen Ooms [aut, cre] (<https://orcid.org/0000-0002-4035-0289>), Duncan Temple Lang [ctb], Lloyd Hilaiel [cph] (author of bundled libyajl)

Initial release