The MCE API comprises some 45 separate methods that control all aspects of configuring the underlying database, uploading raw data and downloading the calculated data. Includes methods to: Return and update the data structure; Add new RAW and CALC Items; Add costs and conversions; Add Targets and High and Low exception limits; Import RAW data.
1 Access Login details
Access information for the demonstration account or create your own account
1.1 Login details for a demonstration account
The following Methods are sufficient to load Raw Data and to retrieve Calculated Data from the Meniscus servers, to retrieve the overall data structure and to make some simple updates.
The GET links below work with the Meniscus REST demo server and when asked the login credentials are:
Username: [email protected]
Password: ipmsdemo
This username and password only has read access so cannot use POST methods and so all POST methods are shown in italics
1.2 Create you own MCE API account
We will e-mail you once the account is created – which should only take a few moments.
2 Group Methods – returns data structure
These methods return the overall data structure together with the properties for each Group and a list of the Properties is set out in section 6.0
2.1 Company - Returns the top level Group - Company
This returns the top level Group called Company that the user has access to
https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/Groups?groupName
<Group> <Alias></Alias> <Name>Demo</Name> </Group>
2.2 Sites - Returns the Sites for a Company
This returns the second Group level called Site from the Company called Demo
https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/Groups?groupName=Demo
<Group> <Alias>My Site</Alias> <Name>ipmsdemo-meniscus.co.uk</Name> </Group>
2.3 Groups – Returns a list of Groups for a Site
This returns a list of Groups under the specified Group name together with the properties for each Group.
This will return all the sub-groups for the Group Demo\ipmsdemo-meniscus.co.uk
<Group> <Alias></Alias> <Name>Electricity_Meters</Name> </Group> <Group> <Alias></Alias> <Name>Summary</Name> </Group>
2.4 SubGroups – Returns a list of SubGroups for a Group
This returns a list of SubGroups associated to a Group
This will return the SubGroups for the Group Demo\ipmsdemo-meniscus.co.uk\Electricity_Meters
<Group> <Alias></Alias> <Name>Daily</Name> </Group> <Group> <Alias></Alias> <Name>Half_Hour</Name> </Group>
2.5 Items - Returns the list of Items for a SubGroup
This returns a list of Items associated to a SubGroup
This will return all the Items that are associated to the SubGroup Demo\ipmsdemo-meniscus.co.uk\Electricity_Meters\Half_Hour
<Group> <Alias></Alias> <Name>Electricity_use_channel_1_HH</Name> </Group> <Group> <Alias></Alias> <Name>Electricity_use_channel_2_HH</Name> </Group> <Group> <Alias></Alias> <Name>Electricity_use_channel_3_HH</Name> </Group>
2.6 Update Site – Updating the properties of a Site – POST method
This method updates the properties of a Site. The example URL below shows how to update the property userKey1 for the Site Demo|ipms-meniscus.co.uk to “My Site”
https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/UpdateSite?companyName=Demo&name=ipmsdemo-meniscus.co.uk&userKey1=My Site
This is the Method’s structure:
[WebInvoke(Method = “POST”, UriTemplate = “UpdateSite?companyName={companyName}&name={name}&newName={newName}&startTime={startTime}&endTime={endTime}&address1={address1}&address2={address2}&town={town}&county={county}&country={country}&postcode={postcode}&phone={phone}&fax={fax}&userKey1={userKey1}&userKey2={userKey2}&userKey3={userKey3}¤cy={currency}&emailAddresses={emailAddressList}”)]
2.7 Update Site - Updating the Site Name - POST method
This method updates the name of a Site. The example URL below shows how to update the name from ipmsdemo-meniscus.co.uk to ipmsdemo2-meniscus.co.uk for the Site Demo|ipms-meniscus.co.uk
https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/UpdateSite?companyName=Demo&name=ipmsdemo-meniscus.co.uk&newName=ipmsdemo2-meniscus.co.uk
This is the Method’s structure:
[WebInvoke(Method = “POST”, UriTemplate = “UpdateSite?companyName={companyName}&name={name}&newName={newName}&startTime={startTime}&endTime={endTime}&address1={address1}&address2={address2}&town={town}&county={county}&country={country}&postcode={postcode}&phone={phone}&fax={fax}&userKey1={userKey1}&userKey2={userKey2}&userKey3={userKey3}¤cy={currency}&emailAddresses={emailAddressList}”)]
2.8 Update Group and SubGroup - Updating the Properties of a Group or SubGroup - POST method
This method updates the properties of a Site.
The example URL below shows how to update the property userKey1 for the Group Demo|ipms-meniscus.co.uk|Summary to “My Group”
https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/UpdateGroup?groupName=Demo\ipmsdemo-meniscus.co.uk&name=Summary&userKey1=My Group
The example URL below shows how to update the property userKey1 for the SubGroup Demo\ipms-meniscus.co.uk\Summary\Carbon Use to “My SubGroup”
https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/UpdateGroup?groupName=Demo\ipmsdemo-meniscus.co.uk\Summary&name=Carbon Use&userKey1=My SubGroup
This is the Method’s structure:
[WebInvoke(Method = “POST”, UriTemplate = “UpdateGroup?groupName={groupName}&newName={newName}&name={name}&userKey1={userKey1}”)]
2.9 Update Group and SubGroup - Updating the Name of a Group or SubGroup - POST method
This method changes the Name of a Group or SubGroup.
The example URL below changes the Name of the Group for the Group Demo|ipms-meniscus.co.uk|Summary to Summary2
https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/UpdateGroup?groupName=Demo\ipmsdemo-meniscus.co.uk&name=Summary&newName=Summary2
The example URL below changes the Name of the SubGroup for the SubGroup Demo\ipms-meniscus.co.uk\Summary\Carbon Use to Carbon Consumption
https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/UpdateGroup?groupName=Demo\ipmsdemo-meniscus.co.uk\Summary&name=Carbon Use&newName=Carbon Consumption
This is the Method’s structure:
[WebInvoke(Method = “POST”, UriTemplate = “UpdateGroup?groupName={groupName}&newName={newName}&name={name}&userKey1={userKey1}”)]
3 Item Methods – returns Item Properties
This returns a list of Items and the properties of each Item for the specified Group. A list of these properties is set out in section 6.1.
3.1 Returning Item Names only for a Site
This method returns just the Item Names for a Site
This returns the following (only showing part of the list
<Group> Alias></Alias> <Name>Average daily temperature</Name> </Group> <Group> <Alias></Alias> <Name>Daily_electricity_use_channel_1</Name> </Group> <Group> <Alias></Alias> <Name>Daily_electricity_use_channel_2</Name> </Group> <Group> <Alias></Alias> <Name>Daily_electricity_use_channel_3</Name> </Group> <Group> <Alias></Alias> <Name>Electricity Carbon</Name> </Group>
3.2 Returning Item Properties for Items in a Group
This method returns all the Item Properties for the Group Demo/ipmsdemo-meniscus.co.uk/Electricity_Meters
This will return the following list (only showing part of the list) of Items and their properties
<Item i:type="CalculatedItemInfo"> <Name> Demo|ipmsdemo-meniscus.co.uk|Daily_electricity_use_channel_1|CALC </Name> <AggregationFunction>Sum</AggregationFunction> <AggregationPeriod>Day</AggregationPeriod> <Alias></Alias> <CalcDelay>0.5</CalcDelay> <CalcEndOffset></CalcEndOffset> <CalcStartOffset>d-7</CalcStartOffset> <Cost>Electricity</Cost> <EndDate>2017-10-03T00:00:00</EndDate> <EntryUnits>None</EntryUnits> <Flags>0</Flags> <Id>20897</Id> <Notes></Notes> <Rounding>-1</Rounding> <StartDate>2017-10-01T00:00:00</StartDate> <StartValue>0</StartValue> <Type>Calculated</Type> <Units>kWh</Units> <UserKey1></UserKey1> <UserKey2></UserKey2> <UserKey3></UserKey3> <Calculation> sum(dataset(Electricity_use_channel_1_HH,today,today+1)) </Calculation> </Item> <Item i:type="StandardItemInfo"> <Name> Demo|ipmsdemo-meniscus.co.uk|Daily_electricity_use_channel_1|LCALC </Name> <Calculation></Calculation> </Item> <Item i:type="StandardItemInfo"> <Name> Demo|ipmsdemo-meniscus.co.uk|Daily_electricity_use_channel_1|HCALC </Name> <Calculation></Calculation> </Item>
3.3 Returning Item Properties for a SubGroup
span lang=”EN-US”>This method returns all the Item Properties for the Group Demoipmsdemo-meniscus.co.uk/Electricity_Meters/Half_Hour
This will return the following list (only showing part of the list) of Items and their properties
<Item i:type="CalculatedItemInfo"> <Name> Demo|ipmsdemo-meniscus.co.uk|Electricity_use_channel_1_HH|CALC </Name> <AggregationFunction>Sum</AggregationFunction> <AggregationPeriod>ThirtyMinutes</AggregationPeriod> <Alias>ipmsdemo_Channel_1</Alias> <CalcDelay>0.5</CalcDelay> <CalcEndOffset></CalcEndOffset> <CalcStartOffset></CalcStartOffset> <Cost>None</Cost> <EndDate>2017-10-03T00:00:00</EndDate> <EntryUnits>None</EntryUnits> <Flags>0</Flags> <Id>20892</Id> <Notes> For demo purposes, changed to calc meter and references back non hh meter </Notes> <Rounding>1</Rounding> <StartDate>2017-10-01T00:00:00</StartDate> <StartValue>0</StartValue> <Type>Absolute</Type> <Units>kWh</Units> <UserKey1></UserKey1> <UserKey2></UserKey2> <UserKey3></UserKey3> <Calculation></Calculation> </Item> <Item i:type="StandardItemInfo"> <Name> Demo|ipmsdemo-meniscus.co.uk|Electricity_use_channel_1_HH|LCALC </Name> <Calculation></Calculation> </Item> <Item i:type="StandardItemInfo"> <Name> Demo|ipmsdemo-meniscus.co.uk|Electricity_use_channel_1_HH|HCALC </Name> <Calculation>2.5</Calculation> </Item>
3.4 Create Item - POST method
This method is to be used when creating or updating Items. MCE will ensure that all the associated Item Types are created in correct order.
The available Item Types that that can be created for any Item are: CALC, LCALC, HCALC and TARGET. The COST and TARGETCOST Item Types are automatically created once the CALC and the TARGET Item Types are created and a Cost is assigned to the Item. The RAW Item Type is implicit and is always created for each Item.
A CALC Item has to be created before a LCALC, HCALC or TARGET Item Type can be created.
The example code will create a new Calculated Item called TestMeter with the following URL:
https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/CreateItem?dataItemName=Demo|ipmsdemo-meniscus.co.uk|TestMeter|CALC&aggregationPeriod=Day&aggregationFunction=Sum&units=None&cost=None&type=Absolute
The parameters for each Item are set out in Section 9.2. Those parameters labelled with * have to added when creating a new Item.
To create a different Item type then replace the element labelled TestMeter|CALC with TestMeter |HCALCfor example. This would create a HCALC Item.
To create a TARGET Item Type the targetStartTime (labelled with ** in Appendix 6.0) has to be included as well. This parameter sets the date when the calculation of the TARGET will start. Multiple TARGET Item Types can be set for the same CALC Item. I.e. Can set multiple targets for an Item by specifying a new target StartTime.
This is the Method’s structure:
WebInvoke(Method = “POST”, UriTemplate = “CreateItem?dataItemName={dataItemName}&aggregationPeriod={aggregationPeriod}&aggregationFunction={aggregationFunction}&units={units}&entryUnits={entryUnits}&cost={cost}&calcStartOffset={calcStartOffset}&calcEndOffset={calcEndOffset}&” +
“calculation={calculation}&startValue={startValue}&startTime={startTime}&endTime={endTime}&calcDelay={calcDelay}&type={type}&alias={alias}&userKey1={userKey1}&userKey2={userKey2}&userKey3={userKey3}¬es={notes}&rounding={rounding}&flags={flags}”)]
3.5 Update an existing Item - POST method
This is the Method used to update an existing Item
When using the UpdateItem method only the Item property to be updated has to be included in the URL. The following call will set a value of “This is a test meter” in userkey1 for Item Pump1
The URL to be passed to the code to Update the Pump1 Item is:
<https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/UpdateItem?dataItemName=Demo|ipmsdemo-meniscus.co.uk|TestMeter|CALC&userkey1=This is a test meter
This is the Method’s structure:
[WebInvoke(Method = “POST”, UriTemplate = “UpdateItem?dataItemName={dataItemName}&newName={newName}&aggregationPeriod={aggregationPeriod}&aggregationFunction={aggregationFunction}&units={units}&entryUnits={entryUnits}&cost={cost}&calcStartOffset={calcStartOffset}&calcEndOffset={calcEndOffset}&” +
“calculation={calculation}&startValue={startValue}&startTime={startTime}&newStartTime={newStartTime}&endTime={endTime}&calcDelay={calcDelay}&type={type}&alias={alias}&userKey1={userKey1}&userKey2={userKey2}&userKey3={userKey3}¬es={notes}&rounding={rounding}&flags={flags}”)]
3.6 Delete Item – POST method
This method deletes the Item and all associated raw and calculated data related to this Item. This is permanent so be careful. The URL to be passed to the code to Delete the Pump1 Item is:
https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/DeleteItem?dataItemName=Demo|ipmsdemo-meniscus.co.uk|TestMeter|CALC
Deleting the CALC Item Type deletes all CALC, HCALC, LCALC and TARGET data.
Deleting the HCALC or LCALC Item Type deletes the calculation for that Item
Deleting the TARGET requires that a targetStartTime is also included. This deletes the Target equation set at the targetStartTime.
This is the Method’s structure:
[WebInvoke(Method = “POST”, UriTemplate = “DeleteItem?dataItemName={dataItemName}&targetStartTime={targetStartTime}”)]
3.7 Checking the syntax of a calculation
This method is used to confirm the calculation syntax and is relevant to the following ItemTypes: CALC, HCALC, LCALC, COST and TARGET
The method will return information to help identify errors in the syntax or will return OK if the syntax is valid.
Important Please note that in accordance with RFC 3986 the “+” sign is a reserved character and must be encoded as %2B
4 Unit Methods – Create, Update and Delete a Unit
This method creates a new Unit is if the Unit is not already present. It also allows a user to update and delete an existing Unit. It does not allow a user to edit or delete a ‘Global’ Unit.
4.1 Unit Method for listing available Units
This method returns a list of all available Units for this Site. Note that many of the common Units are already set up in a Global Site and cannot be updated or deleted. The property Updatable indicates if the Unit is a member of the Global site and hence cannot be changed.
The method for returning a list of Units is
https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/Units?companyName=Demo&siteName=ipmsdemo-meniscus.co.uk
This will return the following list (only showing part of the list)
<UnitInfo> <Name>None</Name> <UnitConversion> <UnitConversionInfo> <Alias i:nil="true"></Alias> <ConversionFactor>1</ConversionFactor> <Name>None</Name> <Updatable>false</Updatable> </UnitConversionInfo> </UnitConversion> <Updatable>false</Updatable> </UnitInfo> <UnitInfo> <Name>°C</Name> <UnitConversion> <UnitConversionInfo> <Alias>Me</Alias> <ConversionFactor>2.8</ConversionFactor> <Name>Test</Name> <Updatable>false</Updatable> </UnitConversionInfo> </UnitConversion> <Updatable>false</Updatable> </UnitInfo>
4.2 Unit Method for creating a unit - POST method
This method is to be used when creating a new Unit for a Site. An example of a Unit would be kWh
Note that a range of common Units are already available and set up in a Global Site. These Units cannot be updated or deleted
This Method is the same as for the Method for adding a Conversion but the conversion properties can be excluded
This is the URL to create a Unit
https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/CreateUnit?companyName=Demo&siteName=ipmsdemo-meniscus.co.uk&name=mW
This is the Method’s structure:
[WebInvoke(Method = “POST”, UriTemplate = “CreateUnit?companyName={companyName}&siteName={siteName}&name={name}&conversionName={conversionName}&conversionFactor={conversionFactor}&alias={alias}”)]
4.3 Unit Method for updating a Unit - POST method
This method is to be used when updating a Unit for a Site. This is the same Method as used for updating Conversions but excludes some properties
Note that a range of common Units are already available and set up in a Global Site. These Units cannot be updated or deleted
The names of existing Units can be found by listing all Units using the call in 4.1 where the output would look like
<UnitInfo> <Name>None</Name> <UnitConversion> <UnitConversionInfo> <Alias i:nil="true"></Alias> <ConversionFactor>1</ConversionFactor> <Name>None</Name> <Updatable>false</Updatable> </UnitConversionInfo> </UnitConversion> <Updatable>false</Updatable> </UnitInfo>
This is the URL to update a Unit with a name =mW with a newName =MW
http://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/UpdateUnit?companyName=Demo&siteName=ipmsdemo-meniscus.co.uk&name=mW&newName=MW
This is the Method’s structure:
[WebInvoke(Method = “POST”, UriTemplate = “UpdateUnit?companyName={companyName}&siteName={siteName}&name={name}&newName={newName}&conversionName={conversionName}&newConversionName={newConversionName}&conversionFactor={conversionFactor}&alias={alias}”)]
4.4 Unit Method for deleting a unit - POST method
This is the method for deleting a Unit
This Method is the same as the Conversion Method bu all Conversion Properties can be excluded
https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/DeleteUnit?companyName=Demo&siteName=ipmsdemo-meniscus.co.uk&name=MW
This is the Method’s structure:
[WebInvoke(Method = “POST”, UriTemplate = “DeleteUnit?companyName={companyName}&siteName={siteName}&name={name}&conversionName={conversionName}”)]
5 Cost Methods – Create, Update and Delete a Cost
This method creates a new Cost is if the Cost is not already present. It also allows a user to update and delete an existing Cost. It does not allow a user to edit or delete a ‘Global’ Cost.
5.1 Cost Method for returning all Costs
This is the method for returning all Costs
This will return XML that looks like (this is only part of the list)
<CostInfo> <CostData> <CostDataInfo> <CostCalculation i:nil="true"></CostCalculation> <Date>2013-09-04T00:00:00</Date> <ValueFrom i:nil="true"></ValueFrom> </CostDataInfo> </CostData> <Name>Electricity</Name> <UnitName>£</UnitName> <Updatable>true</Updatable> </CostInfo>
5.2 Cost Method for creating a Cost - POST method
This is the Method for adding a Cost
This Method is the same as for adding costData but the costData properties can be excluded
This will create a Cost called MWh Cost
https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/CreateCost?companyName=Demo&siteName=ipmsdemo-meniscus.co.uk&name=MWh Cost&units=kWh
This is the Method’s structure:
[WebInvoke(Method = “POST”, UriTemplate = “CreateCost?companyName={companyName}&siteName={siteName}&name={name}&units={units}&costTime={costTime}&calculation={calculation}”)]
5.3 Cost Method for updating a Cost - POST method
This is the Method for updating a Cost
This URL will update the Cost with name= MWh Cost and rename it as newName=MWh Power Cost
https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/UpdateCost?companyName=Demo&siteName=ipmsdemo-meniscus.co.uk&name=MWh Cost&newName=MWh Power Cost&units=kWh
The costName can be found from calling the Method in 5.1 which will return the following for this Cost
<CostInfo> <CostData> <CostDataInfo> <CostCalculation i:nil="true"></CostCalculation> <Date>2015-12-15T00:00:00</Date> <ValueFrom i:nil="true"></ValueFrom> </CostDataInfo> </CostData> <Name>MWh Cost</Name> <UnitName>MWh</UnitName> <Updatable>true</Updatable> </CostInfo>
A list of the Item Properties used to create a Cost are set out in Section 9.0
This is the Method’s structure:
[WebInvoke(Method = “POST”, UriTemplate = “UpdateCost?companyName={companyName}&siteName={siteName}&name={name}&newName={newName}&units={units}&costTime={costTime}&newCostTime={newCostTime}&calculation={calculation}”)]
5.4 Cost Method to delete a Cost - POST method
This is the Method to delete a Cost
This will delete the Cost called MW Power Cost
https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/DeleteCost?companyName=Demo&siteName=ipmsdemo-meniscus.co.uk&name=MWh Power Cost
This is the Method’s structure:
WebInvoke(Method = “POST”, UriTemplate = “DeleteCost?companyName={companyName}&siteName={siteName}&name={name}&costTime={costTime}”)]
5.5 Cost Method to list all costData for a Cost
This is the Method to list all costData for a Method
This is the same Method as that for listing all Costs
The XML returned will look like (this is only part of the list)
<CostInfo> <CostData> <CostDataInfo> <CostCalculation i:nil="true"></CostCalculation> <Date>2013-09-04T00:00:00</Date> <ValueFrom i:nil="true"></ValueFrom> </CostDataInfo> </CostData> <Name>Electricity</Name> <UnitName>£</UnitName> <Updatable>true</Updatable> </CostInfo>
5.6 Cost Method to add new costData to a Cost - POST method
This is the Method to add costData (can think of costData as a unit cost) to a Cost.
This URL will add costData to the Cost called MWh Power Cost which has units of MWh and the costData will be applied from 05/12/2015 and will have a value of 20
https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/UpdateCost?companyName=Demo&siteName=ipmsdemo-meniscus.co.uk&name=MWh Power Cost&units=MWh&costTime=05/12/2015&calculation=20
This is the Method’s structure:
[WebInvoke(Method = “POST”, UriTemplate = “CreateCost?companyName={companyName}&siteName={siteName}&name={name}&units={units}&costTime={costTime}&calculation={calculation}”)]
5.7 Cost Method to update costData for a Cost - POST method
This is the Method for updating costData
This URL will update the existing costData for the unit called MWh Power Cost that has units of MWh and an existing costData entry on 05/12/2015. This will change the calculation from 20 to 30
https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/UpdateCost?companyName=Demo&siteName=ipmsdemo-meniscus.co.uk&name=MWh Power Cost&units=MWh&costTime=05/12/2015&calculation=30
This is the Method’s structure:
[WebInvoke(Method = “POST”, UriTemplate = “UpdateCost?companyName={companyName}&siteName={siteName}&name={name}&newName={newName}&units={units}&costTime={costTime}&newCostTime={newCostTime}&calculation={calculation}”)]
5.8 Cost Method to delete costData for a Cost - POST method
This Method will delete costData for a Cost
This URL will delete the costData for Cost MWh Power Cost that is set on 05/12/2015
https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/DeleteCost?companyName=Demo&siteName=ipmsdemo-meniscus.co.uk&name=MWh Power Cost&costTime=05/12/2015
This is the Method’s structure:
[WebInvoke(Method = “POST”, UriTemplate = “DeleteCost?companyName={companyName}&siteName={siteName}&name={name}&costTime={costTime}”)]
6 Conversion Methods – Create, Update and Delete a Conversion
This method creates a new Conversion is if the Conversion is not already present. It also allows a user to update and delete an existing Conversion. It does not allow a user to edit or delete a ‘Global’ Conversion.
6.1 Conversion Method to list all Conversions
This Method will return a list of all Conversions.This Method is the same as that for listing Units
This will return XML that looks like (this is only part of the list)
<UnitInfo> <Name>None</Name> <UnitConversion> <UnitConversionInfo> <Alias i:nil="true"></Alias> <ConversionFactor>1</ConversionFactor> <Name>None</Name> <Updatable>false</Updatable> </UnitConversionInfo> </UnitConversion> <Updatable>false</Updatable> </UnitInfo> <UnitInfo> <Name>°C</Name> <UnitConversion> <UnitConversionInfo> <Alias>Me</Alias> <ConversionFactor>2.8</ConversionFactor> <Name>Test</Name> <Updatable>false</Updatable> </UnitConversionInfo> </UnitConversion> <Updatable>false</Updatable> </UnitInfo>
6.2 Conversion Method for creating a Conversion - POST method
This is the Method for adding a Conversion. This is the same Method as that for updating Units
This Method is the same as that for adding a Units
This URL will add a Conversion to the unit MWh. This Conversion is called MW to MWh, It has a conversion factor or 0.25. This would be applied to convert MW data arriving every 15 minutes into MWh data. The alias is set to MW and this is the raw units.
https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/CreateUnit?companyName=Demo&siteName=ipmsdemo-meniscus.co.uk&name=GWh&conversionName=GW to GWh&conversionFactor=0.25&alias=Gw
This is the Method’s structure:
[WebInvoke(Method = “POST”, UriTemplate = “CreateUnit?companyName={companyName}&siteName={siteName}&name={name}&conversionName={conversionName}&conversionFactor={conversionFactor}&alias={alias}”)]
6.3 Conversion Method for updating a Conversion - POST method
This is the Method for updating a Conversion. This is the same Method for updating a Unit
This URL will update the Conversion named MW to MWh which is assigned to units of MWh and assign it a value of 0.25. This update changes the alias from Mw to MW
https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/UpdateUnit?companyName=Demo&siteName=ipmsdemo-meniscus.co.uk&name=GWh&conversionName=GW to GWH&newConversionName=GW to GWH&conversionFactor=0.25&alias=GW
This is the Method’s structure:
[WebInvoke(Method = “POST”, UriTemplate = “UpdateUnit?companyName={companyName}&siteName={siteName}&name={name}&newName={newName}&conversionName={conversionName}&newConversionName={newConversionName}&conversionFactor={conversionFactor}&alias={alias}”)]
6.4 Conversion Method for deleting a Conversion - POST method
This is the Method for deleting a Conversion.
This will delete the Conversion named MW to MWh
https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/DeleteUnit?companyName=Demo&siteName=ipmsdemo-meniscus.co.uk&name=GWh&conversionName=GW to GWh
This is the Method’s structure:
[WebInvoke(Method = “POST”, UriTemplate = “DeleteUnit?companyName={companyName}&siteName={siteName}&name={name}&conversionName={conversionName}”)]
7 Target Methods – Create, Update and Delete a Target
This method creates a new Target is if the Target is not already present. If the Target is present then the method will create a new targetTime entry into the relevant Target.
7.1 Target Method for adding a target to an item - POST method
This is the Method for creating a Target. This Method is that same as the Item create Method
This URL will create a Target in the Item Total electricity that has a value of 12 and will apply from 01/10/2017
https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/CreateItem?dataItemName=Demo|ipmsdemo-meniscus.co.uk|Total electricity|TARGET&startTime=01/10/2017&calculation=12&Notes=This is a test target
This is the Method’s structure:
WebInvoke(Method = “POST”, UriTemplate = “CreateItem?dataItemName={dataItemName}&aggregationPeriod={aggregationPeriod}&aggregationFunction={aggregationFunction}&units={units}&entryUnits={entryUnits}&cost={cost}&calcStartOffset={calcStartOffset}&calcEndOffset={calcEndOffset}&” +
“calculation={calculation}&startValue={startValue}&startTime={startTime}&endTime={endTime}&calcDelay={calcDelay}&type={type}&alias={alias}&userKey1={userKey1}&userKey2={userKey2}&userKey3={userKey3}¬es={notes}&rounding={rounding}&flags={flags}”)]
7.2 Target Method for updating a Target - POST Method
This is the Method for updating a Target. This is the same as the update Item Method but some properties can be excluded
This URL changes the startTime for the Target in Item Total electricity from 01/10/2017 to a newStartTime of 15/10/2017
https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/UpdateItem?dataItemName=Demo|ipmsdemo-meniscus.co.uk|Total electricity|TARGET&startTime=01/10/2017&newStartTime=15/10/2017&calculation=12&Notes=This is a test target
This is the Method’s structure:
[WebInvoke(Method = “POST”, UriTemplate = “UpdateItem?dataItemName={dataItemName}&newName={newName}&aggregationPeriod={aggregationPeriod}&aggregationFunction={aggregationFunction}&units={units}&entryUnits={entryUnits}&cost={cost}&calcStartOffset={calcStartOffset}&calcEndOffset={calcEndOffset}&” +
“calculation={calculation}&startValue={startValue}&startTime={startTime}&newStartTime={newStartTime}&endTime={endTime}&calcDelay={calcDelay}&type={type}&alias={alias}&userKey1={userKey1}&userKey2={userKey2}&userKey3={userKey3}¬es={notes}&rounding={rounding}&flags={flags}”)]
7.3 Target Method for updating the calculation or notes for a Target - POST Method
This is the Method for updating the calculation or notes for a TARGET. This is the same as the update Item Method but some properties can be excluded
This URL changes the calculation for the TARGET in Item Total electricity from a value of 12 to a value of 15
https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/UpdateItem?dataItemName=Demo|ipmsdemo-meniscus.co.uk|Total electricity|TARGET&startTime=01/10/2017&calculation=15&Notes=This is a test target
Please note that the calculation for a TARGET can be a complex calculation
This is the Method’s structure:
[WebInvoke(Method = “POST”, UriTemplate = “UpdateItem?dataItemName={dataItemName}&newName={newName}&aggregationPeriod={aggregationPeriod}&aggregationFunction={aggregationFunction}&units={units}&entryUnits={entryUnits}&cost={cost}&calcStartOffset={calcStartOffset}&calcEndOffset={calcEndOffset}&” +
“calculation={calculation}&startValue={startValue}&startTime={startTime}&newStartTime={newStartTime}&endTime={endTime}&calcDelay={calcDelay}&type={type}&alias={alias}&userKey1={userKey1}&userKey2={userKey2}&userKey3={userKey3}¬es={notes}&rounding={rounding}&flags={flags}”)]
7.4 Target Method for deleting a target from an item - POST method
This is the Method for deleting a Target. This is the same Method as for deleting an Item
This URL deletes the Target for the Item Total electricity set on 15/10/2017
https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/DeleteItem?dataItemName=Demo|ipmsdemo-meniscus.co.uk|Total electricity|TARGET&startTime=15/10/2017
This is the Method’s structure:
[WebInvoke(Method = “POST”, UriTemplate = “DeleteItem?dataItemName={dataItemName}&targetStartTime={targetStartTime}”)]
8 Data Methods – Uploading and downloading data
Methods are provided to set raw data and get data back from the Meniscus servers. The POST and GET Methods for Raw and Calculated Data will use JSON serialised responses
8.1 GET Data for a single Item
The full method for retrieving Data for a single Item (Electricity use – channel 1 – HH) within the date range 01/10/2017 to 03/10/2017.
This call returns the following serialised JSON data:
[{“DataItemName”:”Demo|ipmsdemo-meniscus.co.uk|Electricity_use_channel_1_HH|CALC”,”Unit”:”kWh”,”Cost”:”None”,”DecimalPlaces”:1,”Data”:[{“Time”:636424128000000000,”Value”:0.326,”Flags”:0},{“Time”:636424146000000000,”Value”:0.464,”Flags”:0},{“Time”:636424164000000000,”Value”:0.13,”Flags”:0},{“Time”:636424182000000000,”Value”:0.514,”Flags”:0},{“Time”:636424200000000000,”Value”:0.066,”Flags”:0},{“Time”:636424218000000000,”Value”:0.073,”Flags”:0},{“Time”:636424236000000000,”Value”:0.071,”Flags”:0},{“Time”:636424254000000000,”Value”:0.077,”Flags”:0},{“Time”:636424272000000000,”Value”:0.063,”Flags”:0},{“Time”:636424290000000000,”Value”:0.074,”Flags”:0},{“Time”:636424308000000000,”Value”:0.08,”Flags”:0},{“Time”:636424326000000000,”Value”:0.133,”Flags”:0},{“Time”:636424344000000000,”Value”:0.131,”Flags”:0},{“Time”:636424362000000000,”Value”:0.314,”Flags”:0},{“Time”:636424380000000000,”Value”:0.302,”Flags”:0},{“Time”:636424398000000000,”Value”:0.433,”Flags”:0},{“Time”:636424416000000000,”Value”:0.427,”Flags”:0},{“Time”:636424434000000000,”Value”:0.213,”Flags”:0},{“Time”:636424452000000000,”Value”:0.208,”Flags”:0},{“Time”:636424470000000000,”Value”:0.166,”Flags”:0},{“Time”:636424488000000000,”Value”:0.13,”Flags”:0},{“Time”:636424506000000000,”Value”:0.158,”Flags”:0},{“Time”:636424524000000000,”Value”:0.136,”Flags”:0},{“Time”:636424542000000000,”Value”:0.162,”Flags”:0},{“Time”:636424560000000000,”Value”:0.145,”Flags”:0},{“Time”:636424578000000000,”Value”:0.197,”Flags”:0},{“Time”:636424596000000000,”Value”:0.167,”Flags”:0},{“Time”:636424614000000000,”Value”:0.164,”Flags”:0},{“Time”:636424632000000000,”Value”:0.18,”Flags”:0},{“Time”:636424650000000000,”Value”:0.23,”Flags”:0},{“Time”:636424668000000000,”Value”:0.197,”Flags”:0},{“Time”:636424686000000000,”Value”:0.247,”Flags
8.2 GET Data for multiple Items
To retrieve data for Multiple Items(Electricity_use_channel_1_HH and Electricity_use_channel_2_HH within the date range 01/10/2017 to 03/10/2017 you need to create a dataItemList separated by commas
The dataItemList must include the full name for the Item i.e. including the Company|Site
8.3 GET Data for other Item Types
Using the CALC in the full Item name will retrieve the calculated data. By replacing the Item Type you will return the data for these Item Types. I.e.
RAW Item Type
HCALC Item Type
8.4 GET Data for Items using wildcards and filters
It is possible to use wildcards in the dataItemList to extract data and then apply the filters
So the following call will return CALC data for all Items between 01/10/2017 and 02/10/2017
To filter the data we can apply a wildcard filter into the dataItemName and then use one, or more, of the following filters. An example of a wildcard is Demo|ipmsdemo-meniscus.co.uk|.*|CALC this will return CALC data for all Items.
Examples of filters that can be added are:
- unitList – filters on specified unit or list or units
- processList – filters on specified Group or list or Groups
- areaList – filters on specified SubGroup or list or SubGroups
- costList – filters on specified cost or list or costs
- userKey1List – filters on specified userKey1 field or list of userKey1 fields
- userKey2List – filters on specified userKey2 field or list of userKey2 fields
- userKey3List – filters on specified userKey3 field or list of userKey3 fields
so the following call will return CALC data for all Items between 01/10/2017 and 02/10/2017 where the Cost = Electricity (the wildcard dataItemName is Demo|ipmsdemo-meniscus.co.uk|.*|CALC )
To create a list for the filters then separate the values with a comma
This will return all Items in the SubGroups Half_Hour and Daily
8.5 Data - Setting Raw Data by Item - POST method
This method is used to POST raw data into an Item
The example code below shows how to update raw data for the item Demo|ipmsdemo-meniscus.co.uk|TestMeter|RAW for 4 values starting on the 01/07/2016 00:00 to 01/07/2016 01:30
https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/RawData/Demo|ipmsdemo-meniscus.co.uk|TestMeter|RAW
The BODY text for this method is:
[{“Time”:636029280000000000,”Value”:10},
{“Time”:636029298000000000,”Value”:20},
{“Time”:636029316000000000,”Value”:30},
{“Time”:636029334000000000,”Value”:40}]
Please note that this must use JSON and the time is in Ticks
Please note that the item name must be a RAW item otherwise the call will fail.
8.6 Data - Removing RAW data
This method uses a POST to delete raw data in an Item
The example code below shows how to delete raw data for the item Demo|ipmsdemo-meniscus.co.uk|TestMeter|RAW for 4 values starting on the 01/07/2016 00:00 to 01/07/2016 01:30
https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/RemoveRawData?dataItemName=Demo|ipmsdemo-meniscus.co.uk|TestMeter|RAW&startTime=01/08/2016 00:00:00&endTime=01/08/2016 00:00:00
The BODY text blank
Please note that the item name must be a RAW item otherwise the call will fail.
8.7 Data - Setting Raw data for multiple Items JSON - POST Method
This method is used to POST raw data into multiple Items using the Item property alias
The example code below shows how to update RAW data for the Site Demo|ipmsdemo-meniscus.co.uk for 2 values for 2 different Items starting on the 01/07/2016
https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/RawDataMA/Demo/ipmsdemo-meniscus.co.uk
The data has to be passed in deserialised JSON as BODY text is:
[{“ItemAlias”:”Temperature”,”Time”:636029280000000000,”Value”:10},
{“ItemAlias”:”Temperature”,”Time”:636029298000000000,”Value”:20},
{“ItemAlias”:”Electricity use – channel 1″,”Time”:636029280000000000,”Value”:6},
{“ItemAlias”:”Electricity use – channel 1″,”Time”:636029298000000000,”Value”:5}]
This will load data for the Items that have an alias of ElecUse_channel1 and ElecUse_channel3 into the RAW ItemType
8.8 Data - Setting Raw data for multiple Items CSV - POST Method
This method is used to POST raw data into multiple Items using the Item property alias
The example code below shows how to update RAW data for the Site Demo|ipmsdemo-meniscus.co.uk for 2 values in 2 different Items starting on the 01/07/2016
https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/RawDataFile/Demo/ipmsdemo-meniscus.co.uk
The data has to be passed in CSV as BODY text is:
ElecUse_channel3;01/07/2016 01:30;0.030156863
ElecUse_channel3;01/07/2016 02:00;0.032288889
ElecUse_channel1;01/07/2016 02:30;0.028306122
ElecUse_channel1;01/07/2016 03:00;0.028575472
This will load data for the Items that have an alias of ElecUse_channel1 and ElecUse_channel3 into the RAW ItemType
9 List of Properties
List of Group, Item, Unit, Cost and Target Properties
9.1 Company Properties
9.1 Company Properties
| Property | Item Type | Options | Information |
| address1 | Not Applicable | Optional | Any text |
| address2 | Not Applicable> | Optional | Any text |
| country | Not Applicable | Optional | Any text |
| name | Not Applicable | Compulsory | Any text |
| phone | Not Applicable | Optional | Any text |
| postcode | Not Applicable | Optional | Any text |
| town | Not Applicable | Optional | Any text |
| userKey1 | Not Applicable | Optional | Any text |
| userKey2y | Not Applicable | Optional | Any text |
| userKey3 | Not Applicable | Optional | Any text |
9.2 Site Properties
9.2. Site Properties
| Property | Item Type | Options | Information |
| address1 | Not Applicable | Optional | Any text |
| address2 | Not Applicable> | Optional | Any text |
| country | Not Applicable | Optional | Any text |
| county | Not Applicable | Optional | Any text |
| name | Not Applicable | Compulsory | Any text |
| phone | Not Applicable | Optional | Any text |
| postcode | Not Applicable | Optional | Any text |
| town | Not Applicable | Optional | Any text |
| userKey1 | Not Applicable | Optional | Any text |
| userKey2y | Not Applicable | Optional | Any text |
| userKey3 | Not Applicable | Optional | Any text |
| currency | Not Applicable | Optional | Currency to be used for the Site. Any text |
| emailAddressInfos | Not Applicable | Optional | List of e-mail address that will receive e-mail alerts for this Site |
| endDate | Not Applicable | Optional | Date in string format. Sets the date when the Site stops receiving data |
| startDate | Not Applicable | Compulsory | Date ins string format. Sets the date when the Site starts receiving data |
9.3 Group and SubGroup Properties
9.3. Group and SubGroup Properties
| Property | Item Type | Options | Information |
| groupName | Not Applicable | Compulsory | Name of the Group or SubGroup |
| newName | Not Applicable | Optional | Used to define the new Name for a Group or a SubGroup |
| userKey1 | Not Applicable | Any text | Any text |
9.4 Item Properties
9.4. Item Properties
| Property | Item Type | Options | Information |
| alias | CALC | Any text | This is the reference that is to be used when importing data. The Import will look for an Item having the same alias as is included in the data upload |
| aggregationFunction | CALC | Sum and Average | Sets the method of aggregation if the aggregation period of the data used in the calculation is different to the output aggregation period |
| aggregationPeriod | CALC | Hour, Day, FiveMinutes, TenMinutes, FifteenMinutes, ThirtyMinutes,None | Sets the period between the Calculated Data points |
| calculation | CALC, HCALC, LCALC and TARGET | Reference to be made to section 10.1 Calculation Syntax and Functions | A calculation to be used in the Item. This calculation defines the expression used in the relevant Item. |
| calcStartOffset | CALC | y=Year,M=Month, d=Day, h=Hour, m=Minute.
So M-1 will calculate data back 1 month Leaving blank will calculate all data |
How far back in time do the calculations go then processing new data |
| calcDelay | CALC | Multiplier of the aggregation Period
So value of 1/2 will calculate the data every 1/2 of the aggregation Period Leaving blank, or 0, will calculate data as soon as it is imported |
How often is the raw data processed in terms of aggregation periods. Value of 0 means data is processed as soon as it arrives
ie If the aggregation period is 30 minutes and calcDelay is 0.5, data is calculated 15 minutes after it has been imported |
| cost | CALC | Set to None if no cost is assigned | Cost to be used |
| item | CALC, HCALC, LCALC and TARGET | Type of Item. Can be: CALC, HCALC, LCALC. Order of creation is CALC, HCALC, LCALC, TARGET (requires setting of TargetStart). RAW is created implicitly. COST and TARGETCOST created implicitly once a Cost is assigned | |
| endTime | CALC | Optional | Date in string format. Date the Item stops being used |
| flags | CALC | Optional | This is an information field and cannot be updated.
Identifies if the data has been interpolated. I.e. if is based on actual RAW data on an assumptions from previous RAW data values – for data gaps etc. |
| newStartTime | Not Applicable | Optional | Date in String format. The date from which an existing Item start time is to be changed to |
| notes | CALC | Optional | Text field for including any relevant information |
| rounding | CALC | Optional. Defaults to 1. Values accepted from 0 to 5 | Sets the rounding that the Calculated Data will be returned in |
| startTime | CALC | Defaults to date Item created | Date in string format. Date the Item starts being used |
| startValue | CALC | Only used for type=Incrementing | Used to define the initial start value for an Item of type = Incrementing |
| type | CALC | Compulsory. Absolute; Incrementing; Consumption; Level; Calculated | Used to define the Type of Raw Data i.e Incrementing – this data where the value continually counts upwards – i.e. electricity meter. Other Types include: Absolute, Level, Consumption and Calculated. |
| units | CALC | Compulsory. Set to None if no units are to be defined | Used to define the output units of the Calculated Data |
| userkey1 | CALC | Optional | Any text |
| userkey2 | CALC | Optional | Any text |
| userkey3 | CALC | Optional | Any text |
9.5 Unit Properties
9.5. Unit Properties
| Property | Item Type | Options | Information |
| alias | Not Applicable | Optional | the Units which are applicable for this Unit |
| companyName | Not Applicable | Compulsory | Company in which the Unit and any Conversion are to be made available |
| conversionName | Not Applicable | Compulsory | A named description for the conversion |
| conversionFactor | Not Applicable | Optional | The conversion factor to change the Unit from the Unit described in the alias into this Unit |
| newConversionName | Not Applicable | Optional | Date in String format. The date from which an existing target will be changed to |
| siteName | Not Applicable | Compulsory | Site in which the Unit and any Conversion are to be made available |
| updatable | Not Applicable | Optional | This is an information field and cannot be updated. True means that the user has the rights to update this Unit and Conversion False means that the user does not have rights to update this Unit and Conversion |
9.6 Cost Properties
9.6. Cost Properties
| Property | Item Type | Options | Information |
| costTime | Not Applicable | Compulsory | Date in String format. The date from which the Cost is to be applied |
| calculation | Not Applicable | Compulsory | A calculation to be used in the Cost. This calculation defines the expression used in the relevant Cost. Can be a complex expression or a simple integer |
| newCostTime | Not Applicable | Optional | Date in String format. The date from which an existing Cost date is to be changed to |
| units | Not Applicable | Compulsory | Name of the Units which the Costs is to be applied to. I.e. An electricity cost would be associated to units of kWh |
| updatable | Not Applicable | True of False | This is an information field and cannot be updated.
True means that the user has the rights to update this Cost False means that the user does not have rights to update this Cost |
9.7 Target Properties
9.7. Target Properties
| Property | Item Type | Options | Information |
| startTime | Not Applicable | Compulsory | Date in String format. The date from which the TARGET is to be applied |
| calculation | Not Applicable | Compulsory | A calculation to be used in the TARGET. This calculation defines the expression used in the relevant TARGET. Can be a complex expression or a simple integer |
| newStartTime | Not Applicable | Optional | Date in String format. The date from which an existing target will be changed to |
| notes | Not Applicable | Optional | Any text |
10 Calculation syntax and functions
List of the standard set of calculation functions, syntax and examples
10.1 Calculation formats and syntax
The URL to be used to return a list of the available functions, syntax, examples and a description that are available in MCE is:
https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/Formulae
This is the standard list of calculation functions that are available but the complete set is much larger and more verbose. This syntax set will enable users to carry out most calculations but for complex calculations then please contact Meniscus for assistance of go to the Meniscus Wiki – you need to be an existing customer for access to this area.