Position Green API: Data Points

Modified on Tue, 15 Apr at 10:20 AM

TABLE OF CONTENTS

Specifics
Properties of a data point object
- Meta data 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	string	PrettyId of the organization unit
OrgUnitLabel	string	The organization unit the data belongs to
OrgUnitTags	Array of strings	Tags that are specified on an organization unit
ReportingYearLabel	string	Reporting year a registration belongs to
ReportingYearId	Guid	Reporting year ID a registration belongs to
PeriodName	string	The name of the period registration belongs to
PeriodMoniker	string	The moniker suggests the time period a registration belongs to

PeriodStartDate	string	The start date of the period a registration belongs to
AspectName	string	The aspect it belongs to
AspectId	Guid	The ID of aspect it belongs to
MeasureName	string	The name of the measure
MeasureId	Guid	The ID of the measure
MeasureGlobalId	Guid?	The globalId of the measure
MeasurePrettyId	string	PrettyId of the measure

MeasureTags	Array of strings	A list of tags that belongs to the measure
MeasurePointId	Guid?	The ID of measure point
RegistrationResponsibleEmail	string	An email address of a reporter that is responsible for reporting the data
RegistrationResponsibleName	string	A full name of reporter that is responsible for reporting the data
RegistrationLastUpdateUtc	long?	A unixtimestamp that indicates when was data point last time updated
RegistrationConfirmed	bool	The confirmation status of the registration

Data point values properties

Property	Data Type	Description
MeasurePointTags	Array of strings	A list of tags. They can be set in Measure Builder and is recommended way of identifying a control
ControlType	string	Type of a control belongs to the data point
DataPointControlName	string	The name of the data point. Can be complex with separators !! if data points belongs to iterative control.
DataDisplayValue	string	Display name shown to the reporter
DataUnit	string	The unit of the values belongs to the data point
DataValueType	string	The type of the value. Used as discriminator
DataValue	string	The actual data of the data point
RowId	Guid	The id indicating what data points belongs 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	Id (GUID) of the year - as given from /years e.g. 0f80635f-1215-400b-924a-e365cc601d31
measureIds	string[]	List of measure Ids to limit the result to
measureGlobalIds	string[]	List of global measure ids to limit the result to
orgUnitIds	string[]	List of organization unit ids (GUIDs) to filter the results.
orgUnitGlobalIds	string[]	List of global organization unit ids (GUIDs) to filter the results.
includeChildren	bool	Indicates whether to include children of the provided organization units in the response. (Default = false)
startDate	string	Timestamp (ISO 8601) e.g. 2023-06-01T00:00:00+02:00
endDate	string	Timestamp (ISO 8601) e.g. 2023-08-31T23:59:59+02:0
lastModifiedStart	number	Unix timestamp
confirmationState	string	See confirmationState
sortDirection	string	See sorting, below
after	string	Cursor used to fetch next page
first	number	Number of registrations to limit the page to
lastModifiedEnd	number	Unix timestamp

200: OK Succes

See response example below

Example of a curl request

curl --location "<api url>/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": "2023",
                "ReportingYearId": "9cagdfg31a-efg6-4747-9bjrt-49dc4e34563448",
                "PeriodName": "January",
                "PeriodMoniker": "M1",
                "PeriodStartDate": "2023-01-31T00: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": "2023",
                "ReportingYearId": "9cagdfg31a-efg6-4747-9bjrt-49dc4e34563448",
                "PeriodName": "January",
                "PeriodMoniker": "M1",
                "PeriodStartDate": "2023-01-31T00: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 "periodEndDate" falls within the specified range. For example, if you filter on "startDate" as '2019-12-01', you will receive all registrations where the "periodEndDate" 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" 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 is an Enum and the default value is that only Confirmed registrations will be returned.

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

You can perform queries using either "measureIds" or "measureGlobalIds." It is possible to query using a single "measureId" or an array of multiple "measureIds." The same applies to "measureGlobalIds."

Sorting

Sorting by period is possible in ascending or descending order. 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 "int.MaxValue" (2,147,483,647), which retrieves all registrations. You can specify a specific number of registrations as well.

Note: Every request has the following end section:

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

Due to 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, regardless of the "first" parameter that specifies the number of registrations to retrieve.

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 then the response looks like this:

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