API Blog Series Part 4: Controlling Cost and Usage through API

 

API Blog Series Part 4: Controlling Cost and Usage through API

In the last edition of the EMnify API Blog Series we covered the importance of SMS in IoT/M2M and how to send and receive application-to-peer (A2P) SMS messages over API. To close off our API Blog Series, Part 4 will  explain how you can use API calls to retrieve statistics on data usage and cost.

In case you missed out on the previous editions of the Blog Series, read them here:

Part 1: API Driven IoT & M2M 

Part 2: Auto-provisioning over API 

Part 3: SMS over API


Gain insights into usage and cost statistics

The EMnify RESTful API allows you  to integrate the provisioning, management and monitoring  of connectivity  for your IoT & M2M products and services into your existing IT systems and business process in an automated way. You can use our API to programmatically retrieve usage and information in real-time. This gives you the ability to gather data and integrated it with your existing data analytics or monitoring system or even build your own usage-based billing system. We understand the importance and need to predict, manage and control usage and costs and EMnify’s API provides the ability to do that.

 

Cost & Usage Statistics for M2M/IoT

Cost and usage statistics are aggregated metrics that pinpoint which SIMs are sending and receiving data, how much data is being sent, and when the data activity occurs. Since data fees are incurred through usage, these statistics can help you pinpoint how, when and where your fees originate. This can help developers optimize their applications, and can enable customers to segment billing charges.

Example: Optimize data

A pipeline monitoring company has set their SIM cards to send a certain amount of data in a specific time. While tracking statistics on data usage, the company realized that one SIM pulls significantly more data than others, and is transferring data outside of a fixed timeframe. By examining their software calls through the API they were able to identify a line of code that instructed the SIM to transmit useless data. By modifying the code, the unnecessary transmissions ceased, helping to save on airtime costs.  

 

Example: Segment Billing

A fleet tracking company is running two projects in Mexico. In order track the budgets of each project, the costs incurred by each SIM must be segmented. By integrating into the EMnify API and pulling costs statistic for each SIM, the company can monitor how much is being spent on each project. EMnify usage statistic enables them to retrieve their billing information in real-time, not just at the end of the month, and to set usage limits for each project to prevent overages.

 

Track Real-Time Costs

In order to avoid the ‘bill shock’ at the end of the month, our API gives you an ability to always keep a transparent record of your usage and costs. By analyzing hourly and daily statistics you can create a cost estimate for you and your customers. Many traditional mobile operators only provide a billing statement at the end of each month, and users are expected to decide which data charges should be assigned to their customers. With the EMnify API, you get real-time, detailed information that enables you to simplify your budgeting and billing process and create future cost projections to avoid unexpected expenses from unnecessary and unknown cost factors.

 

Get cost and usage analysis of specific devices

You can create a consumption analysis for each of your devices and observe how it impacts the total cost. For example, you can pinpoint a specific device that may be pulling too much traffic, or like the first example above, you may have unnecessary code that is asking for feedback too often. With this knowledge, you can pinpoint the problem areas and optimize your programs.

 

Set up volume limits

On the EMnify’s User Interface (EUI) you can set up the limits for different teleservices such as data consumption and have SIMs automatically blocked when the limit is reached. By using different service profiles you can set up individual settings according to the requirement of your use case. Also, SIMs can be automatically unblocked this way to resume service once the given time period is expired.

Any blocking events will also be recorded in your event log that is accessible via our API. This way you can integrate that data with existing dashboards you might use for the monitoring of your business and bring all key information together at one place. Important events like having SIMs exceeding their limits will instantly show up there, and your operations and support teams can take instant action to release the limit or investigate on deviations from normal usage patterns

 

Sample Dashboard based on EMnify API

screen-shot-2016-11-03-at-11-09-19

 

Retrieving cost and usage information over API

Quickly check current and last month usage for all my SIMs

To easily show a monthly overview on your own dashboard just a simple API calls is needed and you have all information at hand.

GET api/v1/organisation/my/stats

