Position Green API: Data Points

Modified on Tue, 21 Jul at 8:47 AM

TABLE OF CONTENTS

Specifics
Properties of a data point object
- Meta data properties
- Data point values properties
Get data for Data Points
Query Data Points in API

A data point refers to the data submitted by a reporter, presented in a flat structure.

Specifics

To address the unique characteristics of the data point endpoint, which differs from other endpoints containing more data, and to avoid obvious problems of data redundancy in a flat structure (where metadata is repeated for one or more data points), a streaming solution is implemented.

The returned stream will exclusively include data points with values, while those without any value will be filtered out.

Properties of a data point object

Meta data properties

Property	Data Type	Description
orgUnitPrettyId	nullable string	PrettyId of the organization unit
orgUnitLabel	nullable string	The organization unit the data belongs to
orgUnitTags	nullable string[]	Tags that are specified on an organization unit
reportingYearLabel	nullable string	Reporting year a registration belongs to
reportingYearId	string (uuid)	Reporting year ID a registration belongs to
periodName	nullable string	The name of the period registration belongs to
periodMoniker	nullable string	The moniker suggests the time period a registration belongs to
periodStartDate	nullable string	The start date of the period a registration belongs to
aspectName	nullable string	The aspect it belongs to
aspectId	string (uuid)	The ID of aspect it belongs to
measureName	nullable string	The name of the measure
measureId	string (uuid)	The ID of the measure
measureGlobalId	nullable string (uuid)	The globalId of the measure
measurePrettyId	nullable string	PrettyId of the measure
measureTags	nullable string[]	A list of tags that belongs to the measure
measurePointId	nullable string (uuid)	The ID of measure point
registrationResponsibleEmail	nullable string	An email address of a reporter that is responsible for reporting the data
registrationResponsibleName	nullable string	A full name of reporter that is responsible for reporting the data
registrationLastUpdateUtc	nullable integer (int64)	A unix timestamp (milliseconds) that indicates when the data point was last updated
registrationConfirmed	boolean	The confirmation status of the registration

Data point values properties

Property	Data Type	Description
measurePointTags	nullable string[]	A list of tags. They can be set in Measure Builder and is recommended way of identifying a control
controlType	string (enum)	Type of control belonging to the data point (e.g. `Unknown`, `Dropdown`, `Number`, `Date`, `Calculation`, `Sum`, `YesNo`, `File`, `Text`)
dataPointControlName	nullable string	The name of the data point. Can be complex with separators `!!` if data point belongs to an iterative control.
dataDisplayValue	nullable string	Display name shown to the reporter
dataUnit	nullable string	The unit of the value belonging to the data point
dataValueType	string (enum)	The type of value used as discriminator (e.g. `Unknown`, `Numeric`, `Text`, `Dropdown`, `File`, `Bool`)
dataValue	nullable string	The actual data of the data point
rowId	nullable string (uuid)	The id indicating which data points belong to each other. Also known as correlating Id

Get data for Data Points

/datapoints

GET https://api.positiongreen.com/v1/datapoints

Useful when fetching data for a data-lake or BI-system with optional input to get delta-records.

Output is a flat and consistent dataset with data registered and calculated in Position Green.

Query Parameters

Name	Type	Description
yearId*	string (uuid)	Required. ID (GUID) of the reporting year – as retrieved from /years (e.g., `0f80635f-1215-400b-924a-e365cc601d31`)
measureIds	string[] (uuid)	Optional array of measure identifiers to filter by specific measures
measureGlobalIds	string[] (uuid)	Optional array of global measure identifiers for measure filtering
measurePrettyIds	string[]	Optional array of measure pretty IDs for measure filtering
orgUnitIds	string[] (uuid)	Optional array of organization unit identifiers to filter by specific units
orgUnitGlobalIds	string[] (uuid)	Optional array of global organization unit identifiers
includeChildren	boolean	Whether to include child organization units in the filter. Default: `false`
startDate	string	Optional start date filter in ISO 8601 format (e.g. `2024-01-01`)
endDate	string	Optional end date filter in ISO 8601 format (e.g. `2024-12-31`)
lastModifiedStart	integer (int64)	Optional Unix timestamp in milliseconds for filtering by modification date start
lastModifiedEnd	integer (int64)	Optional Unix timestamp in milliseconds for filtering by modification date end
confirmationState	string (enum)	Filter by confirmation status: `Confirmed` (default), `NotConfirmed`, or `All`
sortDirection	string (enum)	Sort direction for results: `Ascending` (default) or `Descending`
first	integer (int32)	Maximum number of items to return. Default: `2147483647`
after	string	Optional cursor pointing to where to continue retrieving data points

200: OK Success	Returns the paginated list of data points matching the criteria. See response example below.
400: Bad Request	Validation errors or missing required `yearId` parameter.
401: Unauthorized	Authentication required.
500: Server Error	Internal server error occurred while retrieving data points.

Example of a curl request

curl --location "<api url>/v1/datapoints?yearId=<year_id>" --header "client_id: <client_id>" --header "client_secret: <clientsecret>" --no-buffer

By executing a cURL request in a console, it is possible to observe that the data is streamed out from the endpoint.

Example of a response

Below is an example of a registration with two distinct data points. It is important to note that while the metadata for the registration remains the same, the data for each data point differs.

