Author: Mauricio Vargas S.
Date: 2026-07-21

# Basic usage

#### Mauricio Vargas S.

#### 2026-07-21

# Introduction

This vignette explains the functions within this package. The idea is to show how this package simplifies obtaining data from (api.tradestatistics.io)[https://api.tradestatistics.io].

    library(tradestatistics)

# Package data

## Available tables

Provided that this package obtains data from an API, it is useful to know which tables can be accessed:

    ots_tables
    #>                 table
    #>                <char>
    #>  1:         countries
    #>  2: countries_colours
    #>  3:         importers
    #>  4:         exporters
    #>  5:           sectors
    #>  6:   sectors_colours
    #>  7:        industries
    #>  8:             years
    #>  9:             itpde
    #> 10:         itpde_imp
    #> 11:         itpde_exp
    #> 12:     itpde_imp_exp
    #> 13:     itpde_imp_sec
    #> 14:     itpde_imp_ind
    #> 15:     itpde_exp_sec
    #> 16:     itpde_exp_ind
    #> 17:         itpde_sec
    #> 18:         itpde_ind
    #> 19: itpde_imp_exp_sec
    #> 20:             itpds
    #> 21:         itpds_imp
    #> 22:         itpds_exp
    #> 23:     itpds_imp_exp
    #> 24:     itpds_imp_sec
    #> 25:     itpds_imp_ind
    #> 26:     itpds_exp_sec
    #> 27:     itpds_exp_ind
    #> 28:         itpds_sec
    #> 29:         itpds_ind
    #> 30: itpds_imp_exp_sec
    #>                 table
    #>                <char>
    #>                                                                                               description
    #>                                                                                                    <char>
    #>  1:                                                                                             Countries
    #>  2:                                                    Contries coloured by continent (for visualization)
    #>  3:                                                                                    Importers per year
    #>  4:                                                                                    Exporters per year
    #>  5:                                                                                         Broad sectors
    #>  6:                                                                             Broad sectors with colour
    #>  7:                                                                                            Industries
    #>  8:                                                                                                 Years
    #>  9:                                                     International Trade and Production for Estimation
    #> 10:                    International Trade and Production for Estimation, aggregated by year and importer
    #> 11:                    International Trade and Production for Estimation, aggregated by year and exporter
    #> 12:         International Trade and Production for Estimation, aggregated by year, importer, and exporter
    #> 13:           International Trade and Production for Estimation, aggregated by year, importer, and sector
    #> 14:         International Trade and Production for Estimation, aggregated by year, importer, and industry
    #> 15:           International Trade and Production for Estimation, aggregated by year, exporter, and sector
    #> 16:         International Trade and Production for Estimation, aggregated by year, exporter, and industry
    #> 17:                      International Trade and Production for Estimation, aggregated by year and sector
    #> 18:                    International Trade and Production for Estimation, aggregated by year and industry
    #> 19: International Trade and Production for Estimation, aggregated by year, importer, exporter, and sector
    #> 20:                                                     International Trade and Production for Simulation
    #> 21:                    International Trade and Production for Simulation, aggregated by year and importer
    #> 22:                    International Trade and Production for Simulation, aggregated by year and exporter
    #> 23:         International Trade and Production for Simulation, aggregated by year, importer, and exporter
    #> 24:           International Trade and Production for Simulation, aggregated by year, importer, and sector
    #> 25:         International Trade and Production for Simulation, aggregated by year, importer, and industry
    #> 26:           International Trade and Production for Simulation, aggregated by year, exporter, and sector
    #> 27:         International Trade and Production for Simulation, aggregated by year, exporter, and industry
    #> 28:                      International Trade and Production for Simulation, aggregated by year and sector
    #> 29:                    International Trade and Production for Simulation, aggregated by year and industry
    #> 30: International Trade and Production for Simulation, aggregated by year, importer, exporter, and sector
    #>                                                                                               description
    #>                                                                                                    <char>
    #>                 source
    #>                 <char>
    #>  1: Derived from USITC
    #>  2: Derived from USITC
    #>  3: Derived from USITC
    #>  4: Derived from USITC
    #>  5: Derived from USITC
    #>  6: Derived from USITC
    #>  7: Derived from USITC
    #>  8: Derived from USITC
    #>  9:              USITC
    #> 10:              USITC
    #> 11:              USITC
    #> 12:              USITC
    #> 13:              USITC
    #> 14:              USITC
    #> 15:              USITC
    #> 16:              USITC
    #> 17:              USITC
    #> 18:              USITC
    #> 19:              USITC
    #> 20:              USITC
    #> 21:              USITC
    #> 22:              USITC
    #> 23:              USITC
    #> 24:              USITC
    #> 25:              USITC
    #> 26:              USITC
    #> 27:              USITC
    #> 28:              USITC
    #> 29:              USITC
    #> 30:              USITC
    #>                 source
    #>                 <char>

The ITPD-E table means “International Trade and Production Database for Estimation” and does not contain imputed values.

The ITPD-S table means “International Trade and Production Database for Simulation” and contains imputed values using the gravity model of trade.

The most aggregated tables are `itpde_imp`/`itpds_imp` (for imports, or with `_exp` for exporter) which contains how many dollars each country imports and exports in a year.

The less aggregated tables are `itpde`/`itpds` which detail bilateral trade at industry level in a year.

For the complete detail you can check tradestatistics.io.

## Country codes

The Package Functions section explains that you don’t need to memorize all ISO codes. The functions within this package are designed to match strings (i.e. “United States” or “America”) to valid ISO codes (i.e. “USA”).

Just as a reference, the table with all valid ISO codes can be accessed by running this:

    ots_countries
    #> Key: <dynamic_code>
    #>        iso3 dynamic_code                                   country continent
    #>      <char>       <char>                                    <char>    <char>
    #>   1:    ABW          ABW                                     Aruba  Americas
    #>   2:    AFG          AFG                               Afghanistan      Asia
    #>   3:    AGO          AGO                                    Angola    Africa
    #>   4:    AIA          AIA                                  Anguilla  Americas
    #>   5:    ALB          ALB                                   Albania    Europe
    #>  ---
    #> 259:    ZAF          ZAF                              South Africa    Africa
    #> 260:    ZAF        ZAF.X South Africa (after Namibia independence)    Africa
    #> 261:    COD          ZAR                                     Zaire    Africa
    #> 262:    ZMB          ZMB                                    Zambia    Africa
    #> 263:    ZWE          ZWE                                  Zimbabwe    Africa
    #>       colour
    #>       <char>
    #>   1: #a1aafb
    #>   2: #a8c380
    #>   3: #d1a1bc
    #>   4: #a1aafb
    #>   5: #d05555
    #>  ---
    #> 259: #d1a1bc
    #> 260: #d1a1bc
    #> 261: #d1a1bc
    #> 262: #d1a1bc
    #> 263: #d1a1bc

## Sector/industry codes

The functions within this package are designed to match strings (i.e. “agriculture”) to sector/industry codes.

    ots_sectors
    #> Key: <broad_sector_id>
    #>         broad_sector broad_sector_id  colour
    #>               <char>           <int>  <char>
    #> 1:       Agriculture               1 #74c0e2
    #> 2:     Manufacturing               2 #406662
    #> 3: Mining and Energy               3 #549e95
    #> 4:          Services               4 #8abdb6

    ots_industries
    #>                                industry_descr industry_id
    #>                                        <char>       <int>
    #>   1:                                    Wheat           1
    #>   2:                               Rice (raw)           2
    #>   3:                                     Corn           3
    #>   4:                            Other cereals           4
    #>   5:                          Cereal products           5
    #>  ---
    #> 166:                   166 Education services         166
    #> 167: 167 Government goods and services n.i.e.         167
    #> 168:               168 Services not allocated         168
    #> 169:               169 Trade-related services         169
    #> 170:              170 Other personal services         170

# Package functions

## Country code

The end user can use this function to find a dynamic ISO-3 code by providing a country name. This works by implementing partial search.

Basic examples:

    # Single match with no replacement
    ots_country_code("Chile")
    #> Key: <dynamic_code>
    #>      iso3 dynamic_code country continent  colour
    #>    <char>       <char>  <char>    <char>  <char>
    #> 1:    CHL          CHL   Chile  Americas #a1aafb

    # Single match with replacement
    ots_country_code("America")
    #> Key: <dynamic_code>
    #>      iso3 dynamic_code        country continent  colour
    #>    <char>       <char>         <char>    <char>  <char>
    #> 1:    ASM          ASM American Samoa   Oceania #a17cb0

    # Double match with no replacement
    ots_country_code("Germany")
    #> Key: <dynamic_code>
    #>      iso3 dynamic_code      country continent  colour
    #>    <char>       <char>       <char>    <char>  <char>
    #> 1:    DEU          DEU      Germany    Europe #d05555
    #> 2:    DEU        DEU.X West Germany    Europe #d05555

The function `ots_country_code()` is used by `ots_create_tidy_data()` in a way that you can pass parameters like `ots_create_tidy_data(... importers = "Chile" ...)` and it will automatically replace your input for a valid code in case there is a match. This will be covered in detail in the Trade Data section.

## Sector/industry code

The end user can find a code or a set of codes by looking for keywords for commodities or groups. The function `ots_commodity_code()` allows to search from the official commodities and groups in the Harmonized system:

    ots_sector_code(" AgriCulture ")
    #> Key: <broad_sector_id>
    #>    broad_sector broad_sector_id  colour
    #>          <char>           <int>  <char>
    #> 1:  Agriculture               1 #74c0e2
    ots_industry_code("  CeReaLS")
    #>    industry_descr industry_id
    #>            <char>       <int>
    #> 1:  Other cereals           4

## Trade data

This function downloads data for a single year and needs (at least) some filter parameters according to the query type.

Here we cover aggregated tables to describe the usage.

### Bilateral trade (aggregated)

If we want Chile-Argentina bilateral trade at community level in 2019:

    ots_create_tidy_data(
      years = 2019,
      importers = "chl",
      exporters = "arg",
      table = "itpde_imp_exp"
    )

We can pass two years or more, several reporters/partners, and filter by commodities with exact codes or code matching based on keywords:

    ots_create_tidy_data(
      years = 2018:2019,
      importers = c("chl", "Peru", "col"),
      exporters = c("arg", "Brazil"),
      table = "itpde_imp_exp"
    )

### Bilateral trade (sector)

    ots_create_tidy_data(
      years = 2018:2019,
      importers = c("chl", "Peru", "col"),
      exporters = c("arg", "Brazil"),
      table = "itpde_imp_exp_sec"
    )

### Aggregate trade (industry)

    ots_create_tidy_data(
      years = 2018:2019,
      importers = c("chl", "Peru", "col"),
      exporters = c("arg", "Brazil"),
      table = "itpde_ind"
    )