{"id":13858161,"url":"https://github.com/ropensci/comtradr","last_synced_at":"2025-04-07T14:15:46.071Z","repository":{"id":41254426,"uuid":"80773377","full_name":"ropensci/comtradr","owner":"ropensci","description":"Functions for Interacting with the UN Comtrade API","archived":false,"fork":false,"pushed_at":"2024-05-22T16:17:05.000Z","size":10600,"stargazers_count":62,"open_issues_count":0,"forks_count":17,"subscribers_count":13,"default_branch":"main","last_synced_at":"2024-05-23T02:53:47.883Z","etag":null,"topics":["api","comtrade","peer-reviewed","r","r-package","rstats","supply-chain"],"latest_commit_sha":null,"homepage":"https://docs.ropensci.org/comtradr","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ropensci.png","metadata":{"files":{"readme":"README.Rmd","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":"codemeta.json"}},"created_at":"2017-02-02T22:07:38.000Z","updated_at":"2024-06-06T15:51:25.875Z","dependencies_parsed_at":"2024-01-13T03:28:14.151Z","dependency_job_id":"38c1b0fb-7d52-4312-b3a8-5c4455e0c084","html_url":"https://github.com/ropensci/comtradr","commit_stats":{"total_commits":457,"total_committers":11,"mean_commits":41.54545454545455,"dds":"0.48577680525164113","last_synced_commit":"058b97036e8539345d2233e5fa230fb878e4ef3d"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ropensci%2Fcomtradr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ropensci%2Fcomtradr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ropensci%2Fcomtradr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ropensci%2Fcomtradr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ropensci","download_url":"https://codeload.github.com/ropensci/comtradr/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247666015,"owners_count":20975788,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","comtrade","peer-reviewed","r","r-package","rstats","supply-chain"],"created_at":"2024-08-05T03:01:58.790Z","updated_at":"2025-04-07T14:15:46.049Z","avatar_url":"https://github.com/ropensci.png","language":"R","funding_links":[],"categories":["R"],"sub_categories":[],"readme":"---\noutput:\n  github_document: default\n  html_document: default\n---\n\n\u003c!-- README.md is generated from README.Rmd. Please edit that file --\u003e\n\n```{r, echo = FALSE}\nknitr::opts_chunk$set(collapse = TRUE, comment = \"#\u003e\")\n```\n\ncomtradr \u003cimg src=\"man/figures/logo.png\" align=\"right\" height=\"139\" /\u003e\n=======\n\u003c!-- badges: start --\u003e\n[![CRAN_Status_Badge](https://www.r-pkg.org/badges/version/comtradr)](https://cran.r-project.org/package=comtradr)\n[![Status at rOpenSci Software Peer Review](https://badges.ropensci.org/613_status.svg)](https://github.com/ropensci/software-review/issues/613)\n[![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)\n[![Codecov test coverage](https://codecov.io/gh/ropensci/comtradr/branch/main/graph/badge.svg)](https://app.codecov.io/gh/ropensci/comtradr?branch=main)\n\u003c!-- badges: end --\u003e\nInterface with and extract data from the United Nations Comtrade API \n\u003chttps://comtradeplus.un.org/\u003e. Comtrade provides country level shipping data\nfor a variety of commodities, these functions allow for easy API query and data \nreturned as a tidy data frame. More info can be found \n[here](https://uncomtrade.org/docs/welcome-to-un-comtrade/). Full API documentation \ncan be found [here](https://comtradedeveloper.un.org/).\n\nPlease [report](https://github.com/ropensci/comtradr/issues) issues, comments, \nor feature requests. We are very much looking for feedback on the usability \nof the new functions. \n\n\nPlease note that this package is released with a [Contributor Code of Conduct](https://rOpenSci.org/code-of-conduct/). \nBy contributing to this project, you agree to abide by its terms.\n\nFor information on citation of this package, use `citation(\"comtradr\")`\n\n## Installation 🛠️\n\nYou can install the package with:\n\n```{r eval=FALSE}\ninstall.packages(\"comtradr\")\n```\n\nTo install the dev version from github, use: \n\n```{r eval=FALSE}\n# install.packages(\"devtools\")\ndevtools::install_github(\"ropensci/comtradr@dev\")\n```\n\n\n## Usage\n\n### Authentication 🔐\n\n**Do not be discouraged by the complicated access to the token \n- you can do it! 💪**\n\nAs stated above, you need an API token, see the FAQ of Comtrade for details\non how to obtain it:\n\n➡️ https://uncomtrade.org/docs/api-subscription-keys/\n\nYou need to follow the detailed explanations,\nwhich include screenshots, in the Wiki of Comtrade to the letter. ☝️\nI am not writing them out here, because they might be updated regularly. \nHowever, once you are signed up, select the `comtrade - v1` \nproduct, which is the free API. \n\n#### Storing the API key\n\nIf you are in an interactive session, you can call the following function to \nsave your API token to the environment file for the current session. \n\n```{r, eval = F}\nlibrary(comtradr)\n\nset_primary_comtrade_key()\n```\n\nIf you are not in an interactive session, you can register the token once in \nyour session using the following base-r function.\n\n```{r, eval = F}\nSys.setenv('COMTRADE_PRIMARY' = 'xxxxxxxxxxxxxxxxx')\n```\n\nIf you would like to set the comtrade key permanently, we recommend editing \nthe project `.Renviron` file, where you need to add a line \nwith `COMTRADE_PRIMARY = xxxx-your-key-xxxx`. \n\nℹ️ Do not forget the line break after the last entry. This is the \neasiest by taking advantage of the great `usethis` package. \n\n```{r, eval = F}\nusethis::edit_r_environ(scope = 'project')\n``` \n\n### Example 1 ⛴️\n\nNow we can get to actually request some data. Let us query the total \ntrade between China and Germany and Argentina, as reported by China. \n\n\n```{r, eval = F}\n\n# Country names passed to the API query function must be spelled in ISO3 format. \n# For details see: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3 \n\n# You can request a maximum interval of twelve years from the API\nexample1 \u003c- comtradr::ct_get_data(\n  reporter = 'CHN',\n  partner = c('ARG', 'DEU'),\n  start_date = 2010,\n  end_date = 2012\n)\n\n# Inspect the return data\nstr(example1)\n```\n\n\n### Example 2 ⛴️\nReturn all exports related to Wine from Argentina to all other \ncountries, for years 2007 through 2011.\n\n```{r, eval = F}\nlibrary(comtradr)\n\n# Fetch all shrimp related commodity codes from the Comtrade commodities DB.\n# This vector of codes will get passed to the API query.\nwine_codes \u003c- ct_commodity_lookup(\"wine\", return_code = TRUE, return_char = TRUE)\n\n# API query.\nexample2 \u003c- ct_get_data(\n  reporter =  \"ARG\",\n  flow_direction = \"export\",\n  partner = \"all_countries\",\n  start_date = 2007,\n  end_date = 2011,\n  commodity_code = wine_codes\n)\n\n# Inspect the output\nstr(example2)\n```\n\n### Bulk Download Example 📦\nTo download bulk files, use the function `ct_get_bulk`. Usage is documented in \nthe package vignettes, \nsee [here](https://docs.ropensci.org/comtradr/articles/bulk_files.html) for an example. \n\nAttention, this downloads large files (often more than one Gigabyte in size) and \nrequires a premium key. \n\n```{r, eval = FALSE}\nhs0_all \u003c- comtradr::ct_get_bulk(\n  reporter = c(\"DEU\"), # only some examples here,\n  commodity_classification = 'H0',\n  frequency = 'A',\n  verbose = T,\n  start_date = 2020, # only one year here\n  end_date = 2020)\n```\n\n\n\n## Data availability\n\nSee [here for an overview](https://uncomtrade.org/docs/why-are-some-converted-datasets-not-accessible-in-the-ui/) of available commodity classifications.\n\n[![ropensci_footer](https://ropensci.org/public_images/ropensci_footer.png)](https://ropensci.org)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fropensci%2Fcomtradr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fropensci%2Fcomtradr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fropensci%2Fcomtradr/lists"}