{
    "items": [
        {
            "cursor": "cGFnZTs5",
            "node": {
                "orgUnitPrettyId": "SOME_PRETTY_ID",
                "orgUnitLabel": "Organisation unit 1",
                "orgUnitTags": ["tag1", "tag2", "tag3"],
                "reportingYearLabel": "2024",
                "reportingYearId": "9cagdfg31a-efg6-4747-9bjrt-49dc4e34563448",
                "periodName": "January",
                "periodMoniker": "M1",
                "periodStartDate": "2024-01-01T00:00:00.0000000+01:00",
                "aspectName": "Aspect name 1",
                "aspectId": "e0265592-dsd7-44hf-b433-fd9a5ty3bdc7",
                "measureName": "Measure name 1",
                "measureId": "ed454f906-9999-48fc-9c44-420we65654f8",
                "measureGlobalId": "1hfghdeac5-c297-7gfd-95ad-4b43543534552",
                "measurePrettyId": "Measure pretty name 1",
                "measureTags": ["tag1", "tag2", "tag3"],
                "measurePointId": "8basd90-d884-4asd8-8fads1-1a6da0e0df",
                "measurePointTags": ["tag1", "tag2", "tag3"],
                "registrationResponsibleEmail": "test+John.Doe+D310D6@testmail.com",
                "registrationResponsibleName": "John Doe",
                "registrationLastUpdateUtc": 1677680020228,
                "registrationConfirmed": true,
                "controlType": "Number",
                "dataPointControlName": "measure_dfd",
                "dataDisplayValue": "Summary of first measure",
                "dataUnit": "ton",
                "dataValueType": "Numeric",
                "dataValue": "0",
                "rowId": null
            }
        },
        {
            "cursor": "cGFnZTs5",
            "node": {
                "orgUnitPrettyId": "SOME_PRETTY_ID",
                "orgUnitLabel": "Organisation unit 1",
                "orgUnitTags": ["tag1", "tag2", "tag3"],
                "reportingYearLabel": "2024",
                "reportingYearId": "9cagdfg31a-efg6-4747-9bjrt-49dc4e34563448",
                "periodName": "January",
                "periodMoniker": "M1",
                "periodStartDate": "2024-01-01T00:00:00.0000000+01:00",
                "aspectName": "Aspect name 1",
                "aspectId": "e0265592-dsd7-44hf-b433-fd9a5ty3bdc7",
                "measureName": "Measure name 1",
                "measureId": "ed454f906-9999-48fc-9c44-420we65654f8",
                "measureGlobalId": "1hfghdeac5-c297-7gfd-95ad-4b43543534552",
                "measurePrettyId": "Measure pretty name 1",
                "measureTags": ["tag1", "tag2", "tag3"],
                "measurePointId": "8basd90-d884-4asd8-8fads1-1a6da0e0df",
                "measurePointTags": ["tag1", "tag2", "tag3"],
                "registrationResponsibleEmail": "test+John.Doe+D310D6@testmail.com",
                "registrationResponsibleName": "John Doe",
                "registrationLastUpdateUtc": 1677680020228,
                "registrationConfirmed": true,
                "controlType": "Number",
                "dataPointControlName": "measure_xyz",
                "dataDisplayValue": "Summary of first measure",
                "dataUnit": "m3",
                "dataValueType": "Numeric",
                "dataValue": "10",
                "rowId": "201b9192-e565-4680-ad64-30fd78dc4b6d"
            }
        }
    ],
    "totalCount": 1,
    "pageInfo": {
        "startCursor": "cGFnZTs5",
        "endCursor": "cGFnZTs5",
        "hasNextPage": true
    }
}

Query Data Points in API

When querying using the "startDate" and "endDate" parameters, registrations will be returned where the period end date falls within the specified range. For example, if you filter on "startDate" as '2019-12-01', you will receive all registrations where the period end date is later than December 1, 2019. This is applicable when the measure is configured to be reported yearly, and the registration's start date is January 1, 2019, and the end date is December 31, 2019, following a calendar year.

When querying using the "lastModifiedStart" and "lastModifiedEnd" parameters, registrations will be returned where the "registrationLastUpdateUtc" timestamp falls within the specified range. This parameter operates independently of time zones and provides high precision, allowing for queries even at the millisecond level.

Querying using the "confirmationState" parameter retrieves registrations with a specific status. The "confirmationState" parameter accepts an Enum value, and the default value is Confirmed.

public enum ConfirmationState
{
    [EnumMember(Value = "All")]
    All,
    [EnumMember(Value = "Confirmed")]
    Confirmed,
    [EnumMember(Value = "NotConfirmed")]
    NotConfirmed
}

You can perform queries using "measureIds", "measureGlobalIds", or "measurePrettyIds". It is possible to query using a single identifier or an array of multiple identifiers.

Sorting

Sorting results is supported via the "sortDirection" parameter. The default behavior is Ascending.

public enum SortDirection
{
    Ascending,
    Descending
}

To support pagination, there are two specific parameters: "first" and "after". However, due to the flat structure of the data and the uncertainty of the number of data points in each registration, these parameters can only be used at the registration level. The "first" parameter indicates the number of registrations to be returned by the endpoint. The default value is 2147483647 (int.MaxValue), which retrieves all registrations. You can specify a specific number of registrations as well.

Note: Every request response contains the following pagination footer section:

"totalCount": {total_number_of_registrations},
"pageInfo": {
    "startCursor": "cGFnXXsw",
    "endCursor": "cGRnXXsw",
    "hasNextPage": true
}

Due to structural limitations, it is crucial to note that the "totalCount" property represents the number of registrations rather than the number of data points.

The total number of registrations depends on the "registrationConfirmed" state. It always returns the total number of registrations matching your filters, regardless of the "first" parameter specified.

The behavior of pagination is described here.

Additionally, different parameters can be combined with the "first" and "after" parameters to refine the query further.

Empty response

If no items were found after applying filters, the response looks like this:

{
    "items": [],
    "totalCount": 0,
    "pageInfo": {
        "startCursor": null,
        "endCursor": null,
        "hasNextPage": false
    }
}