{
	"last_month": {
		"data": {
			"month": "2016-10-01",
			"traffic_type_id": "5",
			"currency_id": "1",
			"volume": "206.955299",
			"volume_tx": "62.395702",
			"volume_rx": "144.559597",
			"cost": "51.5809887500",
			"traffic_type": {
				"description": "Data",
				"unit": "MB",
				"id": 5
			},
			"currency": {
				"code": "EUR",
				"symbol": "\u20ac",
				"id": 1
			}
		},
		"sms": {
			"month": "2016-10-01",
			"traffic_type_id": "6",
			"currency_id": "1",
			"volume": "1617.000000",
			"volume_tx": "794.000000",
			"volume_rx": "823.000000",
			"cost": "97.3600000000",
			"traffic_type": {
				"description": "SMS",
				"unit": "SMS",
				"id": 6
			},
			"currency": {
				"code": "EUR",
				"symbol": "\u20ac",
				"id": 1
			}
		}
	},
	"current_month": {
		"data": {
			"month": "2016-11-01",
			"traffic_type_id": "5",
			"currency_id": "1",
			"volume": "14.749828",
			"volume_tx": "5.343002",
			"volume_rx": "9.406826",
			"cost": "3.6670870000",
			"traffic_type": {
				"description": "Data",
				"unit": "MB",
				"id": 5
			},
			"currency": {
				"code": "EUR",
				"symbol": "\u20ac",
				"id": 1
			}
		},
		"sms": {
			"month": "2016-11-01",
			"traffic_type_id": "6",
			"currency_id": "1",
			"volume": "128.000000",
			"volume_tx": "65.000000",
			"volume_rx": "63.000000",
			"cost": "7.6600000000",
			"traffic_type": {
				"description": "SMS",
				"unit": "SMS",
				"id": 6
			},
			"currency": {
				"code": "EUR",
				"symbol": "\u20ac",
				"id": 1
			}
		}
	},
	"sim": {
		"total": 28,
		"issued": 0,
		"active": 28,
		"suspended": 0
	},
	"users": 5,
	"service_profiles": 7,
	"tariff_profiles": 7
}

 

Retrieve hourly data points for SMS and Data Traffic over all SIMs

Dashboard with graphs are always very useful to easily understand a trend or spot sudden deviations, our API provides you with data points that can easily be consumed with different data analytics or charting libraries.

Sample Hourly Graph with Data Volumes

screen-shot-2016-11-03-at-11-15-10

GET api/v1/organisation/my/stats/hourly

{
	"data": {
		"rx": [
			["21:00", 0.00509],
			["22:00", 0.097697],
			["23:00", 0.022208],
			["00:00", 0.047395],
			["01:00", 0.059527],
			["02:00", 0.060256],
			["03:00", 0.019417],
			["04:00", 0.072331],
			["05:00", 0.069587],
			["06:00", 0.056947],
			["07:00", 0.045694],
			["08:00", 0.103941],
			["09:00", 0.905406]
		],
		"tx": [
			["21:00", 0.007064],
			["22:00", 0.07561],
			["23:00", 0.040989],
			["00:00", 0.042009],
			["01:00", 0.05027],
			["02:00", 0.046224],
			["03:00", 0.027517],
			["04:00", 0.051305],
			["05:00", 0.066631],
			["06:00", 0.046101],
			["07:00", 0.036277],
			["08:00", 0.091284],
			["09:00", 0.154433]
		]
	},
	"sms": {
		"rx": [
			["21:00", 1],
			["22:00", 1],
			["23:00", 1],
			["00:00", 1],
			["01:00", 1],
			["02:00", 1],
			["03:00", 1],
			["04:00", 1],
			["05:00", 1],
			["06:00", 1],
			["07:00", 1],
			["08:00", 1],
			["09:00", 0]
		],
		"tx": [
			["21:00", 0],
			["22:00", 1],
			["23:00", 1],
			["00:00", 1],
			["01:00", 1],
			["02:00", 1],
			["03:00", 1],
			["04:00", 1],
			["05:00", 1],
			["06:00", 1],
			["07:00", 1],
			["08:00", 1],
			["09:00", 1]
		]
	}
}
Quickly check current and last month usage for a SIM

GET api/v1/sim/{simId}/stats

{
	"last_month": {
		"sms": {
			"month": "2016-10-01",
			"volume": "804.000000",
			"volume_tx": "750.000000",
			"volume_rx": "54.000000",
			"traffic_type_id": "6",
			"last_updated": "2016-10-31 23:05:08",
			"cost": "41.2800000000",
			"currency_id": "1",
			"id": 9925,
			"traffic_type": {
				"description": "SMS",
				"unit": "SMS",
				"id": 6
			},
			"currency": {
				"code": "EUR",
				"symbol": "\u20ac",
				"id": 1
			}
		},
		"data": {	
			"month": "2016-10-01",
			"volume": "186.163925",
			"volume_tx": "49.146045",
			"volume_rx": "137.017880",
			"traffic_type_id": "5",
			"last_updated": "2016-11-01 00:00:59",
			"cost": "46.5409812500",
			"currency_id": "1",
			"id": 10171,
			"traffic_type": {
				"description": "Data",
				"unit": "MB",
				"id": 5
			},
			"currency": {
				"code": "EUR",
				"symbol": "\u20ac",
				"id": 1
			}
		}
	},
	"current_month": {
		"sms": {		
			"month": "2016-11-01",
			"volume": "67.000000",
			"volume_tx": "63.000000",
			"volume_rx": "4.000000",
			"traffic_type_id": "6",
			"last_updated": "2016-11-03 09:05:08",
			"cost": "3.4300000000",
			"currency_id": "1",
			"id": 14856,
			"traffic_type": {
				"description": "SMS",
				"unit": "SMS",
				"id": 6
			},
			"currency": {
				"code": "EUR",
				"symbol": "\u20ac",
				"id": 1
			}
		},
		"data": {
			"month": "2016-11-01",
			"volume": "12.025536",
			"volume_tx": "4.121075",
			"volume_rx": "7.904461",
			"traffic_type_id": "5",
			"last_updated": "2016-11-03 09:21:33",
			"cost": "3.0063840000",
			"currency_id": "1",
			"id": 14871,
			"traffic_type": {
				"description": "Data",
				"unit": "MB",
				"id": 5
			},
			"currency": {
				"code": "EUR",
				"symbol": "\u20ac",
				"id": 1
			}
		}
	}
}
Retrieving daily accumulated data for a SIM for a certain time frame

