---
title: "Getting started with readimf"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting started with readimf}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

`readimf` provides tidy access to International Monetary Fund data through the
new IMF SDMX 3.0 API at <https://data.imf.org>. This vignette shows the main
workflows. The live calls are shown but not executed here, so that the vignette
builds without a network connection.

```{r, eval = TRUE}
library(readimf)
```

## The World Economic Outlook

The WEO is open and needs no key. Indicator and country codes are passed
directly.

```{r}
# Real GDP growth for the UK and US, 2018 to 2024
imf_weo("NGDP_RPCH", country = c("GBR", "USA"), start = 2018, end = 2024)
```

You can request a specific historical release for forecast evaluation:

```{r}
imf_weo("NGDP_RPCH", country = "GBR", vintage = "2025-10")
```

## Migrating from imfr: where did IFS go?

When the IMF retired International Financial Statistics it split the series
across thematic data flows with no official crosswalk. `imf_ifs()` accepts the
old IFS codes and routes them to their new homes. The supported series and
their destinations are shown by `imf_ifs_map()`:

```{r, eval = TRUE}
imf_ifs_map()
```

So a request for the UK consumer price index, formerly `PCPI_IX`, becomes:

```{r}
imf_ifs("PCPI_IX", country = "GBR", start = 2015)
```

Country coverage in the new data flows varies, especially for interest rates.
If a country returns nothing, try another.

## Discovering data

Browse the full catalogue, search it, and inspect a data flow's key structure:

```{r}
imf_dataflows()                 # the full catalogue
imf_search("balance of payments")
imf_dimensions("CPI")           # the dimension order for building a key
imf_codelist("CL_WEO_INDICATOR", agency = "IMF.RES")
```

Anything in the catalogue can be fetched with `imf_data()` by supplying a key
in the dimension order reported by `imf_dimensions()`:

```{r}
imf_data("CPI", key = "GBR.CPI._T.IX.M", start = 2020)
```

## Named database wrappers

Common databases have named wrappers that set sensible defaults:

```{r}
imf_cpi("GBR", measure = "inflation")
imf_dots("USA", "GBR", flow = "exports")
imf_cofer(currency = "USD", measure = "share")
imf_commodity("POILWTI", measure = "usd")
imf_gfs("GBR", indicator = "revenue")
```

## API keys

The World Economic Outlook is open. Restricted databases accept an optional key
through the `IMF_API_KEY` environment variable, which unlocks wildcard queries.