rdb_by_api_link.R 5.38 KB
Newer Older
1
#' Download DBnomics data using API link (deprecated).
2
3
#'
#' \code{rdb_by_api_link} downloads data series from
4
#' \href{https://db.nomics.world/}{DBnomics}.
5
6
#'
#' This function gives you access to hundreds of millions data series from
7
#' \href{https://api.db.nomics.world/}{DBnomics API} (documentation about
8
#' the API can be found \href{https://api.db.nomics.world/v22/apidocs}{here}).
9
10
#' The API link is given on the
#' \href{https://db.nomics.world/}{DBnomics website}.
11
12
#'
#' @param api_link Character string. DBnomics API link of the search.
13
#' @param use_readLines Logical (default \code{FALSE}). If \code{TRUE}, then
14
15
16
#' the data are requested and read with the base function \code{readLines} i.e.
#' through the default R internet connection. This can be used to get round the
#' error \code{Could not resolve host: api.db.nomics.world}.
17
#' @param curl_config Named list (default \code{NULL}). If not
18
#' \code{NULL}, it is used to configure a proxy connection. This
19
#' configuration is passed to the function \code{curl_fetch_memory} of the package
20
21
#' \pkg{curl}. A temporary \code{curl_handle} object is created internally
#' with arguments equal to the provided list in \code{curl_config}.\cr
22
#' For \code{curl_fetch_memory} arguments see \code{\link[curl]{curl_fetch}}.
23
24
25
#' For available curl options see \code{\link[curl]{curl_options}},
#' \code{names(curl_options())} and
#' \href{https://curl.haxx.se/libcurl/c/curl_easy_setopt.html}{libcurl}.
26
#' @param filters List (default \code{NULL}). This argument must be a named
27
28
29
#' list for one filter because the function \code{toJSON} of the package \pkg{jsonlite}
#' is used before sending the request to the server. For multiple filters,
#' you have to provide a list of valid filters (see examples).\cr
30
31
#' A valid filter is a named list with an element \code{code} which is a character string,
#' and an element \code{parameters} which is a named list with elements \code{frequency}
32
#' and \code{method} or a NULL.
33
#' @return A \code{data.table}.
34
#' @examples
35
#' \dontrun{
36
#' # Fetch two series from different datasets of different providers :
37
38
#' df1 <- rdb_by_api_link(
#'   paste0(
39
40
#'     "https://api.db.nomics.world/v22/",
#'     "series?observations=1&series_ids=AMECO/ZUTN/EA19.1.0.0.0.ZUTN,IMF/CPI/A.AT.PCPIT_IX"
41
42
#'   )
#' )
43
#' 
44
#' # Fetch one series from the dataset 'Doing Business' of WB provider :
45
46
#' df2 <- rdb_by_api_link(
#'   paste0(
47
48
49
#'     "https://api.db.nomics.world/v22/series/WB/DB?dimensions=%7B%22",
#'     "indicator%22%3A%5B%22IC.REG.PROC.FE.NO%22%5D%7D&q=Doing%20Business",
#'     "&observations=1&format=json&align_periods=1&offset=0&facets=0"
50
51
52
#'   )
#' )
#' 
53
54
#' 
#' ## Use a specific proxy to fetch the data
55
#' # Fetch one series from the dataset 'Doing Business' of WB provider :
56
57
58
59
60
61
62
63
64
#' h <- list(
#'   proxy = "<proxy>",
#'   proxyport = <port>,
#'   proxyusername = "<username>",
#'   proxypassword = "<password>"
#' )
#' options(rdbnomics.curl_config = h)
#' df2 <- rdb_by_api_link(
#'   paste0(
65
66
67
#'     "https://api.db.nomics.world/v22/series/WB/DB?dimensions=%7B%22",
#'     "indicator%22%3A%5B%22IC.REG.PROC.FE.NO%22%5D%7D&q=Doing%20Business",
#'     "&observations=1&format=json&align_periods=1&offset=0&facets=0"
68
69
#'   )
#' )
70
71
72
#' # or to use once
#' df2 <- rdb_by_api_link(
#'   paste0(
73
74
75
#'     "https://api.db.nomics.world/v22/series/WB/DB?dimensions=%7B%22",
#'     "indicator%22%3A%5B%22IC.REG.PROC.FE.NO%22%5D%7D&q=Doing%20Business",
#'     "&observations=1&format=json&align_periods=1&offset=0&facets=0"
76
77
78
79
80
81
#'   ),
#'   curl_config = h
#' )
#'
#' 
#' ## Use R default connection to avoid a proxy failure (in some cases)
82
#' # Fetch one series from the dataset 'Doing Business' of WB provider :
83
#' options(rdbnomics.use_readLines = TRUE)
84
85
#' df2 <- rdb_by_api_link(
#'   paste0(
86
87
88
#'     "https://api.db.nomics.world/v22/series/WB/DB?dimensions=%7B%22",
#'     "indicator%22%3A%5B%22IC.REG.PROC.FE.NO%22%5D%7D&q=Doing%20Business",
#'     "&observations=1&format=json&align_periods=1&offset=0&facets=0"
89
90
#'   )
#' )
91
#' # or to use once
92
93
#' df2 <- rdb_by_api_link(
#'   paste0(
94
95
96
#'     "https://api.db.nomics.world/v22/series/WB/DB?dimensions=%7B%22",
#'     "indicator%22%3A%5B%22IC.REG.PROC.FE.NO%22%5D%7D&q=Doing%20Business",
#'     "&observations=1&format=json&align_periods=1&offset=0&facets=0"
97
98
99
#'   ),
#'   use_readLines = TRUE
#' )
100
101
102
103
104
#' 
#' 
#' ## Apply filter(s) to the series
#' # One filter
#' df3 <- rdb_by_api_link(
105
#'   "https://api.db.nomics.world/v22/series/IMF/WEO:2019-10/ABW.BCA?observations=1",
106
107
108
109
110
111
112
113
#'   filters = list(
#'     code = "interpolate",
#'     parameters = list(frequency = "daily", method = "spline")
#'   )
#' )
#' 
#' # Two filters
#' df3 <- rdb_by_api_link(
114
#'   "https://api.db.nomics.world/v22/series/IMF/WEO:2019-10/ABW.BCA?observations=1",
115
116
117
118
119
120
121
122
123
124
125
#'   filters = list(
#'     list(
#'       code = "interpolate",
#'       parameters = list(frequency = "quarterly", method = "spline")
#'     ),
#'     list(
#'       code = "aggregate",
#'       parameters = list(frequency = "annual", method = "average")
#'     )
#'   )
#' )
126
#' }
127
#' @seealso \code{\link{rdb}}
128
#' @author Sebastien Galais
129
#' @export
130
rdb_by_api_link <- function(
131
132
133
134
  api_link,
  use_readLines = getOption("rdbnomics.use_readLines"),
  curl_config = getOption("rdbnomics.curl_config"),
  filters = getOption("rdbnomics.filters")
135
) {
136
  .Deprecated("rdb(api_link = ...)", old = "rdb_by_api_link(api_link = ...)")
137

138
  .rdb(
139
140
141
142
143
    api_link = api_link,
    use_readLines = use_readLines,
    curl_config = curl_config,
    filters = filters
  )
144
}