itunesconnect is node.js module wrapping iTunes Connect Reporting API. It allows to query sales/downloads reports in super easy way.
$ npm install itunesconnect
If you want to have and access to comman-line tool itcreport install itunesconnect globally. See more info about itcreport.
$ npm install itunesconnect -g
$ itcreport --help
There are 2 different report types, ranked and timed.
Ranked report is sorted by number of downloads and it can be filtered and grouped by one of the constants. Ranked report result contains just a number of sales and/or proceeds regardless of time frame. Ranked is also ignoring interval option. Good use case for ranked report is to get summary of sales and/or proceeds in some time period. You can also use filters and group to make your query more advanced.
Timed report result is a little bit more detailed. It's not sorted by number of sales or proceeds. It's embedding objects with number of sales grouped by interval option. You should understand it more looking at the examples below.
It's hard to fuly understand Apple API without documentation so my description might have some errors. I strongly recommend to play with queries and results and try to understand different types. If you also want to improove description feel free to do so.
This example shows how to fetch ranked report data from last 10 days and timed report from last 3 weeks with week interval.
Query:
var itc = require("itunesconnect");
var Report = itc.Report;
// Connect to iTunes
var itunes = new itc.Connect('apple@id.com', 'password');
// Simple ranked report
itunes.request(Report.ranked().time(10, 'days'), function(error, result) {
console.log(result);
});
// Or
itunes.request(Report('timed').time(3, 'weeks').interval('week'), function(error, result) {
console.log(result);
});Result (ranked):
[
{
"key": 0,
"title": "App Name ",
"rptgDesc": "App",
"contentSpecificTypeId": 1,
"contentSpecificTypeName": "iOS App",
"contentGrpCd": "Apps",
"contentProviderId": 0,
"artistName": "Artist Name",
"contentProviderName": "Provider Name",
"units": 7684
},
{
"key": 0,
"title": "In App Name ...",
"rptgDesc": "In App",
"contentSpecificTypeId": 3,
"contentSpecificTypeName": "Auto-Renewable Subscription",
"contentGrpCd": "Apps",
"contentProviderId": 0,
"contentProviderName": "Provider Name",
"units": 2886
}
...
]Result (timed):
Default group for timed report is null so it contains just all downloads.
[
{
"data": [
{
"date": "2014-07-14T00:00:00.000Z",
"units": 1234567
},
{
"date": "2014-07-21T00:00:00.000Z",
"units": 2345
},
{
"date": "2014-07-28T00:00:00.000Z",
"units": 987
},
{
"date": "2014-08-04T00:00:00.000Z",
"units": 456789
}
]
}
]Query (timed) grouped by location:
var itc = require("itunesconnect");
var Report = itc.Report;
// Connect to iTunes
var itunes = new itc.Connect('apple@id.com', 'password');
// Or
itunes.request(Report('timed').time(3, 'weeks').interval('week').group('location'), function(error, result) {
console.log(result);
});Result (timed) grouped by location:
[
{
"metadata": {
"key": "143461",
"title": "New Zealand",
"parent_key": "-100004"
},
"data": [
{
"date": "2014-07-14T00:00:00.000Z",
"units": 3
},
{
"date": "2014-07-28T00:00:00.000Z",
"units": 2
}
]
},
{
"metadata": {
"key": "143465",
"title": "China",
"parent_key": "-100004"
},
"data": [
{
"date": "2014-07-14T00:00:00.000Z",
"units": 9
},
{
"date": "2014-07-21T00:00:00.000Z",
"units": 18
},
{
"date": "2014-07-28T00:00:00.000Z",
"units": 15
},
{
"date": "2014-08-04T00:00:00.000Z",
"units": 7
}
]
},
...
]This example shows how to fetch ranked report data from last 2 days, both app sales and in-app sales with one of provided categories, grouped by content and returning both sales and proceeds (Moooooooooney).
Please note that limit property apply just to ranked reports
var itc = require("itunesconnect");
var Report = itc.Report;
// Connect to iTunes
var itunes = new itc.Connect('apple@id.com', 'password');
// More complex query
var query = Report('ranked', {
limit : 100,
filters : {
type: [
itc.type.inapp,
itc.type.app
],
category: [6001,6002,6003]
},
group: 'content', // content is default group for ranked report so you dont have to use it here
measures: [itc.measure.units, itc.measure.proceeds]
}).time(2, 'days');
itunes.request(query, function(error, result) {
console.log(result);
});Same query in chainable way
var query = Report
.ranked()
.time(2,'days')
.limit(100)
.category([6001,6002,6003])
.group('content')
.type([itc.type.inapp, itc.type.app])
.measures( [itc.measure.units, itc.measure.proceeds]);Please also reffer to Connect class docs.
Connect(<username>, <password>, [options])
Available options:
options.concurrentRequests = Number
options.errorCallback = Function //function(error) {}
options.loginCallback = Function //function(cookies) {}
options.cookies = ArrayIf you want to cache login cookies use loginCallback and set cookies option
Please note that cookies have expiration date
var itc = require("itunesconnect");
var options = {
loginCallback: function(cookies) {
redis.set("cache-cookies", cookies);
}
}
redis.get("cache-cookies", function (err, cookies) {
if(!err) options.cookies = cookies;
});
// Connect to iTunes
var itunes = new itc.Connect('apple@id.com', 'password', options);Please also reffer to Query class docs.
To create new Query class instance please use Report helper functions.
Report(<type>, [config])
Report.ranked([config])
Report.timed([config])
Config Object:
config.start = String|Date // (Date or if String must be in format YYYY-MM-DD)
config.end = String|Date // (Date or if String must be in format YYYY-MM-DD)
config.interval = String // (Available values: day,week,month,quarter,year)
config.filters.content = Number|Array // (Content ID / Application ID)
config.filters.type = String|Array // (Please refer to constants below)
config.filters.transaction = String|Array // (Please refer to constants below)
config.filters.category = Number|Array // (Visit Cheet-Sheet#categories for available options)
config.filters.platform = String|Array // (Please refer to constants below)
config.filters.location = Number|Array // (Visit Cheet-Sheet#countries for available options)
config.group = String // (Available values: content,type,transaction,category,platform,location)
config.measures = Array // (Please refer to constants below)
config.limit = Number// Import itunesconnect
var itc = require("itunesconnect"),
// Types
itc.type.inapp
itc.type.app
// Transactions
itc.transaction.free
itc.transaction.paid
itc.transaction.redownload
itc.transaction.update
itc.transaction.refund
// Platforms
itc.platform.desktop
itc.platform.iphone
itc.platform.ipad
itc.platform.ipod
// Measures
itc.measure.proceeds
itc.measure.unitsExample:
// Start and end date set manualy
query.date('2014-04-08', new Date());
// Start and end date will be todays date
query.date(new Date());
// Start and end date will be set as 8th of April 2014
query.date('2014-04-08');
// End date will be set as 8th of April 2014 and start as 8th of Jan 2014
query.date('2014-04-08').time('3', 'months');// Start date will be set to 10 weeks from today
query.time(10, 'weeks');
// End date will be set as 8th of April 2014 and start as 8th of Jan 2014
query.date('2014-04-08').time('3', 'months');Available options:
- content
- type
- transaction
- category
- platform
- location
Ranked report default is content. Timed report default is null
query.group('transaction');Available options:
- day
- week
- month
- quarter
- year
Ranked report is ignoring this.
query.interval('day');Ranked report default is 100. Timed report is ignoring this.
query.limit(100);See Constants for available options
query.measures(itc.measure.units);
query.measures([itc.measure.units, itc.measure.proceeds]);All filter methods take one parameter Value or Array of Values
Content is taking Number or Array of Number (Application ID).
query.content(1);
query.content([1, 2]);
query.content([1, 2]).content(3);Visit Categories Cheet-Sheet wiki page for available options
query.category(6001);
query.category([6002, 6003]);
query.category([6001, 6002]).category(6003);Visit Locations Cheet-Sheet wiki page for available options
query.location(6001);
query.location([6002, 6003]);
query.location([6001, 6002]).location(6003);See Constants for available options
query.platform(itc.platform.desktop);
query.platform([itc.platform.desktop, itc.platform.ipad]).platform(itc.platform.ipod);See Constants for available options
query.transaction(itc.transaction.free);
query.transaction([itc.transaction.free, itc.transaction.paid]).transaction(itc.transaction.refund);See Constants for available options
query.type(itc.type.app);
query.type([itc.type.inapp, itc.type.app]);Command-Line tool to get report results from console. It can output result to console or to to json file.
I strongly recommend to put username and password in config file so its not in bash history
$ itcreport --help
Usage: itcreport [options] [command]
Commands:
create-config <filename>
Creates new config file <filename>
ranked [options]
Ranked report
timed [options]
Timed report
Options:
-h, --help output usage information
-V, --version output the version number
-c, --config <filename> Specify config file
-h, --cachetime <seconds> Specify cache time for session cookies. Defaulting to 1800.
-f, --forcelogin Will ignore cached cookies and re-login.
-u, --username <username> iTunes Connect Username (Apple ID)
-p, --password <password> iTunes Connect Password
-s, --since <since> Specify since date. You can use format YYYY-MM-DD or simply 1day ...
-d, --date <date> Specify date (YYYY-MM-DD) Defaulting to today.
-g, --group <group> Group results by one of the following:
-A, --content <contentid> Filter by Content ID. [Repeatable value]
-L, --location <location> Filter by Location. Visit (...) for available options. [Repeatable value]
-C, --category <category> Filter by Category. Visit (...) for available options. [Repeatable value]
-P, --platform <platform> Filter by Platform. [Repeatable value]
-T, --transaction <transaction> Filter by Transaction Type. [Repeatable value]
-t, --type Filter by Content Type. [Repeatable value]
-M, --measure <measure> Result measures (units, proceeds). Defaulting to units. [Repeatable value]
-o, --outputfile <filename> Output file name. Will be saved as json.
Some examples ...
$ itcreport create-config sample.json
$ itcreport timed -c sample.json --since 1week
$ itcreport timed -c sample.json --since 1week -C 6001 -C 6002
$ itcreport timed -c sample.json --date 2014-01-01
Same story as for constants
// Types
inapp
app
// Transactions
free
paid
redownload
update
refund
// Platforms
desktop
iphone
ipad
ipod
// Measures
proceeds
units$ itcreport timed -c sample.json --date 2014-01-01 --platform desktop --platform ipad
- Better tests
- More examples
(The MIT License)
Copyright (c) 2014 Marek Serafin, itunesconnect module creator
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.