Basil Shkara

App Sales Machine - pulls, parses, stores and emails App Store reports

comments [ appengine python appstore ] 05 September 2009

[UPDATE 20090910] Now parsing the Top 200 rankings.

[UPDATE 20090909] App Sales Machine now automatically generates graphs using Graphy and also sends HTML formatted emails.

I recently spent a couple days writing an App Engine application using the webapp framework. App Sales Machine does the following:

  1. Imports a tarball of your existing sales reports and stores them in the datastore.
  2. Logs into iTunes Connect every morning, downloads your latest sales report and stores it in the datastore.
  3. Parses the downloaded report and stores the parsed data in the datastore.
  4. Converts the reported income revenue of your sales to a configurable currency and stores that.
  5. Pulls the rankings for your app every 8 hours (configurable) and stores that in the datastore.
  6. Emails a report to a select group of recipients every morning with the latest cumulative figures, as well as the last downloaded report’s figures.

It utilises the task queues API to fetch your rankings asynchronously in a staggered approach. And if the daily sales report pull times out, it will add that task to the task queue to keep trying until it is downloaded.

All of this was made possible because of the following pieces of open software:

I made some modifications to itunes-connect-scraper to use the URL Fetch API so I could increase the connection timeout to the maximum currently allowed on App Engine (10 seconds).

The data parsing and currency converting code is borrowed and modified from iTunesConnectArchiver.

I also ported the app_rank.pl Perl script to Python. It was originally written by Ben Chatelain but it seems to have been taken down, however it still lives on in other forms albeit still in Perl (read the comments in his original blog post).

The variety of scripts available to download and parse your own report data is just an indication of the poor state of tools that Apple has provided iPhone developers with which to monitor their sales. In fact an entire ecosystem has sprung up to capitalise on this void (appFigures, heartbeat, TapMetrics, Appstatz, AppViz, My App Sales).

There are some free tools (as well as the above scripts) available such as MajicRank and AppSalesMobile but nothing really comparable to the kind of reporting you get from one of the above paid tools. App Sales Machine isn’t really comparable either at this stage and I don’t know if it ever will be.

There’s nothing wrong with any of the above tools, in fact I used appFigures for a while and was quite happy with it. App Sales Machine was inspired by their functionality but I just wanted to be in control of my own data.

In its current state App Sales Machine may offer all the functionality you require. It does for me currently but there is certainly room for extending it’s current feature set. There is currently a very minimal frontend interface which consists of just a file upload field to upload your existing sales reports. It wouldn’t be hard to integrate nice charts as email attachments (e.g. Graphy) or even as part of a frontend interface.

How to install

# SKU of the app when you uploaded it to the App Store
"<<SKU>>": {
	# Human-readable app name which corresponds to the above SKU
	"name": "<<app name>>",

	# App ID (can be found from the GET param of your iTunes URL i.e. ?id=xxxxxxxxx)
	"app_id": "<<app id>>",

	# Make sure your category name and corresponding ID exists in jobs/app_store_codes.py
	"category_name": "<<category name>>",

	# Is your app free?
	"paid": False,

	# List of dictionaries which represent the human-readable version number and the
	# date the version was released on the App Store
	"versions": [{'name': 'v1.0', 'date': datetime.date(2009, 6, 22)},
			{'name': 'v1.1', 'date': datetime.date(2009, 7, 18)}],

	# This must be the email address of a registered administrator for the application due to
	# mail API restrictions
	"from_address": "My Name <sender@example.com>",

	# List of email addresses you would like the daily reports sent to
	"to_addresses": [
		'Recipient Name <recipient@example.com>',
	]
}

cron:
- description: Daily report pull
  url: /jobs/pull_report
  schedule: every day 06:00
  timezone: Australia/Sydney

- description: Rankings pull
  url: /jobs/pull_rankings
  # Must be larger than 1 hour, see email_report.py
  schedule: every 8 hours
  timezone: Australia/Sydney

- description: Daily report email push
  url: /jobs/email_report
  schedule: every day 07:00
  timezone: Australia/Sydney

What you get

If all goes well, the scheduled email task should push a daily report to your inbox that looks something like this:

Hello,

Here is your daily report for <<app name>>
--

Yesterday's (2009-09-03) download figures:
       - xx

Yesterday's (2009-09-03) upgrade figures:
       - xx

Total number of downloads (2009-06-22 to 2009-09-03):
       - xxxxx

Total number of upgrades (2009-07-18 to 2009-09-03):
       - xxxxx

Upgrade rate (over base of xxxxx):
       - xx.xx%

Approximate total income revenue (AUD):
       - 0.0

Rankings (as of 2009-09-04 16:59:27.615497 UTC):

       Country                  Category                 Ranking
       -------                  --------                 -------
       New Zealand              Lifestyle                67
       Australia                Lifestyle                6

I’ve been using App Sales Machine for the past week and it’s been working beautifully. It lets me and the other stakeholders in the app know about its progress and how it’s tracking.

And because everything is stored in GAE’s datastore under your own administrator account, you can write new webapp handlers and templates to query the data and generate graphs, etc. if you wish.

The usual disclaimers apply here. Although I’ve been using it happily for a while now, I take no responsibility for incorrect reporting or loss of data that App Sales Machine causes. With that being said, I hope you find a use for it.