Get store metrics with the Analytics API
Shop requirements
To access the Analytics API, a shop must have the advanced report builder feature, included in the Advanced Shopify plan and up. In the API, this feature is called reports_editing.
Set up
Add the read_analytics scope to your new app. The Analytics API comes bundled with the Embedded App SDK. If you already set up the Embedded App SDK, you can skip ahead to the example request.
To start using the Analytics API in your app, include the app.js at the top of your app's <head> element. It has no dependencies and plays well with other libraries like jQuery.
<head>
<script src="https://cdn.shopify.com/s/assets/external/app.js"></script>
...
</head>The SDK should be initialized with the API key and shop's origin immediately after including the app.js file.
<head>
<script src="https://cdn.shopify.com/s/assets/external/app.js"></script>
<script type="text/javascript">
ShopifyApp.init({
apiKey: 'YOUR_APP_API_KEY',
shopOrigin: 'https://CURRENT_LOGGED_IN_SHOP.myshopify.com'
});
</script>
...
</head>This makes the ShopifyApp object available and ready for use.
Example Request
Now that the Embedded App SDK is configured, we can make a request to the Analytics API:
<script type="text/javascript">
ShopifyApp.ready(function() {
var shopifyQL = 'SHOW count() FROM visits SINCE -2w UNTIL today';
var renderData = function(response) {
// do amazing things here
};
var handleError = function(response) {
// handle missing API errors here (missing scopes, back shopifyql, etc...)
};
ShopifyApp.Analytics.fetch({
query: shopifyQL,
success: renderData,
error: handleError
});
});
</script>Example Response
Valid responses from the Analytics API are returned in JSON. Given the following ShopifyQL query SHOW sum(pageview_count) OVER day(timestamp) FROM visits SINCE -1d UNTIL today string, we would expect a response of the form:
{
"result": {
"columns": [
{
"field": "day_timestamp",
"type": "property",
"format": "timestamp",
"unit": "day"
},
{
"field": "sum_pageview_count",
"type": "measure",
"format": "number"
}
],
"data": [
["2016-06-06T00:00:00-04:00", 19321],
["2016-06-05T00:00:00-04:00", 5791]
]
}
}| key | description |
|---|---|
| field | column name eg: day |
| type | column type (property or measure*) |
| format | the data type |
- A property is an attribute of an object, useful for defining groups (e.g. id, name, location).
- A measure is a reference to the value of a property or what's being aggregated (e.g., count of people from location, average name length).
Errors
The API will return errors for invalid ShopifyQL statements. It could also return two specific errors you should be aware of:
"Application is missing 'read_analytics' scope"
This error means that your app was not set up with the read_analytics OAuth scope. You will need to add the scope and have the merchant log in.
"Shop is missing 'reports' feature"
This error should be handled by your app for the best user experience. This means that the store running your app does not have privileges to run the Analytics API. You can choose to use to a different datasource, not display the data you were requesting, or let the user know the reason they cannot see data.