# Use case: the Big Data PE API

`apifetch` was extracted from the BigDataPE package, which wraps the Big Data PE platform — a public-data REST API run by the Government of the State of Pernambuco, Brazil. This vignette shows how that service maps onto a single `apifetch` profile, and is the canonical worked example of configuring the package for a real API.

## What is specific about Big Data PE

The Big Data PE API has two conventions that differ from the `apifetch` defaults:

- Authentication sends the token verbatim in the `Authorization` header (no `Bearer` prefix) — use `af_auth_raw()`.
- Pagination sends `limit`/`offset` as HTTP headers, not query parameters — use `af_paginate_offset("header")`.

It also returns a status column named `"Mensagem"` that we drop when combining chunks (`drop_cols = "Mensagem"`), and it is only reachable from the PE Conectado network or VPN, which we surface via `connect_hint`.

## Defining the profile

    library(apifetch)

    bigdatape <- af_api(
      endpoint     = "https://www.bigdata.pe.gov.br/api/buscar",
      service      = "BigDataPE",
      auth         = af_auth_raw(),
      pagination   = af_paginate_offset("header"),
      drop_cols    = "Mensagem",
      connect_hint = "Ensure you are on the PE Conectado network or VPN."
    )

## Storing a token and fetching

    af_store_token("dengue", "your-token-here", service = "BigDataPE")

    # A single page of 50 records
    dengue <- af_fetch(bigdatape, "dengue", limit = 50)

    # Everything, in chunks, with a progress message per chunk
    dengue_all <- af_fetch_all(
      bigdatape, "dengue",
      chunk_size = 50000,
      verbosity = 1
    )

## Note on language

Function and parameter names are English (R convention), but the API’s response column names and some values are Portuguese (e.g. `nu_notificacao`, `"BOA VIAGEM"`). That is intentional — they come straight from the upstream service.