Analytics Reporting API¶
Overview¶
Flurry Analytics provides you with the tools and resources you need to gain a deep level of understanding about your users’ behavior in your apps. Flurry Metrics API allows you to export your data, based on standard formats such as CSV and JSON, allowing you to integrate it into web dashboards, data warehouses and any other system you might use for managing your business.
To get the access to your company data you need to acquire the programmatic app token. The programmatic token should be included in the header as:
Authorization: Bearer programmatic_token_here
Flurry Analytics API Query Builder¶
We’ve created an api console which you can use to build test queries and experiment with our API.
API basics¶
The metrics (reporting) API is organized by tables (product features), currently allowing for independent reporting on App Usage, App Events and Event Params, Real Time, Audience, Technical, Revenue, Crash Report, and Crash Summary Report.
Metrics API endpoint is https://api-metrics.flurry.com/public/v1/data/
The API request comprises of elements that can be combined to query your analytics data. Everything in the API is case-sensitive.
endPoint/table/timeGrain/dimension1/dimension2;show=all/dimension3{…}?metrics=[comma-separated-metrics]&dateTime=[..]&filters=[…]&topN=[..]&sort=[..]&having=[..]&format=[..]&timeZone=[..]
Params |
Required |
Example |
---|---|---|
endpoint |
yes |
|
table |
yes |
appUsage, appEvent and eventParams, realTime, audience, technical, revenue, crashReport, crashSummaryReport |
timeGrain |
yes |
day, week, month, … Table specific. See table details |
dimension |
no |
app, company, country,…Table specific. See table details. |
metrics |
yes |
sessions, activeDevices, …Table specific. See table details. |
dateTime |
yes |
Format for Day, Week: YYYY-MM-DD/YYYY-MM-DD Format for Month: YYYY-MM/YYYY-MM Format for Hour: YYYY-MM-DDTHH/YYYY-MM-DDTHH (HH in 24-hour format) follows ISO 8601 |
filters |
no |
One or more dimension attribute filters that are combined (as AND) to reduce output to match your criteria. id and name are available for all dimensions. Some dimensions have additional attributes that are called the dimensions section. Format: dimension1|attribute-operator[value(s)], dimension2|attribute-operator[value(s)] Operators: in, notin, contains, startsWith Example: country|name-in[‘United States’,’Canada’,’Mexico’] ,appVersion|name-in[‘2.3’] |
sort |
no |
Specify one or more metrics to sort results by. If order is not specified, then it defaults to descending. Example: sort=sessions|desc,activeDevices|desc |
topN |
no |
Reduces result to match the number specified for this parameter. If this parameter is used, then you must also use sort to indicate metric and order by which top-n must be calculated. Example: topN=5&sort=sessions|desc |
having |
no |
Reduces result to match the metrics criteria specified. Can be combined with multiple metrics criteria. Format: metric-operator[value(s)] Operators available: equal(eq), greaterThan(gt), lessThan(lt) and their not versions Example: sessions-gt[1000],activeDevices-notgt[200] |
format |
no |
json (default), csv |
timeZone |
no |
Default results are in UTC time zone. Format: Example: America/New_York or America/Los_Angeles https://en.wikipedia.org/wiki/List_of_tz_database_time_zones |
App Usage Data¶
To get data on session, new, active devices, time spent,.. in your apps check the appUsage table.
Sample request:
https://api-metrics.flurry.com/public/v1/data/appUsage/day/app?metrics=sessions,activeDevices,newDevices&dateTime=2016-07-01/2016-07-03
Further details on App Usage table.
App Event Data¶
Full on reporting on how often an Event occurs, how many unique users trigger an Event, etc.
Sample Request:
https://api-metrics.flurry.com/public/v1/data/appEvent/day/app/appVersion/event?metrics=occurrences&dateTime=2016-07-01/2016-07-03&filters=app|name-in[foo],event|name-in[login,register]
Further details on App Event table.
App Event Parameter Data¶
If you have added parameters to your Event, you can get the report on their occurence
Sample Request:
https://api-metrics.flurry.com/public/v1/data/eventParams/day/app;show=all/event/paramName/paramValue?metrics=count&filters=app|name-in[foo],event|name-in[level_complete]&dateTime=2016-11-07/2016-11-08
Further details on App Event Parameter table.
Real Time App Data¶
Real time app data provides you with real-time data on how your app may be impacted by user updates, user acquisitions, or enhancements.
Sample Request:
https://api-metrics.flurry.com/public/v1/data/realtime/hour?metrics=sessions,activeDevices&dateTime=2016-08-27T12/2016-08-27T13&filters=app|name-in[foo]
Further details on Real Time table.
Audience Data¶
To understand your app audience, including their age and gender, retrieve data from the audience table.
Sample Request:
https://api-metrics.flurry.com/public/v1/data/audience/day/app/generalInterestCategory?metrics=activeDevices&dateTime=2017-04-01/2017-04-02&filters=app|name-in[foo]
Further details on Audience Data table.
Technical Data¶
Retrieve activeDevices metric broken out by top 3 carriers.
Sample Request:
https://api-metrics.flurry.com/public/v1/data/technical/day/app/carrier?metrics=activeDevices&dateTime=2017-04-01/2017-04-02&filters=app|name-in[foo]&topN=3&sort=activeDevices
Further details on Technical Data table.
Revenue Analytics Data¶
Retrieve IAP purchases for one day for all company apps broken out by each product with revenue in USD.
Request:
https://api-metrics.flurry.com/public/v1/data/iapRevenue/day/app/product?metrics=revenueUSD,purchases,purchaseQuantity&dateTime=2017-04-01/2017-04-02&sort=revenueUSD
Further details on Revenue Analytics Data table.
Retention Data (Beta)¶
We recognize that retention analysis is very powerful to understand the health and viability of your app. You can now query retention metrics for an individual app or at company level.
Sample Request:
https://api-metrics.flurry.com/public/v1/data/retention/day?metrics=returnRate,rollingRate&dateTime=2018-01-08/2018-01-15&filters=app|apiKey-in[<flurry_api_key_here>]&token=<programmatic_token>
Further details on Retention Data table.
Errors¶
Code |
Name |
What to do |
---|---|---|
400 |
BAD REQUEST |
You have some sort of syntax error in your request. We couldn’t figure out what you were trying to ask. Check your request format. |
401 |
UNAUTHORIZED |
We don’t know who you are, so send your request again, but tell us who you are. Usually this means you didn’t include proper token authentication information in your request. |
403 |
FORBIDDEN |
We know who you are, but you can’t come in. This is usually because you’re making a request to access data from a company or app to which you do not have access. Please select ‘Viewer’ role to enable programmatic API access using your account. If you leave it as ‘None’, then you will not be able to access metrics via API |
404 |
NOT FOUND |
We don’t know which resource you are requesting. You probably have a typo in your URL path. |
416 |
REQUESTED RANGE NOT SATISFIABLE |
We can’t get that data for you. Time range is too large or not available for reporting. |
422 |
UNPROCESSABLE ENTITY |
We understood the request (ie. syntax is correct), but something else about the query is wrong. Likely something like a dimension mis-match, or a metric/dimension not being available in the requested table. |
429 |
TOO MANY REQUESTS |
You’ve hit the rate limit. Wait a little while for any requests you may have sent to finish and try your request again. |
5xx |
INTERNAL SERVER ERROR |
Some other error on our end. We try to catch and investigate all of these, but we might miss them, so please let us know if you get 5XX errors. |
500 |
MAXIMUM NUMBER OF ROWS REACHED |
Our API retruns a maximum of 50,000 rows in the response. Modify your query to request smaller scope. |
507 |
INSUFFICIENT STORAGE |
The query was deemed too costly to run and rejected. |
Additional Clarification/Tips¶
Case sensitive API is case sensitive. This means that metric, dimension and API request parameter names must be spelled as specified in the document. sessions is not the same as Sessions and is not the same as SeSsIoNs.
Specifying time intervals: dateTime follows ISO 8601 for start and end period. Start date time period is included but end date time interval is excluded from query interval.
Week/month time grains require specifying the exact start and end boundary dates for the query to be well-formed. Month queries must specify first of the month for both start and end period. Week queries must specify dates for Monday of the week for corresponding start and end periods.
The maximum interval supported at this time is 90 days in one single request. Since the API request is a synchronous call to the server, limiting this period allows for faster response to queries. For gathering data for longer periods, please split query into multiple time period queries.
Missing timestamps for scenarios where there are no results for a combination of timestamp, dimensions and any filter criteria, the result timestamps are omitted completely. This is done to reduce the size of results and for faster response to queries.
Filter can only be applied on dimensions that are included in the results requested.
Sorting applies for results within a specific timestamp. This means that results are always ordered first by timestamp and then by any sort criteria that you added to the API request. Also to sort on a metric, the metric needs to be part of the API data request.
Additional dimension attributes can be requested by adding the show clause next to dimension breakdown on the API request. Without the show clause, only dimension name attributes will be included on the result. The how clause must include comma separated dimension attributes or all.
Rate limits To prevent abuse of the system, the API only allows each user to have a certain number of data requests being processed at any one time. If you try to make another request that would put you above the allowed limit, you will be given an error response with an HTTP response status code of 429.
- The following headers will be returned with a 429 response:
X-RateLimit-Limit: The maximum number of credits that the consumer is permitted to charge. All requests consume at least 1 credit but can cost more depending on the resources consumed.
X-RateLimit-Remaining: The number of credits remaining. This number can go negative.
X-RateLimit-RefillPerMinute: The rate (credits/minute) at which credits are refilled.
Programmatic accounts are specific to one company only. Even though you may have access to multiple companies, a programmatic account grants API authorization to one company only. You can have multiple accounts that have access to different sets of apps in case your company/app team organization requires such a configuration.
Forgotten/lost/compromised programmatic tokens require that you delete the programmatic account that you or your company admin created and create a new programmatic account. You will then need to replace the old token with this newly created programmatic account.