Skip to content

Commit

Permalink
updated readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@datapumpernickel
datapumpernickel committed May 11, 2023
1 parent 9280e77 commit 9437a82
Show file tree
Hide file tree
Showing 3 changed files with 165 additions and 83 deletions.
108 changes: 68 additions & 40 deletions README.Rmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,69 +26,97 @@ comtradr
<!-- [here](https://comtrade.un.org/data/doc/api/). -->


## Currently re-launching
## 🚧 Currently re-launching Comtradr 🚧

See #44 for the discussion around it.
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?)).

Please [report](https://github.com/ropensci/comtradr/issues) issues, comments, or feature requests.
In order to accomodate 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.

Please [report](https://github.com/ropensci/comtradr/issues) issues, comments, or feature requests. We are very much looking for feedback on the useability 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

<!-- Install from CRAN: -->
<!-- ```{r eval=FALSE} -->
<!-- install.packages("comtradr") -->
<!-- ``` -->
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:

Install the current development version from this repo:
```{r eval=FALSE}
# install.packages("devtools")
devtools::install_github("ropensci/comtradr@api-update")
devtools::install_github("ropensci/comtradr@main")
```

<!-- ## Example Usage -->
## Usage

### Authentication

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')
```

<!-- **Example 1**: Return all exports from China to South Korea, United States and Mexico, for all years -->
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} -->
<!-- library(comtradr) -->
```{r, eval = F}
usethis::edit_r_environ(scope = 'project')
```

<!-- # Country names passed to the API query function must be spelled as they appear -->
<!-- # in the Comtrade DB. Use "ct_country_lookup" to query the country DB and -->
<!-- #return the exact spelling of specific countries. -->
<!-- ct_country_lookup("korea") -->
### Example 1

<!-- # Since we want South Korea, we'll use "Rep. of Korea" within the API query. -->
<!-- example1 <- ct_search(reporters = "China", -->
<!-- partners = c("Rep. of Korea", "USA", "Mexico"), -->
<!-- trade_direction = "exports") -->
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.

<!-- # Inspect the return data -->
<!-- str(example1) -->
<!-- ``` -->

<!-- **Example 2**: Return all exports related to shrimp from Thailand to all other countries, for years 2007 thru 2011 -->

<!-- ```{r, eval = F} -->
<!-- library(comtradr) -->
```{r, eval = F}
<!-- # Fetch all shrimp related commodity codes from the Comtrade commodities DB. -->
<!-- # This vector of codes will get passed to the API query. -->
<!-- shrimp_codes <- ct_commodity_lookup("shrimp", return_code = TRUE, return_char = TRUE) -->
# 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
<!-- # API query. -->
<!-- example2 <- ct_search(reporters = "Thailand", -->
<!-- partners = "All", -->
<!-- trade_direction = "exports", -->
<!-- start_date = 2007, -->
<!-- end_date = 2011, -->
<!-- commod_codes = shrimp_codes) -->
# 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 output -->
<!-- str(example2) -->
<!-- ``` -->
# 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",
start_date = 2007,
end_date = 2011,
commodity_code = wine_codes
)
# Inspect the output
str(example2)
```

[![ropensci_footer](https://ropensci.org/public_images/ropensci_footer.png)](https://ropensci.org)
138 changes: 96 additions & 42 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,22 +7,34 @@
<!-- [![Travis-CI Build Status](https://travis-ci.org/ropensci/comtradr.svg?branch=master)](https://travis-ci.org/ropensci/comtradr) -->
<!-- [![AppVeyor Build Status](https://ci.appveyor.com/api/projects/status/github/ropensci/comtradr?branch=master&svg=true)](https://ci.appveyor.com/project/ropensci/comtradr) -->

[![codecov](https://codecov.io/github/ropensci/comtradr/branch/master/graphs/badge.svg)](https://codecov.io/github/ropensci/comtradr)
[![CRAN_Status_Badge](https://www.r-pkg.org/badges/version/comtradr)](https://cran.r-project.org/package=comtradr)
[![](https://badges.ropensci.org/141_status.svg)](https://github.com/ropensci/software-review/issues/141)
[![R-CMD-check](https://github.com/ropensci/comtradr/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/ropensci/comtradr/actions/workflows/R-CMD-check.yaml)
[![Codecov test
coverage](https://codecov.io/gh/ropensci/comtradr/branch/master/graph/badge.svg)](https://app.codecov.io/gh/ropensci/comtradr?branch=api-update)
<!-- badges: end -->

<!-- R package for interacting with the [UN Comtrade Database](https://comtrade.un.org/data/) public API. UN Comtrade provides historical data on the weights and value of -->
<!-- specific goods shipped between countries, more info can be found [here](https://comtrade.un.org/). Full API documentation can be found -->
<!-- [here](https://comtrade.un.org/data/doc/api/). -->

## Currently re-launching
## 🚧 Currently re-launching Comtradr 🚧

See \#44 for the discussion around it.
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 accomodate 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.

Please [report](https://github.com/ropensci/comtradr/issues) issues,
comments, or feature requests.
comments, or feature requests. We are very much looking for feedback on
the useability 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
Expand All @@ -32,48 +44,90 @@ For information on citation of this package, use `citation("comtradr")`

## Installation

<!-- Install from CRAN: -->
<!-- ```{r eval=FALSE} -->
<!-- install.packages("comtradr") -->
<!-- ``` -->

Install the current development version from this repo:
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:

``` r
# install.packages("devtools")
devtools::install_github("ropensci/comtradr@api-update")
devtools::install_github("ropensci/comtradr@main")
```

## Usage

### Authentication

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
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
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
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

# 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 Usage -->
<!-- **Example 1**: Return all exports from China to South Korea, United States and Mexico, for all years -->
<!-- ```{r, eval = F} -->
<!-- library(comtradr) -->
<!-- # Country names passed to the API query function must be spelled as they appear -->
<!-- # in the Comtrade DB. Use "ct_country_lookup" to query the country DB and -->
<!-- #return the exact spelling of specific countries. -->
<!-- ct_country_lookup("korea") -->
<!-- # Since we want South Korea, we'll use "Rep. of Korea" within the API query. -->
<!-- example1 <- ct_search(reporters = "China", -->
<!-- partners = c("Rep. of Korea", "USA", "Mexico"), -->
<!-- trade_direction = "exports") -->
<!-- # Inspect the return data -->
<!-- str(example1) -->
<!-- ``` -->
<!-- **Example 2**: Return all exports related to shrimp from Thailand to all other countries, for years 2007 thru 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. -->
<!-- shrimp_codes <- ct_commodity_lookup("shrimp", return_code = TRUE, return_char = TRUE) -->
<!-- # API query. -->
<!-- example2 <- ct_search(reporters = "Thailand", -->
<!-- partners = "All", -->
<!-- trade_direction = "exports", -->
<!-- start_date = 2007, -->
<!-- end_date = 2011, -->
<!-- commod_codes = shrimp_codes) -->
<!-- # Inspect the output -->
<!-- str(example2) -->
<!-- ``` -->
**Example 2**: Return all exports related to Wine from Argentina to all
other countries, for years 2007 through 2011.

``` r
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",
start_date = 2007,
end_date = 2011,
commodity_code = wine_codes
)

# Inspect the output
str(example2)
```

[![ropensci_footer](https://ropensci.org/public_images/ropensci_footer.png)](https://ropensci.org)
2 changes: 1 addition & 1 deletion man/ct_commodity_lookup.Rd
View file

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

0 comments on commit 9437a82

Please sign in to comment.