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.
2.1 Method to return the structure of the data:
The following API call format will give the geometry types a customer has available.
2.2 Output of API Call
The output of the above API call contains information about the child items of the item specified and contains the following:
- 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 “”.
- ID. This is the ID of the child Item. This ID will be used later in Point Expressions.
- Name. The name of the child item. FullName of an Item is basically “FullName of Parent Item Name of the Item”.
- 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
| URL | Result |
|---|---|
| https://ServerName/Map/Admin/Item/ChildItems?count=100&idexp=GetItemId(“Company ABC”)&index=0 | Information about Rainfall |
| https://ServerName/Map/Admin/Item/ChildItems?count=100&idexp=GetItemId(“Company ABC/Rainfall”)&index=0 | Information about Geometry Types Alarms |
| https://ServerName/Map/Admin/Item/ChildItems?count=100&idexp=GetItemId(“Company ABC/Rainfall/Geometry Types”)&index=0 | Information about Pumping Station |
| https://ServerName/Map/Admin/Item/ChildItems?count=100&idexp=GetItemId(“Company ABC/Rainfall/Alarm”)&index=0 | Information 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 Point | https://map-rainuk.meniscus.co.uk/MAP/ReadData/ |
| Expression Type | CalcJson? |
| Expression Library | calc=B2A358EE-D419-4F1E-BA25-21FC13FA5809 |
| API Key | apiKey=demo |
| Expression | exp=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”))) |
3.1 Endpoint:
The structure of the endpoint is https:// ServerName/MAP/ReadData, where ServerName can be different depending on the URL of the required server.
3.2 Expression Type
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 |
3.3 Expression Library
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
3.4 API Key
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.
3.5 Expression
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.