Java library

sdmx-dl API is a library designed as a facade for the SDMX model and APIs.

Web example:

SdmxWebManager
    .ofServiceLoader()
    .usingName("ECB")
    .getData(DataRequest
        .builder()
        .flowOf("EXR")
        .keyOf("M.CHF+USD.EUR.SP00.A")
        .build())
    .forEach(series -> System.out.printf(Locale.ROOT, "%s: %d obs%n", series.getKey(), series.getObs().size()));

File example:

SdmxFileManager
    .ofServiceLoader()
    .usingFile(dataFile())
    .getData(DataRequest
        .builder()
        .flowOf("data")
        .keyOf("A.DEU.1.0.319.0.UBLGE")
        .build())
    .forEach(series -> System.out.printf(Locale.ROOT, "%s: %d obs%n", series.getKey(), series.getObs().size()));

Filtering example (time range and observation count):

SdmxWebManager
    .ofServiceLoader()
    .usingName("ECB")
    .getData(DataRequest
        .builder()
        .flowOf("EXR")
        .keyOf("M.CHF.EUR.SP00.A")
        .startPeriodOf("2020")     // inclusive lower bound
        .endPeriodOf("2022-12")    // inclusive upper bound
        .lastNObservations(3)      // keep only the last 3 observations
        .build())
    .forEach(series -> System.out.printf(Locale.ROOT, "%s: %d obs%n", series.getKey(), series.getObs().size()));

Filters (startPeriod, endPeriod, firstNObservations, lastNObservations) are always (re-)applied client-side, so results are consistent across all sources. When a source supports them server-side, they are also pushed down as a bandwidth optimization; otherwise the full series is downloaded then filtered locally.

Structure overview

flowchart BT
    api
    subgraph formats
        format-base[base]
        csv
        kryo
        protobuf
        xml
    end
    subgraph providers
        provider-base[base]
        connectors
        ri
        dialects
        px
    end
    subgraph applications
        cli
        desktop
        grpc
    end

    formats --> api
    providers --> formats
    applications --> providers

Dependencies setup

sdmx-dl is distributed in two different ways: a standard JAR hierarchy, and a standalone uber JAR containing all the implementations and their dependencies. Most of the standalone JAR’s dependencies are shaded i.e. they are hidden in alternative packages. This allows sdmx-dl to be used as a zero-dependency library in projects without conflicting with other dependencies.

Standalone uber JAR (zero-dependency):

<dependencies>
  <dependency>
    <groupId>com.github.nbbrd.sdmx-dl</groupId>
    <artifactId>sdmx-dl-standalone</artifactId>
  </dependency>
</dependencies>

Standard JAR hierarchy:

<dependencies>
  <dependency>
    <groupId>com.github.nbbrd.sdmx-dl</groupId>
    <artifactId>sdmx-dl-api</artifactId>
  </dependency>
  <dependency>
    <groupId>com.github.nbbrd.sdmx-dl</groupId>
    <artifactId>sdmx-dl-ri</artifactId>
    <scope>runtime</scope>
  </dependency>
  <dependency>
    <groupId>com.github.nbbrd.sdmx-dl</groupId>
    <artifactId>sdmx-dl-dialects</artifactId>
    <scope>runtime</scope>
  </dependency>
</dependencies>