Margay Interface User Guides - Zendesk · Margay Interface User Guides Document Reference: 8322 July 2017 Version: 5

Margay Interface User Guides

Document Reference: 8322

July 2017

Version: 5

Page 1

+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000

Eseye, AnyNet, AnyNet Secure and Eseye Logos are registered trademarks of Eseye Ltd © Eseye 2017 Limited.

All Rights Reserved. [email protected] | eseye.com

Version

Number

Date Author Changes

1 Nov 2015 Sam Smith

2 Jun 2016 Sam Smith Branding updated

3 Sep 2016 Sam Smith Published

4 Feb 2017 Sam Smith Added web interface section

Updated API error codes

Branding updated

5 Jul 2017 Sam Smith Branding updated

Page 2

+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000



Contents 1 Introduction ......................................................................................................................................... 3

2 Enabling the Interface ....................................................................................................................... 3

3 Margay API .......................................................................................................................................... 4

3.1 ping: ............................................................................................................................................. 4

3.2 getCookieName: ....................................................................................................................... 4

3.3 login: ............................................................................................................................................. 4

3.3.1 Successful response: ............................................................................................................. 5

3.3.2 Fields ......................................................................................................................................... 5

3.3.3 Errors ......................................................................................................................................... 5

3.4 getAuthenticationInformation ................................................................................................ 8

3.4.1 Successful response: ............................................................................................................. 8

3.4.2 Fields ......................................................................................................................................... 8

3.4.3 Errors ......................................................................................................................................... 9

3.5 getThroughputInformation .................................................................................................... 12

3.5.1 Successful responses: .......................................................................................................... 12

3.5.2 Fields ....................................................................................................................................... 12

3.5.3 Errors ....................................................................................................................................... 13

3.6 logout ......................................................................................................................................... 16

3.6.1 Successful response: ........................................................................................................... 16

3.6.2 Fields ....................................................................................................................................... 16

3.6.3 Errors ....................................................................................................................................... 16

3.7 Coding Examples .................................................................................................................... 18

3.7.1 PHP cURL ............................................................................................................................... 18

4 Web Interface ................................................................................................................................... 19

4.1 Different Time Period Views ................................................................................................... 21

Page 3

+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000



1 Introduction The Margay service enables customers to request data from Eseye servers on a number of

important events in the previous time period.

The Margay service has two delivery methods:

An app agnostic API

A web interface hosted by Eseye

For the API:

The requests are sent through to the Network Information and Management (NIAM) JSON

API. This system is designed to have requests sent frequently and from automated sources,

this collection of JSON formatted data can then be collated by a customer to convert the

data into useful information.

This API sections of this document uses the Postman app only as an example, the API is app

agnostic. The Postman User Guide can be found at https://www.eseye.com/wp-

content/uploads/8314-Postman-User-Guide.pdf. Postman allows you to download the

request in a coding language of your choice, using the Generate Code button.

For the web interface:

The requests are viewable through a collection of graphs.

The time period that the data is for is pre-agreed between Eseye and individual customers

dependent on the requirements and nature of the devices being used.

The system currently provides data on the number of SIM card authentications, and how

much data has been sent to and from the estate.

2 Enabling the Interface To enable the use of Margay on your account speak to your Eseye Account Manager.

To run the requests you will require: your Margay username, password, account portfolioID.

https://www.eseye.com/wp-content/uploads/8314-Postman-User-Guide.pdf

https://www.eseye.com/wp-content/uploads/8314-Postman-User-Guide.pdf

Page 4

+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000



3 Margay API

3.1 ping: This function tests whether the server running. To test the interface in Postman app use the

details shown below, to download a code example of this request use the Generate Code

button:

Request URL: https://margay.eseye.com/Japi/Niam/ping

Command: ‘Post’

Requires no formatted text.

A successful response will read "pong", if this is not returned it means that either the Eseye

server is down or that the request was incorrect.

3.2 getCookieName: This function returns the name of the cookie that is used to keep the session logged in. To test

the interface in Postman app use the details shown below, to download a code example of

this request use the Generate Code button:

Request URL: https://margay.eseye.com/Japi/Niam/getCookieName

Command: ‘Post’


A successful response will read "examplecookie" (with this being an example), if this is not

returned it means that either the Eseye server is down or that the request was incorrect.

3.3 login: This function logs the user on. If you do not log out, but an attempt is made to log in, the

previous user will be logged out, regardless of whether the new login attempt is successful. To

test the interface in Postman app use the details shown below, to download a code

example of this request use the Generate Code button:

Request URL: https://margay.eseye.com/Japi/Niam/login

Command: ‘Post’

Requires the following formatted JSON text:

{

"username" : "exampleusername" ,

"password" : "examplepassword"

}

Click the blue ‘Send’ button.

All responses are when viewed in the pretty form (default setting)

https://margay.eseye.com/Japi/Niam/ping

https://margay.eseye.com/Japi/Niam/getCookieName

