API Queries - Report

The report function creates a parking statistic report. Additional parameters are optional for this function.

Additional Parameters

• from_date & to_date - The report date range. Dates must be in the format YYYY-MM-DD.
  Note: Valid combinations are from_date and to_date parameters together, or period only. (Optional)
• period - The report date period. Accepted values are "today", "yesterday", "last7days", "lastmonth", "last30days", "monthtodate", "last3months", "last12months" and "alltime".
  Note: Values are case-sensitive. Valid combinations are from_date and to_date parameters together, or period only. (Optional)
• groupby - How to group data on the report. Accepted values are "folder", "domain", "day", "month", "month_domain", "month_service" and "date_service". Default is "domain" (Optional)
• folder - Name of the folder to retrieve statistics for (Optional)
• service - Name of the service to retrieve statistics for. Accepted values are "bodis", "domainadvertising", "domainapps", "domainsponsor", "dotzup", "fabulous", "hotkeys", "domainnamesales", "maximizer", "parkingcrew", "rookmedia", "sedo", "skenzo", "smartname", "theparkingplace" and "voodoo".
  Note: Values are case-sensitive. (Optional)
• start - The starting offset for results. Default is 0 (Optional)
• num - The number of results to show from the report. Default is 100, maximum is 1,000 (Optional)
• demographics - This will display the hits from the top 10 countries. Default is "0" (disabled). Accepted values are "0" (disabled) and "1" (enabled). (Optional)
• trafficsource - This will display the traffic source data collected when Above.com's nameservers are used. Default is "0" (disabled). Accepted values are "0" (disabled) and "1" (enabled). (Optional)
• revonlydomains - This will generate a report showing only domains that have a revenue greater than $0. Default is "1". Accepted values are "0" (disabled) and "1" (enabled). (Optional)
• demographics - This will display the hits from the top 10 countries. Default is "0" (disabled). Accepted values are "0" (disabled) and "1" (enabled). (Optional)
• format : Default= xml. Accepted values are 'csv' or 'xml' (Optional)

Note: Make sure to URL encode all values.

Notes on Parameter Combinations

• Valid combinations are from_date and to_date parameters together, or period only.
• Reports grouped by domain. These can have service and/or folder, demographics and/or trafficsource specified. Either a canned period or a custom date range can be specified. These are always generated in the background.
• Reports grouped by folder. Service can NOT be specified for these. Reports with a custom date range are generated in the background, canned periods are returned instantly.
• Reports grouped by day. Folder can be specified but service can NOT be specified. All reports are returned instantly.
• Reports grouped by month. Folder can be specified but service can NOT be specified. All reports are returned instantly. Partial months are not supported - only full months of data are returned.
• Reports grouped by month_domain. Folder can be specified but service can NOT be specified. These can have demographics and/or trafficsource specified. Either a canned period or a custom date range can be specified. These are always generated in the background.
• Reports grouped by month_service. Folder can be specified but service can NOT be specified. Either a canned period or a custom date range can be specified. These are always generated in the background.
• Reports grouped by date_service. Folder can be specified but service can NOT be specified. Either a canned period or a custom date range can be specified. These are always generated in the background.

Example queries and responses:

• In this example, we will fetch statistics from 2009-03-01 (from_date=2009-03-01) to 2009-03-31 (to_date=2009-03-31), grouped by domain (default, if groupby is omitted).

  As this report data is not cached, it will be generated in the background. The response will include the current status "Generating" and the report ID, which you can use to retrieve the report once it is ready. You can check the status of the report or retrieve it when is ready, using the Fetch API function.

  Example query:
  https://www.above.com/api.php?username=user&password=pass&api_key=key&mode=report&from_date=2009-03-01&to_date=2009-03-31&start=0&num=100

  Response:
  

  			<results>
  			<result reportid="12345" status="Generating" />
  			</results>
  				

  
  

• In this example, we will fetch statistics from the last 7 days (period=last7days), grouped by day (groupby=day). This report data is cached, so it is retured instantly.

  Example query:
  https://www.above.com/api.php?username=user&password=pass&api_key=key&mode=report&period=last7days&groupby=day&start=0&num=100

  Response:
  

  			<results>
  			Date,Hits,Uniques,Reported,Clicks,Revenue,CTR,EPC,RPM
  			2010-09-03,25040342,650064,626752,76195,8632.27,12.16,0.11,13.77
  			2010-09-04,23721786,624412,608911,71070,7832.17,11.67,0.11,12.86
  			2010-09-05,24445721,606606,595510,67925,7943.29,11.41,0.12,13.34
  			2010-09-06,26173088,656610,639723,72431,8446.99,11.32,0.12,13.20
  			2010-09-07,25931218,679469,696465,74580,9888.40,10.71,0.13,14.20
  			2010-09-08,26300738,683867,419405,24701,4284.57,5.89,0.17,10.22
  			2010-09-09,24735673,1385507,20486,2144,279.25,10.47,0.13,13.63
  			</results>
  			

Error Responses:

Possible error responses for this function are:

• 412 - Period, from_date and to_date combination or value is invalid
• 413 - Folder Not Found
• 414 - Service Not Found
• 415 - Groupby invalid
• General errors, such as 200 - Internal Error or 300 - Username or password invalid.

For a complete list of error responses, see the Error Codes manual page.