-
Notifications
You must be signed in to change notification settings - Fork 17
/
README.Rmd
174 lines (125 loc) · 5.37 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
---
output:
github_document: default
html_document: default
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, echo = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
```
comtradr <img src="man/figures/logo.png" align="right" height="139" />
=======
<!-- badges: start -->
[](https://cran.r-project.org/package=comtradr)
[](https://github.com/ropensci/software-review/issues/613)
[](https://github.com/ropensci/comtradr/actions/workflows/R-CMD-check.yaml)
[](https://app.codecov.io/gh/ropensci/comtradr?branch=main)
<!-- badges: end -->
Interface with and extract data from the United Nations Comtrade API
<https://comtradeplus.un.org/>. Comtrade provides country level shipping data
for a variety of commodities, these functions allow for easy API query and data
returned as a tidy data frame. More info can be found
[here](https://uncomtrade.org/docs/welcome-to-un-comtrade/). Full API documentation
can be found [here](https://comtradedeveloper.un.org/).
Please [report](https://github.com/ropensci/comtradr/issues) issues, comments,
or feature requests. We are very much looking for feedback on the usability
of the new functions.
Please note that this package is released with a [Contributor Code of Conduct](https://rOpenSci.org/code-of-conduct/).
By contributing to this project, you agree to abide by its terms.
For information on citation of this package, use `citation("comtradr")`
## Installation 🛠️
You can install the package with:
```{r eval=FALSE}
install.packages("comtradr")
```
To install the dev version from github, use:
```{r eval=FALSE}
# install.packages("devtools")
devtools::install_github("ropensci/comtradr@dev")
```
## Usage
### Authentication 🔐
**Do not be discouraged by the complicated access to the token
- you can do it! 💪**
As stated above, you need an API token, see the FAQ of Comtrade for details
on how to obtain it:
➡️ https://uncomtrade.org/docs/api-subscription-keys/
You need to follow the detailed explanations,
which include screenshots, in the Wiki of Comtrade to the letter. ☝️
I am not writing them out here, because they might be updated regularly.
However, once you are signed up, select the `comtrade - v1`
product, which is the free API.
#### Storing the API key
If you are in an interactive session, you can call the following function to
save your API token to the environment file for the current session.
```{r, eval = F}
library(comtradr)
set_primary_comtrade_key()
```
If you are not in an interactive session, you can register the token once in
your session using the following base-r function.
```{r, eval = F}
Sys.setenv('COMTRADE_PRIMARY' = 'xxxxxxxxxxxxxxxxx')
```
If you would like to set the comtrade key permanently, we recommend editing
the project `.Renviron` file, where you need to add a line
with `COMTRADE_PRIMARY = xxxx-your-key-xxxx`.
ℹ️ Do not forget the line break after the last entry. This is the
easiest by taking advantage of the great `usethis` package.
```{r, eval = F}
usethis::edit_r_environ(scope = 'project')
```
### Example 1 ⛴️
Now we can get to actually request some data. Let us query the total
trade between China and Germany and Argentina, as reported by China.
```{r, eval = F}
# Country names passed to the API query function must be spelled in ISO3 format.
# For details see: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3
# You can request a maximum interval of twelve years from the API
example1 <- comtradr::ct_get_data(
reporter = 'CHN',
partner = c('ARG', 'DEU'),
start_date = 2010,
end_date = 2012
)
# Inspect the return data
str(example1)
```
### Example 2 ⛴️
Return all exports related to Wine from Argentina to all other
countries, for years 2007 through 2011.
```{r, eval = F}
library(comtradr)
# Fetch all shrimp related commodity codes from the Comtrade commodities DB.
# This vector of codes will get passed to the API query.
wine_codes <- ct_commodity_lookup("wine", return_code = TRUE, return_char = TRUE)
# API query.
example2 <- ct_get_data(
reporter = "ARG",
flow_direction = "export",
partner = "all_countries",
start_date = 2007,
end_date = 2011,
commodity_code = wine_codes
)
# Inspect the output
str(example2)
```
### Bulk Download Example 📦
To download bulk files, use the function `ct_get_bulk`. Usage is documented in
the package vignettes,
see [here](https://docs.ropensci.org/comtradr/articles/bulk_files.html) for an example.
Attention, this downloads large files (often more than one Gigabyte in size) and
requires a premium key.
```{r, eval = FALSE}
hs0_all <- comtradr::ct_get_bulk(
reporter = c("DEU"), # only some examples here,
commodity_classification = 'H0',
frequency = 'A',
verbose = T,
start_date = 2020, # only one year here
end_date = 2020)
```
## Data availability
See [here for an overview](https://uncomtrade.org/docs/why-are-some-converted-datasets-not-accessible-in-the-ui/) of available commodity classifications.
[](https://ropensci.org)