https://margay.eseye.com/Japi/Niam/login

Page 5

+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000



3.3.1 Successful response: Successful responses will look as follows:

{

"cookie": "ExampleCookie",

"status": {

"status": "OK",

"errorCode": "",

"errorMessage": ""

}

}

3.3.2 Fields 3.3.2.1 "cookie"

This displays the name of the cookie that is used to keep the session logged in, this line is the

same as the getCookieName function.

3.3.2.2 "status"

This displays the status of the request, will display ERR if the request is unsuccessful, and OK if

successful.

3.3.2.3 "errorCode"

This displays an error code if the request is unsuccessful, if successful will be blank.

3.3.2.4 "errorMessage"

This displays an explanation of the error if the request is unsuccessful, if successful will be

blank.

3.3.3 Errors E0000 – Unknown username or password

{

"status": {

"status": "ERR",

"errorCode": "E0000",

"errorMessage": "Unknown username or password"

}

}

This indicates that the password value was entered incorrectly.

Page 6

+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000



3.3.3.1 E0100 – Unknown username or password

This error message will display as follows:

{

"status": {

"status": "ERR",



}

}

This indicates that the username or password value or parameter was entered incorrectly.

3.3.3.2 E0101 – Invalid JSON


{

"status": {

"status": "ERR",


"errorMessage": "Invalid JSON"

}

}

This indicates that the JSON text was structured incorrectly. Check that your JSON text follows

the format described. Note this error can be received due to Microsoft Word style text being

entered, as some characters are slightly different between Microsoft Word and ASCII. To

avoid this, either type the text in directly, or configure Microsoft Word so that basic ASCII text

is entered.

3.3.3.3 Could not get any response:


This indicates that either you are not connected to the internet or one or more of the

following sections of the Request URL were entered incorrectly. http ://

.eseye.com/

Page 7

+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000



3.3.3.4 <!DOCTYPE html>:

This error message will begin as follows:

This indicates that one or more of the following sections of the Request URL were entered

incorrectly. Margay

Page 8

+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000



3.4 getAuthenticationInformation This function retrieves a summary of authentication information over the last time period. To

test the interface in Postman app use the details shown below, to download a code

example of this request use the Generate Code button:

Request URL: https://margay.eseye.com/Japi/Niam/getAuthenticationInformation

Command: ‘Post’


{


"password" : "examplepassword" ,

"portfolioID" : "exampleportfolioid"

}

All responses are when viewed in the pretty form (default setting)


{

"status": {

"status": "OK",

"errorCode": "",

"errorMessage": ""

},

"auth_count": [

{

"mcc": "234",

"mnc": "10",

"start_date": "2016-08-16 10:07:47",

"stop_date": "2016-08-16 10:08:47",

"auth-accept": "1"

}

]

}

3.4.2 Fields 3.4.2.1 "status"


successful.

3.4.2.2 "errorCode"


https://margay.eseye.com/Japi/Niam/

Page 9

+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000





blank.

3.4.2.4 "auth_count"

This is the heading for the following object.

3.4.2.5 "mcc"

This displays the Mobile Country Code.

3.4.2.6 "mnc"

This displays the Mobile Network Code.

3.4.2.7 "start_date"

This displays the start of the period in UTC.

3.4.2.8 "stop_date"

This displays the end of the period in UTC.

3.4.2.9 "auth_accept"

This displays the number of devices authenticated in the period.

3.4.3 Errors 3.4.3.1 E0000 – Unknown username or password

{

"status": {

"status": "ERR",



}

}


3.4.3.2 E0100 - Unknown username or password


{

"status": {

"status": "ERR",



}

}

This indicates that the username value or parameter or the password parameter or the

portfolioID value was entered incorrectly.

Page 10

+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000





{

"status": {

"status": "ERR",



}

}





is entered.

3.4.3.4 E9991 – No Recent data available for user


{

"status": {

"status": "ERR",


"errorMessage": "No recent data available for user"

}

}

This indicates that there were no data was passed within the last time period.

3.4.3.5 E9992 – User disabled for configuration


{

"status": {

"status": "ERR",


"errorMessage": "User disabled for configuration"

}

}

This indicates that the PortfolioID parameter was entered incorrectly

3.4.3.6 E9998 - Other error

This means that the session should be restarted, if the appears repeatedly contact Eseye

Support team details found at https://www.eseye.com/contact-us/ )

https://www.eseye.com/contact-us/

Page 11

+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000







.eseye.com/




incorrectly. Margay

Page 12

+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000



3.5 getThroughputInformation This function retrieves a summary of data sent and received over the last time period. To test

the interface in Postman app use the details shown below, to download a code example of

this request use the Generate Code button:

Request URL: https://margay.eseye.com/Japi/Niam/getAuthenticationInformation

Command: ‘Post’


{


"password" : "examplepassword" ,

"portfolioID" : "exampleportfolioid"

}

All of these responses are when viewed in the pretty form (default setting)

