Author: Mauricio Vargas S.
Date: 2025-09-22

# Basic usage

#### Mauricio Vargas S.

#### 2025-09-22

# 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].

To improve the presentation of the tables I shall use `tibble` besides `tradestatistics`.

    library(tradestatistics)
    library(tibble)

# Package data

## Available tables

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

    as_tibble(ots_tables)
    #> # A tibble: 11 × 3
    #>    table             description                                          source
    #>    <chr>             <chr>                                                <chr>
    #>  1 commodities       Commodities metadata (HS codes, 6 digits long)       Based…
    #>  2 commodities_short Commodities metadata (HS codes, 4 digits long)       Based…
    #>  3 countries         Countries metadata                                   Based…
    #>  4 gdp_deflator      GDP deflator (2020 = 100)                            Based…
    #>  5 sections          Sections metadata (HS codes)                         Based…
    #>  6 year_range        Minimum and maximum years with available data        Based…
    #>  7 yc                Commodity trade at aggregated level (Year and Commo… Based…
    #>  8 yr                Reporter trade at aggregated level (Year and Report… Based…
    #>  9 yrc               Reporter trade at commodity level (Year, Reporter a… Based…
    #> 10 yrp               Reporter-Partner trade at aggregated level (Year, R… Based…
    #> 11 yrpc              Reporter-Partner trade at commodity level (Year, Re… Based…

You might notice the tables have a pattern. The letters indicate the presence of columns that account for the level of detail in the data:

- `y`: year column.
- `r`: reporter column
- `p`: partner column
- `c`: commodity column

The most aggregated table is `yr` which basically says how many dollars each country exports and imports for a given year.

The less aggregated table is `yrpc` which says how many dollars of each of the 1,242 commodities from the Harmonized System each country exports to other countries and imports from other countries.

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:

    as_tibble(ots_countries)
    #> # A tibble: 263 × 5
    #>    country_iso country_name          continent_id continent_name continent_color
    #>    <chr>       <chr>                        <int> <chr>          <chr>
    #>  1 DZA         Algeria                          1 Africa         #74c0e2
    #>  2 AGO         Angola                           1 Africa         #74c0e2
    #>  3 BEN         Benin                            1 Africa         #74c0e2
    #>  4 BWA         Botswana                         1 Africa         #74c0e2
    #>  5 IOT         Br. Indian Ocean Ter…            1 Africa         #74c0e2
    #>  6 BFA         Burkina Faso                     1 Africa         #74c0e2
    #>  7 BDI         Burundi                          1 Africa         #74c0e2
    #>  8 CPV         Cabo Verde                       1 Africa         #74c0e2
    #>  9 CMR         Cameroon                         1 Africa         #74c0e2
    #> 10 CAF         Central African Rep.             1 Africa         #74c0e2
    #> # ℹ 253 more rows

## Commodity codes

The Package Functions section explains that you don’t need to memorize all HS codes. The functions within this package are designed to match strings (i.e. “apple”) to valid HS codes (i.e. “0808”).

    as_tibble(ots_commodities)
    #> # A tibble: 6,898 × 8
    #>    commodity_code commodity_code_short commodity_name  chapter_code chapter_name
    #>    <chr>          <chr>                <chr>           <chr>        <chr>
    #>  1 010121         0101                 Horses; live, … 01           Animals; li…
    #>  2 010129         0101                 Horses; live, … 01           Animals; li…
    #>  3 010130         0101                 Asses; live     01           Animals; li…
    #>  4 010190         0101                 Mules and hinn… 01           Animals; li…
    #>  5 010221         0102                 Cattle; live, … 01           Animals; li…
    #>  6 010229         0102                 Cattle; live, … 01           Animals; li…
    #>  7 010231         0102                 Buffalo; live,… 01           Animals; li…
    #>  8 010239         0102                 Buffalo; live,… 01           Animals; li…
    #>  9 010290         0102                 Bovine animals… 01           Animals; li…
    #> 10 010310         0103                 Swine; live, p… 01           Animals; li…
    #> # ℹ 6,888 more rows
    #> # ℹ 3 more variables: section_code <chr>, section_name <chr>,
    #> #   section_color <chr>

## Inflation data

This table is provided to be used with `ots_gdp_deflator_adjustment()`.

    as_tibble(ots_gdp_deflator)
    #> # A tibble: 7,070 × 4
    #>    year_from year_to country_iso gdp_deflator
    #>        <int>   <int> <chr>              <dbl>
    #>  1      1988    1989 ABW                 1.04
    #>  2      1989    1990 ABW                 1.06
    #>  3      1990    1991 ABW                 1.06
    #>  4      1991    1992 ABW                 1.04
    #>  5      1992    1993 ABW                 1.05
    #>  6      1993    1994 ABW                 1.06
    #>  7      1994    1995 ABW                 1.03
    #>  8      1995    1996 ABW                 1.03
    #>  9      1996    1997 ABW                 1.04
    #> 10      1997    1998 ABW                 1.07
    #> # ℹ 7,060 more rows

# Package functions

## Country code

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

