comtradr

Functions for Interacting with the UN Comtrade API

https://github.com/ropensci/comtradr

Science Score: 36.0%

This score indicates how likely this project is to be science-related based on various indicators:

○
CITATION.cff file
✓
codemeta.json file
Found codemeta.json file
✓
.zenodo.json file
Found .zenodo.json file
○
DOI references
○
Academic publication links
✓
Committers with academic emails
1 of 9 committers (11.1%) from academic institutions
○
Institutional organization owner
○
JOSS paper metadata
○
Scientific vocabulary similarity
Low similarity (21.1%) to scientific vocabulary

Keywords

api comtrade peer-reviewed r r-package rstats supply-chain

Keywords from Contributors

genome

Last synced: 4 months ago · JSON representation

Repository

Functions for Interacting with the UN Comtrade API

Basic Info

Host: GitHub
Owner: ropensci
Language: R
Default Branch: main
Homepage: https://docs.ropensci.org/comtradr
Size: 11.4 MB

Statistics

Stars: 71
Watchers: 12
Forks: 19
Open Issues: 3
Releases: 11

Topics

api comtrade peer-reviewed r r-package rstats supply-chain

Created almost 9 years ago · Last pushed 5 months ago

Metadata Files

Readme Changelog Contributing Codemeta

README.Rmd

---
output:
  github_document: default
  html_document: default
---



```{r, echo = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
```

comtradr 
=======

