Merge pull request #82 from ropensci/dev

Dev

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: comtradr
-Title: Interface with the United Nations 'Comtrade' API
-Version: 0.4.0.0
+Title: Interface with the United Nations Comtrade API
+Version: 0.4.0.9000
 Maintainer: Paul Bochtler <paulbochtler.gh@gmail.com>
 Authors@R: c(
             person("Paul", "Bochtler", 

README.Rmd

@@ -25,36 +25,32 @@ returned as a tidy data frame. More info can be found
 [here](https://unstats.un.org/wiki/display/comtrade). Full API documentation 
 can be found [here](https://comtradedeveloper.un.org/).
 
-The Comtrade API has been undergoing updates in 2023. At this point the legacy 
-API has been taken offline (see [here](https://unstats.un.org/wiki/display/comtrade/New+Comtrade+FAQ+for+Advanced+Users#NewComtradeFAQforAdvancedUsers-WhatisthelegacyoftheUNComtrade?UntilwhencanIuseit?)). The `comtradr`
-package has accommodated these changes. Some premium functions like bulk 
-download are still not supported in the package, but we are working on it. See
-https://github.com/ropensci/comtradr/issues/68 for details. 
-
 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. 
 
+The package in its old version is still available from 
+the `legacy-0-3-0` branch.
+
 
-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.
+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 🛠️
 
-Currently, the package is not on CRAN, but we plan on publishing to CRAN in the 
-near future. Install the current development version from this repo:
+You can install the package with:
 
 ```{r eval=FALSE}
-# install.packages("devtools")
-devtools::install_github("ropensci/comtradr@main")
+install.packages("comtradr")
 ```
 
-Once it is on CRAN, you can install with:
+To install the dev version from github, use: 
 
 ```{r eval=FALSE}
-install.packages("comtradr")
+# install.packages("devtools")
+devtools::install_github("ropensci/comtradr@main")
 ```
 
 ## Usage
@@ -153,4 +149,20 @@ example2 <- ct_get_data(
 str(example2)
 ```
 
+
+## Data availability
+
+See [here for an overview](https://unstats.un.org/wiki/display/comtrade/New+Comtrade+FAQ+for+Advanced+Users?preview=/135004494/135004492/Picture1.png) of available commodity classifications.
+
+## Comtradr has relaunched recently 🚧
+
+The Comtrade API has been undergoing extensive updates. At this point the legacy 
+API has been taken offline (see [here](https://unstats.un.org/wiki/display/comtrade/New+Comtrade+FAQ+for+Advanced+Users#NewComtradeFAQforAdvancedUsers-WhatisthelegacyoftheUNComtrade?UntilwhencanIuseit?)).
+
+In order to accommodate the new syntax, as well as adding the new functionality, 
+the `comtradr` package has been undergoing an extensive re-write. Additionally, 
+it is not possible anymore to query the API without an API token. There still is 
+a free version, but unlike before you need to be a registered user to obtain the 
+token. See the [FAQ](https://unstats.un.org/wiki/display/comtrade/New+Comtrade+User+Guide#NewComtradeUserGuide-UNComtradeAPIManagement) for details on how to obtain the new access tokens. 
+
 [![ropensci_footer](https://ropensci.org/public_images/ropensci_footer.png)](https://ropensci.org)

README.md

@@ -19,14 +19,6 @@ frame. More info can be found
 [here](https://unstats.un.org/wiki/display/comtrade). Full API
 documentation can be found [here](https://comtradedeveloper.un.org/).
 
-The Comtrade API has been undergoing updates in 2023. At this point the
-legacy API has been taken offline (see
-[here](https://unstats.un.org/wiki/display/comtrade/New+Comtrade+FAQ+for+Advanced+Users#NewComtradeFAQforAdvancedUsers-WhatisthelegacyoftheUNComtrade?UntilwhencanIuseit?)).
-The `comtradr` package has accommodated these changes. Some premium
-functions like bulk download are still not supported in the package, but
-we are working on it. See
-<https://github.com/ropensci/comtradr/issues/68> for details.
-
 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.
@@ -39,19 +31,17 @@ For information on citation of this package, use `citation("comtradr")`
 
 ## Installation 🛠️
 
-Currently, the package is not on CRAN, but we plan on publishing to CRAN
-in the near future. Install the current development version from this
-repo:
+You can install the package with:
 
 ``` r
-# install.packages("devtools")
-devtools::install_github("ropensci/comtradr@main")
+install.packages("comtradr")
 ```
 
-Once it is on CRAN, you can install with:
+To install the dev version from github, use:
 
 ``` r
-install.packages("comtradr")
+# install.packages("devtools")
+devtools::install_github("ropensci/comtradr@main")
 ```
 
 ## Usage
@@ -150,4 +140,24 @@ example2 <- ct_get_data(
 str(example2)
 ```
 
+## Data availability
+
+See [here for an
+overview](https://unstats.un.org/wiki/display/comtrade/New+Comtrade+FAQ+for+Advanced+Users?preview=/135004494/135004492/Picture1.png)
+of available commodity classifications.
+
+## Comtradr has relaunched recently 🚧
+
+The Comtrade API has been undergoing extensive updates. At this point
+the legacy API has been taken offline (see
+[here](https://unstats.un.org/wiki/display/comtrade/New+Comtrade+FAQ+for+Advanced+Users#NewComtradeFAQforAdvancedUsers-WhatisthelegacyoftheUNComtrade?UntilwhencanIuseit?)).
+
+In order to accommodate the new syntax, as well as adding the new
+functionality, the `comtradr` package has been undergoing an extensive
+re-write. Additionally, it is not possible anymore to query the API
+without an API token. There still is a free version, but unlike before
+you need to be a registered user to obtain the token. See the
+[FAQ](https://unstats.un.org/wiki/display/comtrade/New+Comtrade+User+Guide#NewComtradeUserGuide-UNComtradeAPIManagement)
+for details on how to obtain the new access tokens.
+
 [![ropensci_footer](https://ropensci.org/public_images/ropensci_footer.png)](https://ropensci.org)

vignettes/caching.Rmd

@@ -36,6 +36,7 @@ See here: <https://cachem.r-lib.org/reference/cache_disk.html>
 and here: <https://rappdirs.r-lib.org/reference/user_cache_dir.html>
 
 ```{r, eval = FALSE}
+library(comtradr)
 #### Now
 q <- ct_get_data(reporter = "USA", 
                partner = c("DEU", "FRA", "JPN", "MEX"), 
@@ -70,3 +71,23 @@ The parameters are:
 
 See here for the details on pruning and other functions of `cachem`:
 <https://cachem.r-lib.org/reference/cache_disk.html>
+
+
+### Careful with outdated data! ⚠️
+
+The current default for the cache age is set to `Inf`, hence when you have 
+requested data once, it will never de downloaded again. For recent data, this
+can be a very bad idea, as the United Nations might update their data and 
+you will only work with outdated data.
+
+The recommended way is to set the `COMTRADR_CACHE_MAX_AGE` environment variable
+as described above. E.g.: to `60*60*24*365` for one year. 
+
+To find your cache and empty it by yourself, you can do: 
+
+``` {r, eval = FALSE}
+## to delete all files in your cache
+rappdirs::user_cache_dir('comtradr') |> 
+  list.files(full.names = T) |> 
+  file.remove()
+``` 

vignettes/comtradr.Rmd

@@ -14,7 +14,7 @@ knitr::opts_chunk$set(
 )
 ```
 
-```{r setup}
+```{r setup, echo=FALSE}
 library(comtradr)
 ```
 
@@ -32,7 +32,7 @@ API wrapper for the [UN Comtrade Database](https://comtradeplus.un.org/). UN Com
 
 Install the development version from GitHub:
 ```{r eval = FALSE}
-devtools::install_github("ropensci/comtradr")
+install.packages("comtradr")
 ```
 
 Load comtradr