|
|
The Refresh Analytics REST API allows application owners and application / advertising networks access to their applications' analytics without using the Refresh Analytics Facebook application directory. The API supports both application management & analytics reporting. The interface is a REST API over a HTTP GET or POST request and returning XML data.
This is RELEASE 1.0 of the Refresh Analytics REST API specification.
Before accessing the Refresh Analytics REST API, the application owner or ad network representative needs to contact Refresh at info@refreshpartners.com to enable API access and receive a shared secret used to sign API requests.
Refresh has made a PHP client library available to access the REST API. If you are using this client library, then you only need to review the API Methods documentation.
A valid time-stamp (using the 'time' URL argument) is mandatory for all requests. Furthermore, the client time-stamp must be within 15 minutes of the Refresh Analytics REST API server time when the request is received. If not, the request will fail with the API_ERROR_BAD_TIME error status code.
The intention of this restriction is to limit the possibility that intercepted requests could be replayed by an adversary.
The argument's format is that of a unix timestamp, which is the current time measured in the number of seconds since the Unix Epoch (January 1 1970 00:00:00 GMT). Please note that the time value needs to be a GMT timestamp!
All REST calls are made in a similar fashion. A HTTP GET or POST request is sent to api.refreshanalytics.com with at least five URL arguments; method, time, uid, version and sig.
All API calls use a signature mechanism to both authenticate the user as well as sign the entire request to make sure that it wasn't modified in transit.
The process of signing is as follows.
The XML result returned will have the following format:
<?xml version="1.0" encoding="UTF-8"?> <response> <error>0</error> <method>##method##</method> <##objects## list="true"> <##object##> <##object_field1##>##object_data1##</> <##object_field2##>##object_data2##</> ... </##object##> ... </##objects> </response>
When an error is returned, the following format will be used:
<?xml version="1.0" encoding="UTF-8"?> <response> <error>##error_number##</error> <error_msg>##error_msg##</error_msg> <method>##method##</method> </response>
Returns a list of applications that the user has access to as either a developer or as a viewer.
Returns an array listing each application's name, api_key and other information.
<?xml version="1.0" encoding="UTF-8"?> <response> <error>0</error> <method>application.list</method> <application_list_response list="true"> <application> <api_key>. . .</api_key> <api_id>. . .</api_key> <name>Test application</name> <developers>321, 654, 987</developers> <viewers>123, 456, 789</viewers> <secret>/no</secret> <verified>yes</verified> </application> . . . </application_list_response> </response>
Retrieves the information about an application that is stored with Refresh Analytics.
Returns a single application's information, similar to that of application.list()
<?xml version="1.0" encoding="UTF-8"?> <response> <error>0</error> <method>application.getInfo</method> <application_getInfo_response list="true"> <application> <api_key>. . .</api_key> <api_id>. . .</api_key> <name>Test application</name> <developers>321, 654, 987</developers> <viewers>123, 456, 789</viewers> <secret>/no</secret> <verified>yes</verified> </application> </application_getInfo_response> </response>
Returns the FBML/HTML or script code required to track the application's users demographic and analytic information
If the application has a registered secret, then the following is an example of what is returned;
<?xml version="1.0" encoding="UTF-8"?> <response> <error>0</error> <method>application.getCode</method> <application_getCode_response list="true"> <code> <fb:iframe src="http://demographics.refreshanalytics.com/get.php?api_key=. . ." frameborder="0" width="1" height="1" /> </code> </application_getCode_response list="true"> </response>
If no secret is registered, then the following would be an example of what is returned;
<?xml version="1.0" encoding="UTF-8"?> <response> <error>0</error> <method>application.getCode</method> <application_getCode_response list="true"> <code> #! /usr/bin/env python import urllib, md5 def ra_getcode(uid, api_key, secret, session_key): url = 'http://refreshanalytics.com/demographics/get.php?api_key=%s&uid=%d&session_key=%s' file = urllib.urlopen(url % (api_key, uid, session_key)); rs = file.readlines() if(len(rs) < 4) return rs[0] sig = '' for i in range(2, len(rs) - 1): hash = md5.new() hash.update(rs[i].strip() + secret) sig += hash.hexdigest() + '+' return rs[0].strip() + 'sig=' + sig + '"' + rs[1].strip() # you may need to change the uid, secret_key and session_key values # to make this work in your environment print ra_getcode(facebook.uid, facebook.api_key, facebook.secret_key, facebook.session_key) </code> </application_getCode_response list="true"> </response>
Returns the summary report for an application or applications
A call to analytics.getSummary() with a count of 3 and categories of 'country' and 'state' would produce data similar to the following:
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>0</error>
<method>analytics.getSummary</method>
<analytics_getSummary_response list="true">
<summary>
<api_key>. . .</api_key>
<category>country</category>
<total>239</total>
<values list="true">
<value>
<name>Canada</name>
<count>86</count>
</value>
<value>
<name>Australia</name>
<count>33</count>
</value>
<value>
<name>United States</name>
<count>26</count>
</value>
</values>
</summary>
<summary>
<api_key>. . .</api_key>
<category>state</category>
<total>235</total>
<values list="true">
<value>
<name>Ontario</name>
<count>54</count>
</value>
<value>
<name>Western Australia</name>
<count>17</count>
</value>
<value>
<name>Ile-de-France</name>
<count>16</count>
</value>
</values>
</summary>
</analytics_getSummary_response>
</response>
Returns the historical report for an application or applications
A call to analytics.getHistorical() with a count of 3, category of 'country', report of last31days and a time frame of 10 days would produce data similar to the following:
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>0</error>
<method>analytics.getHistorical</method>
<analytics_getHistorical_response list="true">
<historical>
<api_key>. . .</api_key>
<category>Country</category>
<dates>2008-06-26,2008-06-27,2008-06-28,2008-06-29,2008-06-30,2008-07-01,2008-07-02,2008-07-03,2008-07-04,2008-07-05</dates>
<values list="true">
<value>
<name>United States</name>
<counts>13,0,1,0,0,2,4,0,0,1,0,1,0,0,0,1,1,3,2,2,2,3,0,1,0,0,0,0,1,1,2,2</counts>
</value>
<value>
<name>United Kingdom</name>
<counts>0,0,0,1,2,1,1,3,5,2,1,5,2,1,2,0,2,2,0,1,1,2,1,0,0,0,0,0,1,1,0,0</counts>
</value>
<value>
<name>Turkey</name>
<counts>0,0,0,1,0,0,1,0,0,0,0,2,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,1,0,1,0</counts>
</value>
</values>
</historical>
</analytics_getHistorical_response>
</response>