[![CRAN_Status_Badge](https://www.r-pkg.org/badges/version/comtradr)](https://cran.r-project.org/package=comtradr)
[![Status at rOpenSci Software Peer Review](https://badges.ropensci.org/613_status.svg)](https://github.com/ropensci/software-review/issues/613)
[![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/main/graph/badge.svg)](https://app.codecov.io/gh/ropensci/comtradr?branch=main)

Interface with and extract data from the United Nations Comtrade API 
. 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.

[![ropensci_footer](https://ropensci.org/public_images/ropensci_footer.png)](https://ropensci.org)

Owner

Name: rOpenSci
Login: ropensci
Kind: organization
Email: info@ropensci.org
Location: Berkeley, CA

Website: https://ropensci.org/
Twitter: rOpenSci
Repositories: 307
Profile: https://github.com/ropensci

CodeMeta (codemeta.json)

{
  "@context": "https://doi.org/10.5063/schema/codemeta-2.0",
  "@type": "SoftwareSourceCode",
  "identifier": "comtradr",
  "description": "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.",
  "name": "comtradr: Interface with the United Nations Comtrade API",
  "relatedLink": "https://docs.ropensci.org/comtradr/",
  "codeRepository": "https://github.com/ropensci/comtradr",
  "issueTracker": "https://github.com/ropensci/comtradr/issues",
  "license": "https://spdx.org/licenses/GPL-3.0",
  "version": "0.4.0.0",
  "programmingLanguage": {
    "@type": "ComputerLanguage",
    "name": "R",
    "url": "https://r-project.org"
  },
  "runtimePlatform": "R version 4.3.1 (2023-06-16)",
  "author": [
    {
      "@type": "Person",
      "givenName": "Paul",
      "familyName": "Bochtler",
      "email": "paulbochtler.gh@gmail.com",
      "@id": "https://orcid.org/0000-0002-9146-6185"
    },
    {
      "@type": "Person",
      "givenName": "Harriet",
      "familyName": "Goers",
      "email": "hgoers@umd.edu"
    },
    {
      "@type": "Person",
      "givenName": "Chris",
      "familyName": "Muir",
      "email": "chrismuirRVA@gmail.com"
    }
  ],
  "contributor": [
    {
      "@type": "Person",
      "givenName": "Juergen",
      "familyName": "Amann"
    }
  ],
  "copyrightHolder": [
    {
      "@type": "Person",
      "givenName": "Paul",
      "familyName": "Bochtler",
      "email": "paulbochtler.gh@gmail.com",
      "@id": "https://orcid.org/0000-0002-9146-6185"
    }
  ],
  "maintainer": [
    {
      "@type": "Person",
      "givenName": "Paul",
      "familyName": "Bochtler",
      "email": "paulbochtler.gh@gmail.com",
      "@id": "https://orcid.org/0000-0002-9146-6185"
    }
  ],
  "softwareSuggestions": [
    {
      "@type": "SoftwareApplication",
      "identifier": "covr",
      "name": "covr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=covr"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "dplyr",
      "name": "dplyr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=dplyr"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "ggplot2",
      "name": "ggplot2",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=ggplot2"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "httptest2",
      "name": "httptest2",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=httptest2"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "knitr",
      "name": "knitr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=knitr"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "rmarkdown",
      "name": "rmarkdown",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=rmarkdown"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "testthat",
      "name": "testthat",
      "version": ">= 3.0.0",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=testthat"
    }
  ],
  "softwareRequirements": {
    "1": {
      "@type": "SoftwareApplication",
      "identifier": "R",
      "name": "R",
      "version": ">= 4.1.0"
    },
    "2": {
      "@type": "SoftwareApplication",
      "identifier": "lifecycle",
      "name": "lifecycle",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=lifecycle"
    },
    "3": {
      "@type": "SoftwareApplication",
      "identifier": "fs",
      "name": "fs",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=fs"
    },
    "4": {
      "@type": "SoftwareApplication",
      "identifier": "readr",
      "name": "readr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=readr"
    },
    "5": {
      "@type": "SoftwareApplication",
      "identifier": "askpass",
      "name": "askpass",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=askpass"
    },
    "6": {
      "@type": "SoftwareApplication",
      "identifier": "cli",
      "name": "cli",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=cli"
    },
    "7": {
      "@type": "SoftwareApplication",
      "identifier": "httr2",
      "name": "httr2",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=httr2"
    },
    "8": {
      "@type": "SoftwareApplication",
      "identifier": "rlang",
      "name": "rlang",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=rlang"
    },
    "9": {
      "@type": "SoftwareApplication",
      "identifier": "stringr",
      "name": "stringr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=stringr"
    },
    "10": {
      "@type": "SoftwareApplication",
      "identifier": "poorman",
      "name": "poorman",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=poorman"
    },
    "11": {
      "@type": "SoftwareApplication",
      "identifier": "lubridate",
      "name": "lubridate",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=lubridate"
    },
    "12": {
      "@type": "SoftwareApplication",
      "identifier": "purrr",
      "name": "purrr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=purrr"
    },
    "SystemRequirements": null
  },
  "fileSize": "714.17KB",
  "releaseNotes": "https://github.com/ropensci/comtradr/blob/master/NEWS.md",
  "readme": "https://github.com/ropensci/comtradr/blob/main/README.md",
  "contIntegration": [
    "https://github.com/ropensci/comtradr/actions/workflows/R-CMD-check.yaml",
    "https://app.codecov.io/gh/ropensci/comtradr?branch=api-update"
  ],
  "review": {
    "@type": "Review",
    "url": "https://github.com/ropensci/software-review/issues/141",
    "provider": "https://ropensci.org"
  },
  "keywords": [
    "comtrade",
    "api",
    "supply-chain",
    "r",
    "rstats",
    "r-package",
    "peer-reviewed"
  ]
}

GitHub Events

Total

Create event: 1
Issues event: 5
Release event: 1
Watch event: 7
Delete event: 1
Issue comment event: 6
Push event: 9
Pull request event: 5
Fork event: 2

Last Year

Create event: 1
Issues event: 5
Release event: 1
Watch event: 7
Delete event: 1
Issue comment event: 6
Push event: 9
Pull request event: 5
Fork event: 2

Committers

Last synced: 11 months ago

All Time

Total Commits: 589
Total Committers: 9
Avg Commits per committer: 65.444
Development Distribution Score (DDS): 0.552

Past Year

Commits: 102
Committers: 2
Avg Commits per committer: 51.0
Development Distribution Score (DDS): 0.02

Top Committers

Name	Email	Commits
paul bochtler	6****l	264
ChrisMuir	c**A@g**m	254
Harriet Goers	h**s@u**u	43
Paul Bochtler	p**r@M**l	17
amannj	a**n@g**m	5
Scott Chamberlain	m**s@g**m	2
Bochtler	b**p@s**n	2
mavargas11	m**1@u**l	1
ropenscibot	m**t@g**m	1

Committer Domains (Top 20 + Academic)

uc.cl: 1 swp-berlin.intern: 1 umd.edu: 1

Issues and Pull Requests

Last synced: 4 months ago

All Time

Total issues: 70
Total pull requests: 27
Average time to close issues: 7 months
Average time to close pull requests: 10 days
Total issue authors: 32
Total pull request authors: 7
Average comments per issue: 3.29
Average comments per pull request: 0.19
Merged pull requests: 25
Bot issues: 4
Bot pull requests: 0

Past Year

Issues: 4
Pull requests: 4
Average time to close issues: about 2 months
Average time to close pull requests: 1 day
Issue authors: 4
Pull request authors: 2
Average comments per issue: 0.75
Average comments per pull request: 0.0
Merged pull requests: 3
Bot issues: 0
Bot pull requests: 0

View more stats

Top Authors

Issue Authors

ChrisMuir (13)
datapumpernickel (12)
hgoers (5)
github-actions[bot] (3)
zlfccnu (3)
zauster (3)
LaurentSmeets (2)
amannj (2)
luifrancgom (1)
rachel-pompa (1)
rasundsbak (1)
pedromein (1)
FATelarico (1)
dakilian (1)
hansronald (1)

Pull Request Authors

datapumpernickel (28)
sckott (2)
amannj (2)
pachadotdev (1)
ChrisMuir (1)
potterzot (1)
B-JAMMEH (1)

Top Labels

Issue Labels

bug (1)

Pull Request Labels

Packages

Total packages: 1
Total downloads:
- cran 906 last-month
Total docker downloads: 89,578

Total dependent packages: 1
Total dependent repositories: 2
Total versions: 11
Total maintainers: 1

cran.r-project.org: comtradr

Interface with the United Nations Comtrade API

Homepage: https://docs.ropensci.org/comtradr/
Documentation: http://cran.r-project.org/web/packages/comtradr/comtradr.pdf
License: GPL-3
Latest release: 1.0.3
published about 1 year ago

Versions: 11
Dependent Packages: 1
Dependent Repositories: 2
Downloads: 906 Last month
Docker Downloads: 89,578

Rankings

Forks count: 7.1%

Stargazers count: 7.5%

Average: 15.2%

Dependent packages count: 18.7%

Dependent repos count: 20.5%

Downloads: 22.0%

Maintainers (1)

paulbochtler.gh@gmail.com

Last synced: 4 months ago

Dependencies

DESCRIPTION cran

R >= 3.0.0 depends
httr * imports
jsonlite * imports
magrittr >= 1.5 imports
purrr * imports
dplyr * suggests
ggplot2 * suggests
knitr * suggests
rmarkdown * suggests
testthat * suggests

.github/workflows/pkgcheck.yaml actions

ropensci-review-tools/pkgcheck-action main composite

.github/workflows/R-CMD-check.yaml actions

actions/checkout v3 composite
r-lib/actions/check-r-package v2 composite
r-lib/actions/setup-pandoc v2 composite
r-lib/actions/setup-r v2 composite
r-lib/actions/setup-r-dependencies v2 composite

.github/workflows/test-coverage.yaml actions

actions/checkout v3 composite
actions/upload-artifact v3 composite
r-lib/actions/setup-r v2 composite
r-lib/actions/setup-r-dependencies v2 composite