A Grails plugin that allows easy aggregation of app 'score' date sourced via the iTunes API.
Switch branches/tags
Nothing to show
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


The App Report Card Grails Plugin

This plugin aggregates App 'scores' from the iTunes API.

As you might already know there are many iTunes Stores, one for each of over 120 countries; a given App may be available in some or all of these Stores.

Please note that an App outside of any Store has no meaning - except to the developer that owns that App; as such you'll only find the StoreApp entity here.

An App in a particular Store has several interesting scores:

  • Number of Ratings for all Versions
  • Average Rating for all Versions
  • Number of Ratings for the Current Version
  • Average Rating for for the Current Version

Short of seeing the actual sales figures, such numbers may be of some value in giving us a rough sense of how an App is doing - but only in a single Store; in order to get an overall sense of its success would require the tedious switching of Stores within iTunes.

However, with this plugin, this becomes much easier.

There are two ways to access the functionality: directly (via the two Services) or externally (via the restful interface). The two Services are AppReportCardService and ApiService; while AppReportCardService is the outer shell of the app, ApiService is a thin proxy to the iTunes API itself, so offers a lower level access, as well the complete representation of an app-in-store.

Here are the current use cases with examples on both types of access:

Get all of the Stores

Via Services

 List<Store> stores = appReportCardService.getAllStores()

Via Restful


View icon for single Store

Via Services


Via Restful


Search for Apps in a Store

Via Services

def maxResults = 100 // iTunes API Supports up to 200

List<StoreApp> matchingStoreApps = appReportCardService.findAppsByName(Store.UnitedKingdom,'Cats',maxResults)    

Via Restful

// Uses the max number of results (200)

Find a single App by ID in a Store

Via Services

StoreApp storeApp = appReportCardService.findAppById(Store.UnitedKindom, new AppId(542916632))

Via Restful

 /appReportCardRestful/stores     /GB/apps/542916632

Generate Report for an App in a single Store

Via Services

StoreAppReport storeAppReport = appReportCardService.generateStoreAppReport(Store.UnitedKindom,new AppId(542916632))

Via Restful


Generate Report Card for an App (across all Stores)

Please note that this is a multithreaded operation; even so, it may take up to a few seconds when uncached.

Via Services

AppReport appReport = 	appReportCardService.generateAppReport(new AppId(542916632))                 

Via Restful


As you can see in the ApiService there is declarative caching; however this plugin doesn't have any configuration for this, so it's up to your client; by default it uses an in-memory implementation with no expiration, so I'd recommend that you supply your own implementation.

Please refer to the documentation for the caching plugin.

Hope that you find this to be useful,

Sean Rasmussen