feat: Analytics data response (#122)

Author: larshelge

README.md

@@ -300,15 +300,32 @@ DataValueSetResponse response = dhis2.saveDataValueSet(file, options);
 
 This section explains operations for the analytics engine.
 
+### Get analytics data
+
+To retrieve analytics data:
+
+```java
+AnalyticsQuery query = AnalyticsQuery.instance()
+    .addDataDimension(List.of("fbfJHSPpUQD", "cYeuwXTCPkU", "Jtf34kNZhzP"))
+    .addPeriodDimension(List.of("202501", "202502", "202503"))
+    .addDimension("fMZEcRHuamy", List.of("qkPbeWaFsnU", "wbrDrL2aYEc"))
+    .addOrgUnitFilter(List.of("ImspTQPwCqd"))
+    .setIncludeMetadataDetails(true);
+
+AnalyticsData data = dhis2.getAnalyticsData(query);
+```
+
 ### Get analytics data value set
 
 To retrieve analytics data in the data value set format:
 
 ```java
-DataValueSet dvs = dhis2.getAnalyticsDataValueSet(AnalyticsQuery.instance()
+AnalyticsQuery query = AnalyticsQuery.instance()
     .addDimension(Dimension.DIMENSION_DX, "cYeuwXTCPkU", "Jtf34kNZhzP")
     .addDimension(Dimension.DIMENSION_OU, "O6uvpzGd5pu", "fdc6uOvgoji")
-    .addDimension(Dimension.DIMENSION_PE, "202007", "202008"));
+    .addDimension(Dimension.DIMENSION_PE, "202007", "202008");
+
+DataValueSet dvs = dhis2.getAnalyticsDataValueSet(query);
 ```
 
 ### Write analytics data value set to file
@@ -322,7 +339,7 @@ AnalyticsQuery query = AnalyticsQuery.instance()
     .addDimension(Dimension.DIMENSION_PE, "202007", "202008");
 
 File file = new File("/tmp/data-value-set.json");
-    
+
 dhis2.writeAnalyticsDataValueSet(query, file);
 ```
 

src/main/java/org/hisp/dhis/BaseDhis2.java

@@ -439,8 +439,13 @@ protected URI getAnalyticsQuery(URIBuilder uriBuilder, AnalyticsQuery query) {
     addParameter(uriBuilder, "skipData", query.getSkipData());
     addParameter(uriBuilder, "skipRounding", query.getSkipRounding());
     addParameter(uriBuilder, "ignoreLimit", query.getIgnoreLimit());
-    addParameter(uriBuilder, "inputIdScheme", query.getInputIdScheme());
+    addParameter(uriBuilder, "showHierarchy", query.getShowHierarchy());
+    addParameter(uriBuilder, "includeNumDen", query.getIncludeNumDen());
+    addParameter(uriBuilder, "includeMetadataDetails", query.getIncludeMetadataDetails());
     addParameter(uriBuilder, "outputIdScheme", query.getOutputIdScheme());
+    addParameter(uriBuilder, "outputOrgUnitIdScheme", query.getOutputOrgUnitIdScheme());
+    addParameter(uriBuilder, "outputDataElementIdScheme", query.getOutputDataElementIdScheme());
+    addParameter(uriBuilder, "inputIdScheme", query.getInputIdScheme());
 
     return HttpUtils.build(uriBuilder);
   }
@@ -939,7 +944,7 @@ private void handleErrorsForGet(CloseableHttpResponse response, String url)
    * @param content the JSON content.
    * @param type the object type.
    * @return an object.
-   * @throws IOException
+   * @throws IOException if reading failed.
    */
   protected <T> T readValue(String content, Class<T> type) throws IOException {
     return objectMapper.readValue(content, type);

src/main/java/org/hisp/dhis/Dhis2.java

@@ -85,6 +85,7 @@
 import org.hisp.dhis.model.SystemSettings;
 import org.hisp.dhis.model.TableHook;
 import org.hisp.dhis.model.Visualization;
+import org.hisp.dhis.model.analytics.AnalyticsData;
 import org.hisp.dhis.model.completedatasetregistration.CompleteDataSetRegistration;
 import org.hisp.dhis.model.completedatasetregistration.CompleteDataSetRegistrationImportOptions;
 import org.hisp.dhis.model.dashboard.Dashboard;
@@ -2318,6 +2319,21 @@ public String getDataValueFile(DataValueQuery query) {
         config.getResolvedUriBuilder().appendPath("dataValues/files"), query);
   }
 
+  // -------------------------------------------------------------------------
+  // Analytics data
+  // -------------------------------------------------------------------------
+
+  /**
+   * Retrieves a {@link AnalyticsData}.
+   *
+   * @param query the {@link AnalyticsQuery}.
+   * @return {@link AnalyticsData}.
+   */
+  public AnalyticsData getAnalyticsData(AnalyticsQuery query) {
+    return getAnalyticsResponse(
+        config.getResolvedUriBuilder().appendPath("analytics"), query, AnalyticsData.class);
+  }
+
   // -------------------------------------------------------------------------
   // Analytics data value set
   // -------------------------------------------------------------------------

src/main/java/org/hisp/dhis/model/analytics/AnalyticsData.java

@@ -0,0 +1,53 @@
+/*
+ * Copyright (c) 2004-2025, University of Oslo
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ * Redistributions of source code must retain the above copyright notice, this
+ * list of conditions and the following disclaimer.
+ *
+ * Redistributions in binary form must reproduce the above copyright notice,
+ * this list of conditions and the following disclaimer in the documentation
+ * and/or other materials provided with the distribution.
+ * Neither the name of the HISP project nor the names of its contributors may
+ * be used to endorse or promote products derived from this software without
+ * specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+ * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+ * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+package org.hisp.dhis.model.analytics;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import java.util.List;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+import lombok.ToString;
+
+@Getter
+@Setter
+@ToString
+@NoArgsConstructor
+public class AnalyticsData {
+  @JsonProperty private List<AnalyticsHeader> headers;
+
+  @JsonProperty private AnalyticsMetaData metaData;
+
+  @JsonProperty private List<List<String>> rows;
+
+  @JsonProperty private Integer height;
+
+  @JsonProperty private Integer width;
+
+  @JsonProperty private Integer headerWidth;
+}

src/main/java/org/hisp/dhis/model/analytics/AnalyticsHeader.java

@@ -0,0 +1,51 @@
+/*
+ * Copyright (c) 2004-2025, University of Oslo
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ * Redistributions of source code must retain the above copyright notice, this
+ * list of conditions and the following disclaimer.
+ *
+ * Redistributions in binary form must reproduce the above copyright notice,
+ * this list of conditions and the following disclaimer in the documentation
+ * and/or other materials provided with the distribution.
+ * Neither the name of the HISP project nor the names of its contributors may
+ * be used to endorse or promote products derived from this software without
+ * specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+ * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+ * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+package org.hisp.dhis.model.analytics;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+import lombok.ToString;
+import org.hisp.dhis.model.ValueType;
+
+@Getter
+@Setter
+@ToString
+@NoArgsConstructor
+public class AnalyticsHeader {
+  @JsonProperty private String name;
+
+  @JsonProperty private String column;
+
+  @JsonProperty private ValueType valueType;
+
+  @JsonProperty private Boolean hidden;
+
+  @JsonProperty private Boolean meta;
+}

src/main/java/org/hisp/dhis/model/analytics/AnalyticsMetaData.java

@@ -0,0 +1,46 @@
+/*
+ * Copyright (c) 2004-2025, University of Oslo
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ * Redistributions of source code must retain the above copyright notice, this
+ * list of conditions and the following disclaimer.
+ *
+ * Redistributions in binary form must reproduce the above copyright notice,
+ * this list of conditions and the following disclaimer in the documentation
+ * and/or other materials provided with the distribution.
+ * Neither the name of the HISP project nor the names of its contributors may
+ * be used to endorse or promote products derived from this software without
+ * specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+ * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+ * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+package org.hisp.dhis.model.analytics;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import java.util.List;
+import java.util.Map;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+import lombok.ToString;
+
+@Getter
+@Setter
+@ToString
+@NoArgsConstructor
+public class AnalyticsMetaData {
+  @JsonProperty private Map<String, MetaDataItem> items;
+
+  @JsonProperty private Map<String, List<String>> dimensions;
+}

src/main/java/org/hisp/dhis/model/analytics/MetaDataItem.java

@@ -0,0 +1,62 @@
+/*
+ * Copyright (c) 2004-2025, University of Oslo
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ * Redistributions of source code must retain the above copyright notice, this
+ * list of conditions and the following disclaimer.
+ *
+ * Redistributions in binary form must reproduce the above copyright notice,
+ * this list of conditions and the following disclaimer in the documentation
+ * and/or other materials provided with the distribution.
+ * Neither the name of the HISP project nor the names of its contributors may
+ * be used to endorse or promote products derived from this software without
+ * specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+ * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+ * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+package org.hisp.dhis.model.analytics;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+import lombok.ToString;
+
+@Getter
+@Setter
+@ToString
+@NoArgsConstructor
+public class MetaDataItem {
+  @JsonProperty private String uid;
+
+  @JsonProperty private String name;
+
+  @JsonProperty private String dimensionType;
+
+  @JsonProperty private String code;
+
+  @JsonProperty private String dimensionItemType;
+
+  @JsonProperty private String valueType;
+
+  @JsonProperty private String totalAggregationType;
+
+  @JsonProperty private String startDate;
+
+  @JsonProperty private String endDate;
+
+  @JsonProperty private String legendSet;
+
+  @JsonProperty private String aggregationType;
+}