Scanalytics API Tutorial

This tutorial will take you through some of the common use cases of the Scanalytics API including authentication, pulling data and modifying resources. All of our examples will be presented in Python. Before beginning this tutorial you will need a Scanalytics account. Credentials for app.scanalyticsinc.com will be used throughout this tutorial.

Creating an Application

  1. Go to https://query.scanalyticsinc.com/o/applications
  2. Create a new application. Specify the application name, client type and the authorization grant type. If you are unfamiliar with these fields please read about OAuth2 here: https://oauth.net/2/grant-types/. This tutorial contains examples for both password based authentication and client credential authentication.
  3. Save application

Obtaining an Access Token and Refresh Token

The access token is what is used to authenticate requests coming into the API, and has your user's permissions built into it. These permissions are roughly defined by the scope that is returned.

Password-based authentication

import requests
auth_data = {'grant_type' : 'password',
             'username' : USERNAME,
             'password' : PASSWORD,
             'client_id' : CLIENT_ID }
response = requests.post("https://query.scanalyticsinc.com/o/token/", data=auth_data)
print(response.text)

Client credentials authentication

import requests
auth_data = {'grant_type' : 'client_credentials',
             'client_id' : CLIENT_ID,
             'client_secret' : CLIENT_SECRET
             }
response = requests.post("https://query.scanalyticsinc.com/o/token/", data=auth_data)
print(response.text)
Example JSON Response:
{
    "access_token": "74ahOtYDfbFgcoeletKizsMMiNe8W2", 
    "expires_in": 86400, 
    "token_type": "Bearer", 
    "scope": "read", 
    "refresh_token": "8PzBAcr5tnAmwBrTxoc26HLvqCJh7p"
}

Using Refresh Tokens

Refresh tokens are used to get new access tokens after your current one expires. In the example above the access token will expire in 86,400 seconds or 1 day. The refresh token has a one time use, so when requesting a new access token, you will also get a new refresh token. Refresh tokens do not have an experation, they can only become invalidated after being used.

import requests
auth_data = {'grant_type' : 'refresh_token',
             'client_id' : CLIENT_ID,
             'refresh_token' : "8PzBAcr5tnAmwBrTxoc26HLvqCJh7p"}
response = requests.post("https://query.scanalyticsinc.com/o/token/", data=auth_data)
print(response.text)
Example JSON Response:
{
    "access_token": "qobOeu7jmAeDkjPuiAVUMd6MklTDXI", 
    "expires_in": 86400, 
    "token_type": "Bearer", 
    "scope": "read", 
    "refresh_token": "TnbviXlbrMo6mxvmyexh1xyjKvds5f"
}

Using Your Access Token

An access token can be added to a request three ways:

  1. All Requests: Using the HTTP Authorization header
  2. GET Requests: In the URL as a query parameter
  3. POST Requests: In the body of a form encoded request

Example of using an access token in the request header to get user information in Python:

import requests
headers = {'Authorization' : 'Bearer <ACCESS_TOKEN>'}
response = requests.get('https://query.scanalyticsinc.com/v1/whoami', headers=headers)
print(response.text)
Example JSON Response:
{
    "email" : EMAIL,
    "firstName" : FIRSTNAME,
    "lastName" : LASTNAME,
    "timezone" : "America/Chicago"
}

API Rate Limits

The Scanalytics API has rate limits in place for both authenticated and anonymous users. Authenticated users can make up to 180 requests per minute or 1,200 requests per hour. Anonymous users can make up to 20 requests per minute. These rate limits are based credentials tied to access tokens.

API Versioning

Scanalytics uses URL versioning. The current production endpoints will begin with /v2 and legacy /v1 endpoints can still be used for backwards comatibility.

Pulling Data

In this section we will look at the different ways to pull data from our API. Visit our documentation page to get a full list of endpoints and their parameters. For response data formats, see our documentation

Get Resource Information

The Scanalytics API allows you to fetch useful information about devices, arrays and deployments. In this exmaple we will use the endpoint v1/deployment/list, which will return a list of the deployments you have permission to either view or edit.

import requests
headers = {'Authorization' : 'Bearer <ACCESS_TOKEN>'}
response = requests.get('https://query.scanalyticsinc.com/v1/deployment/list', headers=headers)
print(response.text)

Get Aggregation Metrics

In this example we will be using the v1/aggregate/<arrayKey>/visits/<bucket> endpoint. Our aggregation endpoints are a powerful way to bucket data and draw valuable insights from your deployments. Use GET URL query parameters start, end and timezone to window results. The bucket parameter is what defines the aggregation and is in the format <#><time unit>. For example, 1h is used to bucket by the hour.

This example aggregates visit data into 1 hour buckets between March 1st, 2018 at 12:45pm and March 8th, 2018 4:45pm.

import requests
headers = {'Authorization' : 'Bearer <ACCESS_TOKEN>'}
response = requests.get('https://query.scanalyticsinc.com/v1/aggregate/arrayKey/visits/1h?start=2018-03-01T12:45:00&end=2018-03-08T16:45:00&timezone=America/Chicago', headers=headers)
print(response.text)