JSON Display API

The public JSON Display API allow you to access review and Q&A data in order to customize the look and feel of your integration.

Different Types of Product Reviews

TestFreaks handles three different types of product reviews: expert reviews, user reviews, and customer reviews.

The types differ in how and from where the reviews have been collected.

• Expert Reviews - Reviews written by professional reviewers, usually specialized on certain categories, about a specific product
• User Reviews - Reviews written by people in general about a specific product
• Customer Reviews - Reviews written by your own customers about a specific product

Depending on your setup not all types may be available.

Expert reviews and user reviews are together referred to as external reviews since they come from external sources, not your own customers.

Review Summary

The API takes your product ID and/or family ID and returns a JSON response with review information (the number of available reviews, combined score, and pros & cons) and the location of the review data.

It also contains a separate average score from your customer reviews and the location of a write review page where users can submit new reviews for this product.

https://js.testfreaks.com/onpage/your.client.id/reviews.json?key=productid&url_key=familyid

The your.client.id part should be replaced with one of your assigned client IDs.

Example response:

{
  "score": 7.9,
  "pro_score_dist_all": [1,7,11,56,24],
  "user_score_dist_all": [57,19,151,473,301],
  "product_pros": ["pro1", "pro2"],
  "product_cons": ["con1"],
  "pro_review_count": 99,
  "pro_review_url": "<url>",
  "user_review_count": 1001,
  "user_review_url": "<url>",
  "your_review_count": 5,
  "your_review_url": "<url>",
  "your_avg_score": 4.4,
  "your_score_dist": [0,0,1,1,3],
  "write_review_url": "<url>",
  "your_question_count": 7,
  "your_question_url": "<url>",
  "your_review_answers": [
    {
      "name": "fit3",
      "type": "select",
      "count": 17,
      "options": [
        {
          "value": "small",
          "count": 2
        },
        {
          "value": "normal",
          "count": 15
        },
        {
          "value": "large",
          "count": 0
        }
      ]
    }
  ]
}

Your Review Answers

The your_review_answers section is present when the result contains customer reviews with answers to custom questions.

JSONP Callback

A callback parameter can be added for a padded JSON (JSONP) response suitable for JavaScript integration:

https://js.testfreaks.com/onpage/your.client.id/reviews.json?key=yourproductid&callback=functionName

Page Size

By default the review URLs point to the first 10 reviews of each type and return the location of the next 10 reviews after that.

This page size can be customized with the limit parameter and can either be a single number (1-30) or a list of numbers for different page sizes between the first and following pages. For example:

limit=5
limit=5,10

Language Selection

The language of the external reviews (expert reviews and user reviews) to be shown are preconfigured for your.client.id. It can optionally be overridden by the lang parameter.

If a single language code (ISO 639-1) is specified then only reviews in that language will be returned. If a list of language codes, then reviews are returned in that order. For example:

lang=en
lang=sv,en

A wildcard can be used in place of all remaining languages:

lang=sv,en,*

Sorting

By default the review URLs return reviews sorted by relevance.

• For customer reviews this promotes recent helpful reviews (as determined by up/down votes).
• For external reviews (expert reviews and user reviews) this promotes helpful reviews with full content and from a mix of different sources.

The sort parameter can be used to change to a strict date sorting (most recent first):

sort=date

You may optionally include a sort parameter for relevance sorting even though this is the default:

sort=relevance

Sorting Customer Reviews

For customer reviews, there are three additional sort options available.

To change to a reverse strict date sorting (oldest first):

sort=date:asc

To sort by rating with the highest score first:

sort=score

To sort by reverse rating with the lowest score first:

sort=score:asc

This parameter can also be added directly to the customer review URL (your_review_url).

Note: The sort options date:asc, score, and score:asc can only be used to sort customer reviews.

Expert reviews and user reviews will be sorted according to the default (relevance).

Grouping

Reviews will by default be grouped according to the language, regardless of sort order.

For example, all reviews in the local language will appear before reviews in other languages. Each group will typically contain reviews in a single language sorted according to the sort settings.

Grouping of External Reviews

Grouping of external reviews (expert reviews and user reviews) is handled by the lang parameter as described in Language Selection.

Grouping of Customer Reviews

Grouping of customer reviews can be disabled using the sections parameter.

All customer reviews will be sorted as a single group, typically mixing multiple languages together:

sections=0

This parameter can also be added directly to the customer review URL (your_review_url).

Note: The sections parameter only affects customer reviews.

It has no effect on external reviews (expert reviews and user reviews).

Review Data

The review URLs (pro_review_url for expert reviews, user_review_url for user reviews, and your_review_url for your customer reviews) are API locations of review data in JSON (or JSONP if a callback parameter is added).

Example response from user_review_url:

{
  "reviews": [
    {
      "type": "user",
      "title": "Great product",
      "source": "A Review Site",
      "domain": "reviewsite.example",
      "product": "ACME Product ABC123",
      "author": "John Doe",
      "date": "2020-01-30",
      "country": "us",
      "lang": "en",
      "score": 8,
      "score_max": 10,
      "extract": "I really like the ACME ABC123.",
      "pros": "Very durable and long battery life.",
      "cons": "A bit expensive.",
      "votes_up": 13,
      "votes_down": 1,
      "feedback_url": "<url>",
      "logo": "<url>",
      "logo_width": 110,
      "logo_height": 60,
      "icon": "<url>",
      "icon_width": 80,
      "icon_height": 80,
      "link": "<url>"
    }
  ],
  "next_page_url": "<url>"
}

Example response from your_review_url:

{
  "reviews": [
    {
      "type": "customer",
      "product": "ACME Product ABC123",
      "product_id": "P001-02-BLK",
      "author": "John D",
      "date": "2020-01-30",
      "lang": "en",
      "verified_buyer": true,
      "score": 5,
      "score_max": 5,
      "extract": "I really like the ACME ABC123.",
      "pros": "Very durable, Long battery life",
      "cons": "A bit expensive",
      "votes_up": 9,
      "votes_down": 0,
      "feedback_url": "<url>",
      "images": [
        {
          "icon": "<url>",
          "icon_width": 100,
          "icon_height": 100,
          "medium": "<url>",
          "medium_width": 1600,
          "medium_height": 900,
          "large": "<url>",
          "large_width": 3840,
          "large_height": 2160
        }
      ],
      "responses": [
        {
          "response": "Glad you liked it!",
          "name": "Jane, Customer Support",
          "date": "2020-02-01",
          "icon": "<url>",
          "icon_width": 80,
          "icon_height": 80
        }
      ],
      "question_answers": [
        {
          "name": "fit3",
          "type": "select",
          "options": [
            {"value": "small"},
            {"value": "normal", "selected": true},
            {"value": "large"}
          ]
        }
      ],
      "original": {
        "lang": "sv",
        "extract": "Jag gillar verkligen ACME ABC123.",
        "pros": "Väldigt hållbar, Lång batteritid",
        "cons": "Något dyr"
      }
    }
  ],
  "next_page_url": "<url>"
}

Depending on the source and type of review any of these properties may be omitted.

The next_page_url contains the API location for the next page of reviews, if available.

Images

Responses

Custom Questions

Original

The original section contains details about the original review when a review has been translated.

Score Filter

A score_dist parameter can be added to the review URLs (pro_review_url, user_review_url, your_review_url) in order to only return reviews within a specific score distribution.

The parameter value (1-5) corresponds to the five distribution brackets from the lowest to the highest scores. For example:

score_dist=5

Filter Customer Reviews with Images

An only_with_images parameter can be added to the customer review URL (your_review_url) in order to only return reviews that have at least one submitted image:

only_with_images=1

Note: The only_with_images parameter only affects customer reviews.

It has no effect on expert reviews and user reviews.

Q&A Data

The questions and answers URL (your_question_url) contains the API location for the first page of Q&A data in JSON. For example:

{
  "questions": [
    {
      "product": "ACME Product ABC123",
      "author": "John D",
      "date": "2020-01-30",
      "country": "us",
      "lang": "en",
      "title": "Fits the ABC124?",
      "extract": "Does it work together with the ABC124?",
      "votes_up": 30,
      "votes_down": 5,
      "feedback_url": "<url>",
      "responses": [
        {
          "response": "Yes, the ACME ABC123 and ABC124 work perfectly together!",
          "name": "Jane, Customer Support",
          "date": "2020-02-01"
        }
      ]
    }
  ],
  "next_page_url": "<url>"
}

The next_page_url contains the API location for the next page of questions, if available.