3.5.1 Successful responses: Successful responses will look as follows:

{

"status": {

"status": "OK",

"errorCode": "",

"errorMessage": ""

},

"data_count": [

{

"mcc": "234",

"mnc": "10",

"databytes_mo": "517",

"databytes_mt": "284",

"start_date": "2016-09-14 16:12:00",

"stop_date": "2016-09-14 16:13:00"

}

]

}

3.5.2 Fields 3.5.2.1 "status"


successful.

3.5.2.2 "errorCode"


https://margay.eseye.com/Japi/Niam/

Page 13

+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000





blank.

3.5.2.4 "auth_count"

This is the heading for the following object.

3.5.2.5 "mcc"

This displays the Mobile Country Code.

3.5.2.6 "mnc"

This displays the Mobile Network Code.

3.5.2.7 "start_date"

This displays the start of the period in UTC.

3.5.2.8 "stop_date"

This displays the end of the period in UTC.

3.5.2.9 "databytes_mo"

This displays the number of bytes sent in the period.

3.5.2.10 “databytes_mt”

This displays the number of bytes received in the period.

3.5.3 Errors

3.5.3.1 E0000 – Unknown username or password

{

"status": {

"status": "ERR",



}

}


3.5.3.2 E0100 - Unknown username or password


{

"status": {

"status": "ERR",



}

}

This indicates that the username value or parameter or the password parameter or the

portfolioID value was entered incorrectly.

Page 14

+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000





{

"status": {

"status": "ERR",



}

}





is entered.

3.5.3.4 E9991 – No Recent data available for user


{

"status": {

"status": "ERR",


"errorMessage": "No recent data available for user"

}

}

This indicates that there were no authentications within the last time period.

3.5.3.5 E9992 – User disabled for configuration


{

"status": {

"status": "ERR",


"errorMessage": "User disabled for configuration"

}

}

This indicates that the PortfolioID parameter was entered incorrectly







Page 15

+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000





.eseye.com/




incorrectly. Margay

Page 16

+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000



3.6 logout This function logs out the current user, the whole session in Tigrillo is destroyed. To test the

interface in Postman app use the details shown below, to download a code example of this

request use the Generate Code button:

Request URL: https://margay.eseye.com/Japi/Niam/logout

Command: ‘Post’


All of these responses are when viewed in the pretty form (default setting)


{

"status": {

"status": "OK",

"errorCode": "",

"errorMessage": ""

}

}

3.6.2 Fields

3.6.2.1 "status"

This displays the status of the request, will returned either ERR or OK.

3.6.2.2 "errorCode"




blank.

3.6.3 Errors

3.6.3.1 E0006 – Permission denied


{

"status": {

"status": "ERR",


"errorMessage": "Permission denied"

}

}

This indicates that the user is already logged out.

https://margay.eseye.com/Japi/Niam/logout

Page 17

+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000










.eseye.com/




incorrectly. Margay


Page 18

+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000



3.7 Coding Examples All of these examples are using the getThroughputInformation

3.7.1 PHP cURL <?php

$curl = curl_init();

curl_setopt_array($curl, array(

CURLOPT_URL =>

"https://margay.eseye.com/Japi/Niam/getthroughputinformation"

,

CURLOPT_RETURNTRANSFER => true,

CURLOPT_ENCODING => "",

CURLOPT_MAXREDIRS => 10,

CURLOPT_TIMEOUT => 30,

CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,

CURLOPT_CUSTOMREQUEST => "POST",

CURLOPT_POSTFIELDS => "{\r\n\"username\" :

\"ExampleUsername\" ,\r\n\"password\" : \"ExamplePassword\"

,\r\n\"portfolioID\" : \"ExamplePortfolioID\"\r\n}",

CURLOPT_HTTPHEADER => array(

"cache-control: no-cache",

"content-type: application/json",

"postman-token: 823e2f1c-d843-c90f-9d07-107061f5e417"

),

));

$response = curl_exec($curl);

$err = curl_error($curl);

curl_close($curl);

if ($err) {

echo "cURL Error #:" . $err;

} else {

echo $response;

}

Page 19

+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000



4 Web Interface The Web interface is located at: http://margay.eseye.com/Niam/index.

Enter your account details and press the ‘Sign In’ button.

This should reveal the ‘Country Selector Page’:

http://margay.eseye.com/Niam/index

Page 20

+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000



Enter the MCC desired and whether you want to see the number of authentications or the

amount of data passed.

As long as there is data for the selected MCC a graph will appear:

Scroll down to view the table of data used to create the graph.

Page 21

+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000



4.1 Different Time Period Views The default view is the last 24 hours.

To alter the period shown use the period select scroll.

To view a larger period use the ‘Return to month’ or the ‘Return to day’ buttons.

To view a smaller period click on the headings in the table.

Documents

Margay Interface User Guides - Zendesk · Margay Interface User Guides Document Reference: 8322 July 2017 Version: 5