rdb.Rd 8.68 KB
Newer Older
1
2
3
4
5
6
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/rdb.R
\name{rdb}
\alias{rdb}
\title{Download DBnomics data.}
\usage{
7
8
9
10
11
12
13
rdb(
  provider_code = NULL,
  dataset_code = NULL,
  ids = NULL,
  dimensions = NULL,
  mask = NULL,
  query = NULL,
14
  api_link = NULL,
15
  filters = getOption("rdbnomics.filters"),
16
17
18
19
20
  use_readLines = getOption("rdbnomics.use_readLines"),
  curl_config = getOption("rdbnomics.curl_config"),
  verbose = getOption("rdbnomics.verbose_warning"),
  ...
)
21
22
}
\arguments{
23
24
\item{provider_code}{Character string (default \code{NULL}). DBnomics code
of the provider.}
25

26
27
\item{dataset_code}{Character string (default \code{NULL}). DBnomics code
of the dataset.}
28

29
30
\item{ids}{Character string (default \code{NULL}). DBnomics code of one or
several series.}
31

32
33
\item{dimensions}{List or character string (single quoted)  (default \code{NULL}).
DBnomics code of one or several dimensions in the specified provider and dataset.
34
35
If it is a named list, then the function \code{toJSON} (from the
package \pkg{jsonlite}) is applied to generate the json object.}
36

37
38
\item{mask}{Character string (default \code{NULL}). DBnomics code of one or
several masks in the specified provider and dataset.}
39

40
41
42
\item{query}{Character string (default \code{NULL}). A query to
filter/select series from a provider's dataset.}

43
44
\item{api_link}{Character string. DBnomics API link of the search. It should
starts with \code{http://} or \code{https://}.}
45

46
\item{filters}{List (default \code{NULL}). This argument must be a named
47
48
49
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
50
51
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}
52
53
and \code{method} or a NULL.}

54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
\item{use_readLines}{Logical (default \code{FALSE}). If \code{TRUE}, then
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}.}

\item{curl_config}{Named list (default \code{NULL}). If not
\code{NULL}, it is used to configure a proxy connection. This
configuration is passed to the function \code{curl_fetch_memory} of the package
\pkg{curl}. A temporary \code{curl_handle} object is created internally
with arguments equal to the provided list in \code{curl_config}.\cr
For \code{curl_fetch_memory} arguments see \code{\link[curl]{curl_fetch}}.
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}.}

69
\item{verbose}{Logical (default \code{FALSE}). Show warnings of the function.}
70

71
\item{...}{Arguments to be passed to the internal function \code{.rdb}.}
72
73
}
\value{
74
A \code{data.table}.
75
76
77
}
\description{
\code{rdb} downloads data series from
78
\href{https://db.nomics.world/}{DBnomics} using shortcuts like \code{ids},
79
\code{dimensions}, \code{mask}, \code{query} or using an \code{api_link}.
80
81
82
}
\details{
This function gives you access to hundreds of millions data series from
83
\href{https://api.db.nomics.world/}{DBnomics API} (documentation about
84
the API can be found \href{https://api.db.nomics.world/v22/apidocs}{here}).
85
The code of each series is given on the
86
87
88
89
\href{https://db.nomics.world/}{DBnomics website}. \cr\cr
In the event that only the argument \code{ids} is provided (and those in the
ellipsis \code{...}), the argument name can be dropped. The character string
vector is directly passed to \code{ids}. \cr
90
91
92
If only the argument \code{api_link} is provided (and those in the
ellipsis \code{...}), then the argument name can be dropped. The character string
vector is directly passed to \code{api_link}. \cr
93
94
95
In the same way, if only \code{provider_code}, \code{dataset_code} and
\code{mask} are provided then the arguments names can be dropped. The
last character string is automatically passed to \code{mask}.
96
97
}
\examples{
98
\dontrun{
99
## By ids
100
# Fetch one series from dataset 'Unemployment rate' (ZUTN) of AMECO provider:
101
df1 <- rdb(ids = "AMECO/ZUTN/EA19.1.0.0.0.ZUTN")
102
# or when no argument names are given (provider_code -> ids)
103
df1 <- rdb("AMECO/ZUTN/EA19.1.0.0.0.ZUTN")
104

105
# Fetch two series from dataset 'Unemployment rate' (ZUTN) of AMECO provider:
106
df2 <- rdb(ids = c("AMECO/ZUTN/EA19.1.0.0.0.ZUTN", "AMECO/ZUTN/DNK.1.0.0.0.ZUTN"))
107

108
109
# Fetch two series from different datasets of different providers:
df3 <- rdb(ids = c("AMECO/ZUTN/EA19.1.0.0.0.ZUTN", "IMF/BOP/A.FR.BCA_BP6_EUR"))
110

111
112

## By dimensions
113
# Fetch one value of one dimension from dataset 'Unemployment rate' (ZUTN) of AMECO provider:
114
df1 <- rdb("AMECO", "ZUTN", dimensions = list(geo = "ea12"))
115
# or
116
df1 <- rdb("AMECO", "ZUTN", dimensions = '{"geo":["ea12"]}')
117

118
# Fetch two values of one dimension from dataset 'Unemployment rate' (ZUTN) of AMECO provider:
119
df2 <- rdb("AMECO", "ZUTN", dimensions = list(geo = c("ea12", "dnk")))
120
# or
121
df2 <- rdb("AMECO", "ZUTN", dimensions = '{"geo":["ea12","dnk"]}')
122

123
# Fetch several values of several dimensions from dataset 'Doing business' (DB) of World Bank:
124
125
126
127
dim <- list(
  country = c("DZ", "PE"),
  indicator = c("ENF.CONT.COEN.COST.ZS", "IC.REG.COST.PC.FE.ZS")
)
128
df3 <- rdb("WB", "DB", dimensions = dim)
129
130
# or
dim <- paste0(
131
132
  '{"country":["DZ","PE"],',
  '"indicator":["ENF.CONT.COEN.COST.ZS","IC.REG.COST.PC.FE.ZS"]}'
133
)
134
df3 <- rdb("WB", "DB", dimensions = dim)
135

136

137
## By mask
138
139
# Fetch one series from dataset 'Balance of Payments' (BOP) of IMF:
df1 <- rdb("IMF", "BOP", mask = "A.FR.BCA_BP6_EUR")
140
# or when no argument names are given except provider_code and dataset_code (ids -> mask)
141
df1 <- rdb("IMF", "BOP", "A.FR.BCA_BP6_EUR")
142

143
144
# Fetch two series from dataset 'Balance of Payments' (BOP) of IMF:
df2 <- rdb("IMF", "BOP", mask = "A.FR+ES.BCA_BP6_EUR")
145

146
147
# Fetch all series along one dimension from dataset 'Balance of Payments' (BOP) of IMF:
df3 <- rdb("IMF", "BOP", mask = "A..BCA_BP6_EUR")
148

149
150
# Fetch series along multiple dimensions from dataset 'Balance of Payments' (BOP) of IMF:
df4 <- rdb("IMF", "BOP", mask = "A.FR.BCA_BP6_EUR+IA_BP6_EUR")
151
152
153


## By query
154
155
156
157
# Fetch one series from dataset 'WEO by countries (2019-10 release)' (WEO:2019-10) from IMF :
df1 <- rdb("IMF", "WEO:2019-10", query = "France current account balance percent")
# Fetch series from dataset 'WEO by countries (2019-10 release)' (WEO:2019-10) from IMF :
df2 <- rdb("IMF", "WEO:2019-10", query = "current account balance percent")
158

159

160
## By api_link
161
162
# Fetch two series from different datasets of different providers :
df1 <- rdb(
163
  api_link = paste0(
164
165
166
167
168
169
170
    "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"
  )
)

# Fetch one series from the dataset 'Doing Business' of WB provider :
df2 <- rdb(
171
  api_link = paste0(
172
173
174
175
176
    "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"
  )
)
177
178
179
180
181
182
183
# or when no argument names are given (provider_code -> api_link)
df1 <- rdb(
  paste0(
    "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"
  )
)
184
185


186
## Use a specific proxy to fetch the data
187
# Fetch one series from dataset 'Unemployment rate' (ZUTN) of AMECO provider :
188
189
190
191
192
193
194
h <- list(
  proxy = "<proxy>",
  proxyport = <port>,
  proxyusername = "<username>",
  proxypassword = "<password>"
)
options(rdbnomics.curl_config = h)
195
df1 <- rdb(ids = "AMECO/ZUTN/EA19.1.0.0.0.ZUTN")
196
# or to use once
197
options(rdbnomics.curl_config = NULL)
198
df1 <- rdb(ids = "AMECO/ZUTN/EA19.1.0.0.0.ZUTN", curl_config = h)
199
200
201


## Use R default connection to avoid a proxy failure (in some cases)
202
# Fetch one series from dataset 'Unemployment rate' (ZUTN) of AMECO provider :
203
options(rdbnomics.use_readLines = TRUE)
204
df1 <- rdb(ids = "AMECO/ZUTN/EA19.1.0.0.0.ZUTN")
205
# or to use once
206
df1 <- rdb(ids = "AMECO/ZUTN/EA19.1.0.0.0.ZUTN", use_readLines = TRUE)
207
208
209
210
211


## Apply filter(s) to the series
# One filter
df1 <- rdb(
212
  ids = c("IMF/WEO:2019-10/ABW.BCA.us_dollars", "IMF/WEO:2019-10/ABW.BCA_NGDPD.pcent_gdp"),
213
214
215
216
217
218
219
220
  filters = list(
    code = "interpolate",
    parameters = list(frequency = "daily", method = "spline")
  )
)

# Two filters
df1 <- rdb(
221
  ids = c("IMF/WEO:2019-10/ABW.BCA.us_dollars", "IMF/WEO:2019-10/ABW.BCA_NGDPD.pcent_gdp"),
222
223
224
225
226
227
228
229
230
231
232
  filters = list(
    list(
      code = "interpolate",
      parameters = list(frequency = "quarterly", method = "spline")
    ),
    list(
      code = "aggregate",
      parameters = list(frequency = "annual", method = "average")
    )
  )
)
233
}
234
}
235
236
237
\author{
Sebastien Galais
}