API
TrainingSupportCommunity

mPulse Queries

Introduction to mPulse Queries

The Query API for mPulse is a unified REST API that allows mPulse customers to fetch aggregate data and receive a JSON response with mPulse data. Data sets, Navigation Timing, Custom Timers, and metrics are supported.

Data for a given date is aggregated per minute for the given 24-hour period. Data returned will always be limited to one calendar day in the timezone. If the date is ‘today’ it is still aggregated per minute, only from midnight to the current time (e.g. the time of the query).

📘

Note:

For instance, the Summary widget shows the summary data for the whole day if it’s before today or since midnight today. In this case, summary data is for all minutes on that day. Other instances where this is the case are widgets for Page Groups, browsers, A/B tests, and bandwidth.

For some charts, such as the Last 30 Days chart on the “Load Time vs. Page Views widget, it is necessary to call the Summary API 30 times (or the correct number of days for the given month) to get all the summary aggregate data for the time period.

Drilldowns are supported but not all combinations (mostly dimensions) are supported. For example, drilldowns by Page Groups + browsers + A/B tests are supported. When a drilldown by a combination is not supported, its response will contain no data.

This API uses HTTP in the following ways:

  • HTTP PUT is used to get a security token that is used in subsequent queries.
  • HTTP GET is used to retrieve the aggregate data.

Wrappers

A JavaScript wrapper is available at mpulse-query.js.

REST API URLs

Once a security token is acquired, it is used in all subsequent queries within the validity period. The URLs for accessing the REST API use the token, the mPulse instance, the domain, the query type(s), and any optional parameters that go with the query type, and take the following format:

/concerto/mpulse/api/v2/<api-key>/<query-type>?<optional parameters>

If curl is used, the command line looks like this:

curl -H "Authentication: <security token>" \
  "https://mpulse.soasta.com/concerto/mpulse/api/v2/<api-key>/<query type>?<optional parameters>"

API rate limits

  • Concurrent API calls: 3
  • API calls per minute: 100
  • API calls per hour: 10000
  • API calls per day: 50K

For Concurrent API calls, you can use the following formula to find out whether you will hit the concurrent limit:

Average Duration (in minutes) = Concurrent Limit / Maximum number of parallel requests

For example, if you execute 15 calls per minute and the concurrent limit is 3, then the call duration should be 1/5 minute (12 sec) or less (1/5 = 3 / 15). If you see warning messages that your calls have been limited you need to reduce the number of calls per minute.

Example Python code for mPulse API Query component

Python Example 1: sample.py

######################################
# Sample code using mpulse.py library

import mPulse

# Setting mPulse username, password and API Key
username="example@akamai.com"
password="xxx"
APIKey="ZPJEW-ARB6D-HUSS4-X4H6D-2NJLX"

# Initializing instance of mpulse object
mp = mPulse.mPulse(username, password, APIKey)

# Fetching data
print mp.getData('histogram')

metric="summary"
print mp.getData(metric)
print mp.getData(metric+'?date=2014-09-02&page-group=getbird')
print mp.getData(metric+'?date-comparator=Last24Hours&page_group=best')

Python Example 2: mpulse.py

####################################
# Mpulse Webservice Python API

import requests
import json

class mPulse:

    # Constructor, will initialize connection to mPulse and call getToken method
     # Param: nPulse username, password and mPulse app API Key
    def __init__(self, username, password, APIKey):
         try:
             self.API = APIKey
             self.token=self.getToken1(username, password)
         except exception, e:
             print "Failed to Initialize mPulse instance ", e.args,str(e)

    # Internal Method for fetching authentication token and storing it in global variable
    # Param: nPulse username, password
    def getToken1(self, username, password):
         try:
              URL = "https://mpulse.soasta.com/concerto/services/rest/RepositoryService/v1/Tokens"
             fp = requests.put(URL, data='{ "userName":"'+username+'", "password":"'+password+'"}')
              js= json.loads(fp.content)
              return js['token']
     except exception, e:
              print "Failed to get Token ", e.args,str(e)

    # Generic data fetching function from mPulse, will return JSON response from the server
    # Param: data keyword (summary, histogram, etc.)
    def getData(self, data):
         try:
           if not "?" in data&colon;
           addFormat="?format=json"
         else:
           addFormat="?format=json"
              URL="https://mpulse.soasta.com/concerto/mpulse/api/v2/"+self.API+"/"+data+addFormat
             fp = requests.get(URL, headers={"Authentication":self.token})
             if fp.status_code<>200:
               return str("Error: "+str(fp.status_code)+", "+fp.reason)
             return fp.content
         except exception, e:
              print "Failed to get data ", e.args,str(e)