A macro-data request has several possible outcomes: observations, a valid empty result or a failure. Treating all three as a number creates fragile research code. OCaml's result matching makes the distinction visible at the boundary where the data enters an application.
This guide uses the FXMacroData OCaml client to request US inflation. The first program reports the row count or a formatted error. The next step is a deliberate validation layer before any statistical calculation.
Who this is for: Teams using OCaml who want a repeatable macro-data workflow with explicit inputs and understandable failure states.
Prerequisites
An OCaml project with opam, Lwt and the fxmacrodata package. The SDK guide links the opam package and source repository. Choose a date window covered by your FXMacroData access; historical and non-USD requests may require a subscription key.
- Lwt request
- Match result
- Validate rows
1. Add the package to a reproducible environment
The public package name is fxmacrodata on opam. Use your project's approved dependency workflow and retain the resolved package versions. Open the SDK guide for the package and repository links before wiring it into a larger application.
Keep any subscription credential in the execution environment supported by the client configuration, rather than embedding it in the program. Confirm the repository's configuration instructions for the installed version when using protected datasets.
2. Run the documented bounded request
The published client example keeps the asynchronous operation and the result branches visible:
let () =
let client = Fxmacrodata.create () in
match
Lwt_main.run
(Fxmacrodata.macro_indicator client ~currency:"usd"
~indicator:"inflation" ~start_date:"2026-01-01" ())
with
| Ok rows -> Printf.printf "Fetched %d rows\n" (List.length rows)
| Error e -> prerr_endline (Fxmacrodata.Error.to_string e)The date is a request boundary, not a claim that all observations in that range are freely available. Adjust it to the intended access window and keep a failed request in the Error branch.
3. Separate empty success from usable observations
An Ok result can still contain no rows. Check that case before computing a latest value, a difference or an average. A valid empty list means that this request supplied no observations; a zero would assert a value that the dataset did not return.
Inspect the installed client's row types and retain the series identity, reference period and unit with the values. Validate ordering before taking a first or last element. Do not let a downstream calculation infer chronological order from an undocumented list position.
4. Keep research failures actionable
At the application boundary, record the requested currency, indicator and date window with a failure. Keep credentials out of diagnostic strings. Distinguish a request that should be corrected from a temporary failure that may be retried according to the service response.
Once the input is validated, pass the observations to a pure calculation and return its result with the source context. That separation makes it possible to test the calculation with fixed inputs while keeping network and subscription behavior in one place.
Workflow checks
| Part | Purpose |
|---|---|
| Error | Report the request failure without a substitute value |
| Ok with no rows | Return an unavailable result to the caller |
| Ok with rows | Validate identity, units and ordering |
| Derived result | Retain the input series and period context |
Use the type boundary to protect the economic meaning
The value of explicit result handling becomes clear when the observation feeds another calculation. Suppose a report computes a change between the latest two eligible readings. A request failure, an empty list and a list containing only one reading are three distinct inputs. None supplies a defensible two-observation change, and none should quietly become an unchanged reading.
Keep that eligibility decision outside the pure calculation. First establish the series, order, units and required observations. Then pass a validated input to the function that computes the change. This makes a review of the economic assumption possible without inspecting network-handling code: the calculation has a named input and a defined reason for rejecting it.
In the finished report, an unavailable result should explain what could not be established without exposing authentication details. Measure whether invalid input reaches the numeric calculation and whether each displayed result retains the period it describes. OCaml’s branching helps make those decisions explicit; the analyst still has to define what a valid comparison means. That combination is useful when a small data request becomes a repeatedly generated research document.
Continue from the working example
Continue with the linked setup guide for supported installation and request options. Keep the selected series and its response context together as the workflow expands.
Sources and related guides
AI was used for research, creating images and editing.