GET api/v1/sim/{simId}/stats/daily?start_date=2016-11-01&end_date=2016-11-03

[{
	"date": "2016-11-03",
	"data": {
		"volume": "1.765425",
		"volume_tx": "0.429901",
		"volume_rx": "1.335524",
		"cost": "0.4413562500",
		"traffic_type": {
			"description": "Data",
			"unit": "MB",
			"id": 5
		},
		"currency": {
			"code": "EUR",
			"symbol": "\u20ac",
			"id": 1
		}
	},
	"sms": {
		"volume": "10.000000",
		"volume_tx": "10.000000",
		"volume_rx": "0.000000",
		"cost": "0.5000000000",
		"traffic_type": {
			"description": "SMS",
			"unit": "SMS",
			"id": 6
		},
		"currency": {
			"code": "EUR",
			"symbol": "\u20ac",
			"id": 1
		}
	}
}, {
	"date": "2016-11-02",
	"data": {
		"volume": "8.227604",
		"volume_tx": "2.553273",
		"volume_rx": "5.674331",
		"cost": "2.0569010000",
		"traffic_type": {
			"description": "Data",
			"unit": "MB",
			"id": 5
		},
		"currency": {
			"code": "EUR",
			"symbol": "\u20ac",
			"id": 1
		}
	},
	"sms": {
		"volume": "31.000000",
		"volume_tx": "28.000000",
		"volume_rx": "3.000000",
		"cost": "1.6100000000",
		"traffic_type": {
			"description": "SMS",
			"unit": "SMS",
			"id": 6
		},
		"currency": {
			"code": "EUR",
			"symbol": "\u20ac",
			"id": 1
		}
	}
}, {
	"date": "2016-11-01",
	"data": {
		"volume": "3.031582",
		"volume_tx": "1.263001",
		"volume_rx": "1.768581",
		"cost": "0.7578955000",
		"traffic_type": {
			"description": "Data",
			"unit": "MB",
			"id": 5
		},
		"currency": {
			"code": "EUR",
			"symbol": "\u20ac",
			"id": 1
		}
	},
	"sms": {
		"volume": "26.000000",
		"volume_tx": "25.000000",
		"volume_rx": "1.000000",
		"cost": "1.3200000000",
		"traffic_type": {
			"description": "SMS",
			"unit": "SMS",
			"id": 6
		},
		"currency": {
			"code": "EUR",
			"symbol": "\u20ac",
			"id": 1
		}
	}
}, {
	"date": "TOTAL",
	"data": {
		"volume": "13.024611",
		"volume_tx": "4.246175",
		"volume_rx": "8.778436",
		"cost": "3.2561527500",
		"traffic_type": {
			"description": "Data",
			"unit": "MB",
			"id": 5
		},
		"currency": {
			"code": "EUR",
			"symbol": "\u20ac",
			"id": 1
		}
	},
	"sms": {
		"volume": "67.000000",
		"volume_tx": "63.000000",
		"volume_rx": "4.000000",
		"cost": "3.4300000000",
		"traffic_type": {
			"description": "SMS",
			"unit": "SMS",
			"id": 6
		},
		"currency": {
			"code": "EUR",
			"symbol": "\u20ac",
			"id": 1
		}
	}
}]

You can find the full list of available API calls documented in our API Specification here

 

Conclusion

We hope that now you gained a better understanding of how to efficiently use API to retrieve cost and usage information in order to track real-time costs, set up volume limits and create bill projections. If you have any questions, don’t hesitate to contact our customer support at support@emnify.com.

In case you missed out on the previous editions of the Blog Series, read them here:

Part 1: API Driven IoT & M2M 

Part 2: Auto-provisioning over API 

Part 3: SMS over API

 

Follow us:

twitter-logo transparent-Linkedin-logo-icon

Share this blog post:

Leave A Comment