Historical Application Statistics Available via APIs

The hi5 Platform Team is continuing to make changes that help developers better understand the growth trends of their products. To this end, we are making application statistics accessible via the API server. Before making this public, we would like your feedback on the design of the API. Please read through these specs and let us know what you think of them!

Developers will have to authenticate themselves by creating an authToken — any of the developer accounts associated with an application can be used to access the stats for an application. Statistics can be generated for all or some of the applications owned by the developer account requesting the data.

The API has three endpoints:

1. metrics/daily: These are daily stats, not uniq'ed per user. You can query the data for a range of dates, not exceeding 30 days. Requests for more than 30 days will be truncated to 30 days, starting at the start date.
2. metrics/dailyuniques: These are the same type of stats as returned by metrics/daily, but accounting for uniques. This means that if a single user views a canvas page on your application more than once, it will count as just 1 unique canvas page view in these metrics.
3. metrics/total: These are total stats calculated for the applications, aggregated since your application launched.

The input parameters are supplied in the URL and the parameters and the acceptable values are all case sensitive. Only the Hi5AuthToken parameter is required

Parameters

1. metric: If this parameter is not specified, then all available metrics are displayed. You can request the following metrics with this parameter:
   1. install: Total number of installs
   2. remove: Total number of removes. You will have to subtract this from the total number of installs to get the net installs of your application for the applicable time period.
   3. view_profile: Calls to the profile module
   4. preview: Calls to the preview module
   5. canvas: Calls to the canvas module
   6. block: Block requests generated in response to emails and notifications generated by your application_,_ and on the My Applications page.
   7. api_request: API requests sent to our API servers by your application
   8. report_abuse: Notifications generated by your application marked as spam
   9. activity_requested: Requests to generate a Friend Update
   10. activity_sent: Friend Update requests fulfilled
   11. invite_requested: Friend Invite requests generated. Note that this counts a request containing multiple friends as one request
   12. invite_sent: Friend Invite requests fulfilled
   13. notification_requested: Notification API requests made to the API servers
   14. notification_sent: Notification API requests fulfilled. Note that when an API request is fulfilled, not all the recipients in the API request might receive the request, as some might already have received the limit of per-recipient notifications allowed.
   15. all: All of the above
2. context: The context breaks up each statistic in the metric parameter based on the origin of the corresponding action. Note that not all contexts are valid for all actions — for example, blocks can only occur in the invite, myapps and notification contexts, by definition. If context is not specified then breakdown by context will not be displayed. The possible values of context are:
   1. activity_stream: From all links in a Friend Update, if that link is on a user's home page, or from a Friend Update's "More" link if the Friend Update is being viewed on the logged-in user's or someone else's profile.
   2. apphome_friend: From the My Applications page of the currently logged-in user, when the user clicks on a recommended application (currently, applications installed by a user's friends)
   3. apphome_owner: From the My Applications page of the currently logged-in user, when the user clicks on one of their own applications (currently, user's recent applications)
   4. gallery: From the hi5 Application Gallery
   5. homepage: From the homepage applications box at the top right of the page
   6. invite: From a friend invite
   7. myapps: From the Manage Applications page
   8. notification: From a notification
   9. other_profile: From the profile of someone other than the currently logged-in user
   10. own_profile: From the profile of the currently logged-in user
   11. profilenav: From the View More link on the Profile module, and from the Applications drop down in the navigation bar at the top of the Profile page
   12. unknown: From an unknown context, usually generated when the user comes from a link placed in a Profile module or Friend Update by the application (Note that this number is inflated because invites are not being tracked correctly; this will be fixed soon.)
   13. all: All the contexts applicable to a given action
3. start and end: The start and end dates, respectively, in YYYY-MM-DD format. The dates must be "consistent," that is, the end date cannot precede the start date, and they must both be valid calendar dates. A range greater than 30 days generates an error. If no dates are specified then data for the latest available timestamp (typically, for "yesterday") is displayed.
4. Hi5AuthToken: The auth token generated via the REST API for your API key and login information.
5. api_key: The acceptable values are the API keys of the applications owned by the developer making the request; API keys for other applications will generate an error and return no statistics. To return statistics for more than one application (but not all applications) owned by you, specify the api_key parameter multiple times. If no api_key is specified then the one that was used to generate the auth token will be used.

To begin, we will not rate limit this API and expect that the volume will be no higher than once a day per application. Improper use of this API will lead to the offending API keys being blocked from access to this functionality.

We look forward to your feedback. Thanks!