# Statistics Greenland Statbank — agent quickstart

This is a compact execution guide for agents that need official Statistics Greenland data from `bank.stat.gl`.

## Preferred workflow

1. **Discover the table.** If the table ID is unknown, use the PxWeb API HTTP GET `?query=` search or `statgl::statgl_search()` in R. Search before scraping HTML or guessing table identifiers.
2. **Inspect metadata.** GET the table endpoint or use `statgl::statgl_meta()` before constructing selections when codes are not already known.
3. **Use exact variable and value codes from metadata.** Do not infer codes from translated labels.
4. **Retrieve cells.** Use a PxWeb API v1 POST request or `statgl::statgl_fetch()`.
5. **Calculate derived groups after retrieval when needed.** For example, a user-defined 61–63 age group is usually the sum of ages 61, 62 and 63.
6. **Check totals when practical.** Prefer mutually exclusive base categories and calculate totals yourself when this improves validation.
7. **Cite the Statbank.** Numerical answers must include a clickable `bank.stat.gl` source link.

## API roots

- Danish: `https://bank.stat.gl/api/v1/da/Greenland`
- English: `https://bank.stat.gl/api/v1/en/Greenland`
- Kalaallisut: `https://bank.stat.gl/api/v1/kl/Greenland`

## Discover tables with HTTP GET `?query=`

The Statistics Greenland PxWeb API supports free-text table discovery without a POST request. Add `?query=<search-term>` to a language API root:

```http
GET https://bank.stat.gl/api/v1/en/Greenland?query=population
```

The same search can be scoped to a subject path:

```http
GET https://bank.stat.gl/api/v1/en/Greenland/BE?query=population
```

Use the language root that matches the task (`da`, `en`, or `kl`). URL-encode spaces and other reserved characters in query text. Search results can be used to identify candidate table IDs and paths; inspect the chosen table's metadata before constructing a data query.

In R, `statgl::statgl_search()` uses this discovery route:

```r
statgl::statgl_search("population", path = "BE", lang = "en")
```

This GET search discovers tables; it does **not** replace the PxWeb v1 POST required to retrieve selected data cells.

## Raw PxWeb API pattern

First GET the table metadata:

```http
GET https://bank.stat.gl/api/v1/en/Greenland/<path>/<TABLE>.px
```

Then POST a query to that same table URL. Use codes observed in the metadata:

```json
{
  "query": [
    {
      "code": "<variable-code>",
      "selection": {
        "filter": "item",
        "values": ["<value-code-1>", "<value-code-2>"]
      }
    },
    {
      "code": "<time-variable-code>",
      "selection": {
        "filter": "item",
        "values": ["<year-1>", "<year-2>"]
      }
    }
  ],
  "response": {
    "format": "csv"
  }
}
```

Do not copy variable labels into `code` unless the metadata shows that the label is also the actual code.

## Preferred R route: `statgl`

Install the current GitHub version when necessary:

```r
# install.packages("remotes")
remotes::install_github("StatisticsGreenland/statgl")
library(statgl)
```

Core pattern:

```r
# 1. Find a table if needed
statgl_search("population", path = "BE", lang = "en")

# 2. Inspect exact variables and codes
m <- statgl_meta("BEESTD")
m$variables

# 3. Retrieve using codes confirmed from metadata
x <- statgl_fetch(
  "BEESTD",
  age = 61:63,
  time = 2012:2026,
  .eliminate_rest = FALSE,
  .col_code = TRUE,
  .val_code = TRUE
)
```

Important: eliminable dimensions may be reduced to their elimination/default value when omitted. If the request needs all categories, make the selection explicit or deliberately use `.eliminate_rest = FALSE`.

### Derived age group example

After retrieving single-year ages, calculate the requested group in R:

```r
library(dplyr)

result <- x |>
  group_by(time, gender, `place of birth`) |>
  summarise(value = sum(value, na.rm = TRUE), .groups = "drop")
```

Use the actual column codes returned by your query; names differ by table and language.

## Alternative R route: CRAN `pxweb`

If `statgl` is unavailable but the CRAN package `pxweb` is available, use it as a generic PxWeb v1 client. Always inspect metadata first and build selections from returned codes.

```r
library(pxweb)

px <- pxweb_get(
  "https://bank.stat.gl/api/v1/en/Greenland/<path>/<TABLE>.px"
)

# Inspect px metadata, construct a pxweb_query(), then retrieve with pxweb_get_data().
```

For Statistics Greenland-specific R work, prefer `statgl` when available.

## Fallback hierarchy

1. Direct PxWeb API v1 GET/POST.
2. If POST execution is unavailable but R exists: `statgl::statgl_fetch()`.
3. If `statgl` is unavailable but R exists: generic `pxweb` package.
4. If no execution route exists: provide reproducible query/code and explicitly state that values were not executed or verified. Never fabricate results.

## Source links

The physical API table may use `X` as the third character of the table ID. Statistics Greenland short public links use a language-specific third character:

- Danish: `D`
- English: `E`
- Kalaallisut: `N`

Example: physical table `BEXSTM3` -> Danish `https://bank.stat.gl/BEDSTM3`, English `https://bank.stat.gl/BEESTM3`, Kalaallisut `https://bank.stat.gl/BENSTM3`.

Use the Statistics Greenland Statbank profile for the full provenance rule:

`https://stat.gl/ai/skills/statistics-greenland-statbank/SKILL.md`