Basic examples:

    # Single match with no replacement
    as_tibble(ots_country_code("Chile"))
    #> # A tibble: 1 × 5
    #>   country_iso country_name continent_id continent_name continent_color
    #>   <chr>       <chr>               <int> <chr>          <chr>
    #> 1 CHL         Chile                   2 Americas       #406662

    # Single match with replacement
    as_tibble(ots_country_code("America"))
    #> # A tibble: 0 × 5
    #> # ℹ 5 variables: country_iso <chr>, country_name <chr>, continent_id <int>,
    #> #   continent_name <chr>, continent_color <chr>

    # Double match with no replacement
    as_tibble(ots_country_code("Germany"))
    #> # A tibble: 2 × 5
    #>   country_iso country_name           continent_id continent_name continent_color
    #>   <chr>       <chr>                         <int> <chr>          <chr>
    #> 1 DDR         Dem. Rep. of Germany …            4 Europe         #8abdb6
    #> 2 DEU         Germany                           4 Europe         #8abdb6

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(... reporters = "Chile" ...)` and it will automatically replace your input for a valid ISO in case there is a match. This will be covered in detail in the Trade Data section.

## Commodity 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:

    as_tibble(ots_commodity_code(commodity = " Horse ", section = " ANIMAL "))
    #> # A tibble: 13 × 6
    #>    commodity_code commodity_name          chapter_code chapter_name section_code
    #>    <chr>          <chr>                   <chr>        <chr>        <chr>
    #>  1 010121         Horses; live, pure-bre… 01           Animals; li… 01
    #>  2 010129         Horses; live, other th… 01           Animals; li… 01
    #>  3 020500         Meat; of horses, asses… 02           Meat and ed… 01
    #>  4 020680         Offal, edible; of shee… 02           Meat and ed… 01
    #>  5 020690         Offal, edible; of shee… 02           Meat and ed… 01
    #>  6 030245         Fish; fresh or chilled… 03           Fish and cr… 01
    #>  7 030355         Fish; frozen, jack and… 03           Fish and cr… 01
    #>  8 030554         Dried herrings, anchov… 03           Fish and cr… 01
    #>  9 050290         Animal products; badge… 05           Animal orig… 01
    #> 10 010110         Horses, asses, mules a… 01           Animals; li… 01
    #> 11 050300         Animal products; horse… 05           Animal orig… 01
    #> 12 010111         Horses; live, pure-bre… 01           Animals; li… 01
    #> 13 010119         Horses; live, other th… 01           Animals; li… 01
    #> # ℹ 1 more variable: section_name <chr>

## 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 at commodity level (Year - Reporter - Partner - Commodity Code)

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

    yrpc <- ots_create_tidy_data(
      years = 2019,
      reporters = "chl",
      partners = "arg",
      table = "yrpc"
    )

    as_tibble(yrpc)

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

    # Note that here I'm passing Peru and not per which is the ISO code for Peru
    # The same applies to Brazil
    yrpc2 <- ots_create_tidy_data(
      years = 2018:2019,
      reporters = c("chl", "Peru", "bol"),
      partners = c("arg", "Brazil"),
      commodities = c("01", "food"),
      table = "yrpc"
    )

The `yrpc` table returns some fields that deserve an explanation which can be seen at tradestatistics.io. This example is interesting because “01” return a set of commodities (all commodities starting with 01, which is the commodity group “Animals; live”), but “food” return all commodities with a matching description (“1601”, “1806”, “1904”, etc.). In addition, not all the requested commodities are exported from each reporter to each partner, therefore a warning is returned.

### Bilateral trade at aggregated level (Year - Reporter - Partner)

If we want Chile-Argentina bilateral trade at aggregated level in 2018 and 2019:

    yrp <- ots_create_tidy_data(
      years = 2018:2019,
      reporters = c("chl", "per"),
      partners = "arg",
      table = "yrp"
    )

This table accepts different years, reporters and partners just like `yrpc`.

### Reporter trade at commodity level (Year - Reporter - Commodity Code)

If we want Chilean trade at commodity level in 2019 with respect to commodity “010121” which means “Horses; live, pure-bred breeding animals”:

    yrc <- ots_create_tidy_data(
      years = 2019,
      reporters = "chl",
      commodities = "010121",
      table = "yrc"
    )

This table accepts different years, reporters and commodity codes just like `yrpc`.

All the variables from this table are documented at tradestatistics.io.

### Reporter trade at aggregated level (Year - Reporter)

If we want the aggregated trade of Chile, Argentina and Peru in 2018 and 2019:

    yr <- ots_create_tidy_data(
      years = 2018:2019,
      reporters = c("chl", "arg", "per"),
      table = "yr"
    )

This table accepts different years and reporters just like `yrpc`.

All the variables from this table are documented at tradestatistics.io.

### Commodity trade at aggregated level (Year - Commodity Code)

If we want all commodities traded in 2019:

    yc <- ots_create_tidy_data(
      years = 2019,
      table = "yc"
    )

If we want the traded values of the commodity “010121” which means “Horses; live, pure-bred breeding animals” in 2019:

    yc2 <- ots_create_tidy_data(
      years = 2019,
      commodities = "010121",
      table = "yc"
    )

This table accepts different years just like `yrpc`.

## Inflation adjustment

Taking the `yr` table from above, we can use `ots_gdp_deflator_adjustment()` to convert dollars from 2018 and 2019 to dollars of 2000:

    inflation <- ots_gdp_deflator_adjustment(yr, reference_year = 2000)
    as_tibble(inflation)