ireviews v2.3.1

iReviews

iTunes store customer reviews fetcher.

Known issue

It will happen that the number of reviews by country is different and it comes from Apple. Sometimes the request is OK (HTTP 200) with the first page of reviews but after an hour or a day the same request will return OK without reviews.

Features

• Use of events.
• Automatic validation of all parameters.
• Asynchronous reviews download.
• Parse XML to JSON.
• Choose a delay before each request.
• Choose between XML or JSON for the response format (there is an update date for all reviews in XML format).
• Return an enhance version of the structure (array of reviews).

Changes log

See changes log.

Contributors

See contributors.

License

See license.

Installation

$ npm install [--save] ireviews

Usage

var iReviews = require("ireviews");

var parameters = {
	store_id: "APPLICATION_ITUNES_STORE_ID",
	countries_code: [ "ALPHA_2_ISO_COUNTRY_CODE" ],
	delay: 100, // millisecond
	format: "json" // JSON format by default
};

var ireviews = new iReviews.Processor(parameters);

ireviews.storeId = "APPLICATION_ITUNES_STORE_ID";
ireviews.countriesCode = [ "ALPHA_2_ISO_COUNTRY_CODE" ];
ireviews.delay = 100;
ireviews.format = "xml";

// ============= WITHOUT EVENTS

ireviews.listAll(
	parameters, // not needed if already set before calling this method
	function (err, reviews) {
		if (err) return console.log(err);
			console.log(reviews);
	}
);

// ============= WITH EVENTS

ireviews.on("error", function (err) {
	console.log(err);
});

ireviews.on("end", function (reviews) {
	console.log(reviews);
});

ireviews.on("review", function (review) {
	console.log(review);
});

ireviews.parse(function (err) {
	if (err) console.log(err);
});

IMPORTANT :

• You can have an INVALID_PARAMETERS_ERROR when there is an issue with the parameters JSON.

Structure

• All reviews

[
	{
    	"count": 1,
        "countryCode": "US",
        "items": [
            {
                "id": "533332669",
                "title": "Help",
                "author": "DanBenedit1",
                "content": "I can't see my playlist after the update...",
                "rating": 1,
                "helpful_vote_count": 3,
                "total_vote_count": 3,
                "application_version": "1.1",
                "updated": 1330129380, // Only with response in XML format
                "country_code": "US"
            }
        ]
    }
]

• A review

{
	"id": "533332669",
    "title": "Help",
    "author": "DanBenedit1",
    "content": "I can't see my playlist after the update...",
    "rating": 1,
    "helpful_vote_count": 3,
    "total_vote_count": 3,
    "application_version": "1.1",
    "updated": 1330129380, // Only with response in XML format
    "country_code": "US"
}

Examples

I use the application MOVIST - Your Personal Movie List with 7 countries as example. You can run one of these commands :

• npm run-script movist-xml-stream
• npm run-script movist-delay-xml-stream
• npm run-script movist-xml
• npm run-script movist-delay-xml
• npm run-script movist-json-stream
• npm run-script movist-delay-json-stream
• npm run-script movist-json
• npm run-script movist-delay-json

API

Class

Class: Processor(options)

• options : object with following parameters

{
	"store_id": "",
    "countries_code": [],
    "delay": 1000,
    "format": "json"
}

Class: InvalidParametersError(message, parameters)

Useful when you need to verify if the returned error have an InvalidParametersError type.

• message : error message
• parameters : add data to the error instance

Methods

Method: listAll(parameters, callback)

Start downloading and processing all reviews.

• parameters : object with following parameters

{
	"store_id": "",
    "countries_code": []
}

• callback : function called if an error occured or all reviews have been downloaded and processed

ireviews.listAll(function (err, reviews) {
	if (err) return console.log(err);
    console.log(reviews);
});

Method: parse(callback)

Start downloading and processing all reviews and emit following events.

• callback : function called if an error occured or not

ireviews.parse();

ireviews.parse(function (err) {
	if (err) console.log(err);
});

Events

Event: error

Emitted if an error occured.

ireviews.on("error", function (err) {
	console.log(err);
});

Event: end

Emitted when all reviews have been downloaded and processed.

ireviews.on("end", function (reviews) {
	console.log(reviews);
});

Event: review

Emitted on every review processed.

ireviews.on("review", function (review) {
	console.log(review);
});