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

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

Please fill in the following fields to create a new RESTful API account. This creates an example site that includes a number of Items, conversions and calculations so that you can import your own raw data and then test out the API methods detailed on this page.

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

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>

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>

This returns a list of Groups under the specified Group name together with the properties for each Group.

https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/Groups?groupName=Demo\ipmsdemo-meniscus.co.uk

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>

This returns a list of SubGroups associated to a Group

https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/Groups?groupName=Demo\ipmsdemo-meniscus.co.uk\Electricity_Meters

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>

This returns a list of Items associated to a SubGroup

https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/Groups?groupName=Demo\ipmsdemo-meniscus.co.uk\Electricity_Meters\Half_Hour

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>

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}”)]

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}”)]

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}”)]

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.

This method returns just the Item Names for a Site

https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/ItemGroups?groupName=Demo\ipmsdemo-meniscus.co.uk

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>

This method returns all the Item Properties for the Group Demo/ipmsdemo-meniscus.co.uk/Electricity_Meters

https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/Items?groupName=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>

span lang=”EN-US”>This method returns all the Item Properties for the Group Demoipmsdemo-meniscus.co.uk/Electricity_Meters/Half_Hour

https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/Items?groupName=Demo\ipmsdemo-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>

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}”)]

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}”)]

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}”)]

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.

https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/EquationError?dataItemName=Demo|ipmsdemo-meniscus.co.uk|Daily_electricity_use_channel_1|CALC&templateName=StandardValueCalculatorTemplate&equation=sum(dataset(Electricity_use_channel_1_HH,today,today+1))

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.

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>

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}”)]

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}”)]

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.

This is the method for returning all Costs

https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/Costs?companyName=Demo&siteName=ipmsdemo-meniscus.co.uk

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>

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}”)]

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}”)]

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}”)]

This is the Method to list all costData for a Method

This is the same Method as that for listing all Costs

https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/Costs?companyName=Demo&siteName=ipmsdemo-meniscus.co.uk

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>

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}”)]

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}”)]

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.

This Method will return a list of all Conversions.This Method is the same as that for listing Units

https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/Units?companyName=Demo&siteName=ipmsdemo-meniscus.co.uk

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>

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}”)]

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}”)]

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.

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}”)]

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}”)]

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}”)]

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

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.

https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/Data?dataItemNameList=Demo|ipmsdemo-meniscus.co.uk|Electricity_use_channel_1_HH|CALC&startTime=01/10/2017&endTime=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

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

https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/Data?dataItemNameList=Demo|ipmsdemo-meniscus.co.uk|Electricity_use_channel_1_HH|CALC,Demo|ipmsdemo-meniscus.co.uk|Electricity_use_channel_2_HH|CALC&startTime=01/10/2017&endTime=03/10/2017

The dataItemList must include the full name for the Item i.e. including the Company|Site

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

https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/Data?dataItemNameList=Demo|ipmsdemo-meniscus.co.uk|.*|CALC&startTime=01/10/2017&endTime=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 )

https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/Data?dataItemNameList=Demo|ipmsdemo-meniscus.co.uk|.*|CALC&startTime=01/10/2017&endTime=02/10/2017&costList=Electricity

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

https://restdemo.meniscus.co.uk/MCE/MeniscusRESTWebService/Data?dataItemNameList=Demo|ipmsdemo-meniscus.co.uk|.*|CALC&startTime=01/10/2017&endTime=31/10/2017&areaList=Half_Hour,Daily

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.

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.

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

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

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

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

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

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

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

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

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

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.