This sets out the basis of the MAP API and the specific API methods will be added shortly

There are some example MAP Hyperlocal API calls that show some example calls.

1 Security

MAP uses OAuth for authorization and a username/password combination for Authentication.

The MAP API calls can either use the OAuth username/password combination or they can use a Read Only API key that will be provided by Meniscus.

To apply for an account to test out the calls in your own application then please send a request from our Contact Page

2 MAP Structure

MAP stores items in a tree like structure. To get information about individual items the user is required to know the structure of the item tree.

The output of the above API call contains information about the child items of the item specified and contains the following:

  1. FullName. This is the FullName of the child Item. This full name can be used to return the structure of the child items. This is also used in Point Expressions. When using FullName that has been returned from the above API call, you must replace “\” with “”.
  2. ID. This is the ID of the child Item. This ID will be used later in Point Expressions.
  3. Name. The name of the child item. FullName of an Item is basically “FullName of Parent Item Name of the Item”.
  4. ParentID. The ID of the parent Item. That means Id of the Item whose FullName is used in the API call to get this structure.

The output will be shown in JSON format. The following link can be used to parse the JSON format http://json.parser.online.fr

This is an example of the data structure

So example URLs will be:
URLResult
https://ServerName/Map/Admin/Item/ChildItems?count=100&idexp=GetItemId(“Company ABC”)&index=0Information about Rainfall
https://ServerName/Map/Admin/Item/ChildItems?count=100&idexp=GetItemId(“Company ABC/Rainfall”)&index=0Information about Geometry Types Alarms
https://ServerName/Map/Admin/Item/ChildItems?count=100&idexp=GetItemId(“Company ABC/Rainfall/Geometry Types”)&index=0Information about Pumping Station
https://ServerName/Map/Admin/Item/ChildItems?count=100&idexp=GetItemId(“Company ABC/Rainfall/Alarm”)&index=0Information about Flood Alarms

3 Construction of the URL

The URL used to return data from MAP consists of 5 main parts that are combined to form a URL comprising the Endpoint, Expression Type, MAP Expression Library and Expression.
An example of a complete URL displaying data from a monitoring point at the start of January 2017 is:

End Pointhttps://map-rainuk.meniscus.co.uk/MAP/ReadData/
Expression TypeCalcJson?
Expression Librarycalc=B2A358EE-D419-4F1E-BA25-21FC13FA5809
API KeyapiKey=demo
Expressionexp=Data.ToJson(Data.Aggregate(Data.Resample(Data.GetData(
Data.GetItemId( “58e50578a28f4b0da492654c”,”average rainfall”)),,
ToTime(2017,1,1),ToTime(2017,1,7,23,59,59),Data.Interval(“”)),
ToTime(2017,1,1),ToTime(2017,1,7,23,59,59),
Data.Aggregation(“”,”Sum”,”Forward”)))

The structure of the endpoint is https:// ServerName/MAP/ReadData, where ServerName can be different depending on the URL of the required server.

This part defines the return type of the expression called.

Number Expression Type Description
1 CalcJson? Expects the returned data from the Expression to be in the JSON format for serialising and returning to the browser
2 CalcBool? Expects the returned data from the Expression to be a Boolean for returning to the browser
3 CalcLong? Expects the returned data from the Expression to be a Long (number) for returning to the browser
4 CalcDouble? Expects the returned data from the Expression to be a Double (number) for returning to the browser
5 Calc? Expects the returned data from the Expression to be an array of floats (binary) for returning to the browser

The Expression Library is the set of Methods used in MAP to deliver specific functional tasks. There are a number of generic Expression Libraries that can be used for most requirements. These are:

calc=B2A358EE-D419-4F1E-BA25-21FC13FA5809

This is the library for most standard methods. This is the preferred library to use

API Key (e.g. demo in the example URL) will restrict the access of a user. An API Key will be provided by Meniscus. The user access rights in MAP control access to particular Expression Libraries and to particular Expressions.

The expression processed by MAP. This can be built from one or more expressions nested as required to process data into the format you wanted.