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.

Note: Calling the Review Summary API for multiple different products on a single page, for example a category page, can have performance implications.

Please reach out to TestFreaks to discuss different options.

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
        }
      ]
    }
  ]
}
Attribute Description
score Combined score based on all reviews in all languages (1-10)
pro_score_dist_all Number of expert reviews with score 1-2, 3-4 etc. This includes all available reviews in all languages and from all sources, regardless of what is actually displayed. (score filter)
user_score_dist_all Number of user reviews with score 1-2, 3-4 etc. This includes all available reviews in all languages and from all sources, regardless of what is actually displayed.(score filter)
product_pros Variable number of common pros
product_cons Variable number of common cons
pro_review_count Number of visible expert reviews. This is typically different from pro_score_dist_all because of language and source selection in the client configuration.
pro_review_url API location of the first page of expert reviews (if available)
user_review_count Number of visible user reviews. This is typically different from user_score_dist_all because of language and source selection in the client configuration.
user_review_url API location of the first page of user reviews (if available)
your_review_count Number of visible customer reviews
your_review_url API location of the first page of customer reviews (if available)
your_avg_score Average customer review score (1-5)
your_score_dist Number of visible customer reviews in each score bracket (1-5). (score filter)
write_review_url Location of write review form
your_question_count Number of visible questions with answers
your_question_url API location of the first page of questions and answers

Your Review Answers

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

your_review_answers List of answer summaries for the custom questions present in the result
your_review_answers.name Custom question identifier
your_review_answers.type Custom question type
your_review_answers.count The total number of answers to this question
your_review_answers.options List of option summaries, for select type questions.
your_review_answers.options.value Custom question answer identifier
your_review_answers.options.count The number answers selecting this option

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>"
}
type Review type (pro for an expert review, user for a user review, or customer for a customer review)
title Review title
source Review source name
domain Review source domain
product Review source’s product name
product_id Your product ID. Available for customer reviews.
author Author name
date Date when the review was published
country Country code
lang Language code
verified_buyer true if the review is from a verified buyer
score Review score
score_max Maximum review score. 10 for external reviews (expert reviews and user reviews). 5 for customer reviews.
extract Extract of the main review text. For your customer reviews the field will contain the full review text. The text never contains valid HTML, but may include newline characters (\n) if the review has multiple paragraphs.
pros “Pro” content for reviews with pros & cons
cons “Con” content for reviews with pros & cons
votes_up Number of helpful votes
votes_down Number of not helpful votes
feedback_url Location of the JSON Collect API for submitting feedback
logo Review source logo with rectangular bounding box
logo_width Logo width (<= 110)
logo_height Logo height (<= 60)
icon Review source logo with square bounding box
icon_width Icon width (<= 80)
icon_height Icon height (<= 80)
link Link to the original review

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

images Images submitted with the review
images.icon Link to the image cropped to fit inside a 100x100 pixel square
images.icon_width Icon image width
images.icon_height Icon image height
images.medium Link to the image scaled to 1.5 megapixels or less
images.medium_width Medium image width
images.medium_height Medium image height
images.large Link to the image scaled to 8.3 megapixels or less
images.large_width Large image width
images.large_height Large image height

Responses

responses Responses to the review. Typically the single response maintained in the portal.
responses.response Response text
responses.name Name of the responding person, as configured in the portal.
responses.date Date of the response
responses.icon Link to a 80x80 pixel profile image
responses.icon_width Icon image width
responses.icon_height Icon image height

Custom Questions

question_answers List of answers to (visible) custom questions
question_answers.name Custom question identifier
question_answers.type Custom question type
question_answers.options List of select options, for select type questions.
question_answers.options.value Custom question answer identifier
question_answers.options.selected true for the option(s) selected for this review

Original

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

original.lang Original langage code
original.extract Original main review text
original.pros Original “Pro” content
original.cons Original “Con” content

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>"
}
product Product name
author Author name
date Date when the question was published
country Country code
lang Langauge code
title Question title (required)
extract Question body (optional)
votes_up Number of helpful votes
votes_down Number of not helpful votes
feedback_url Location of the JSON Collect API for submitting feedback
responses Answers to the question. Typically the single answer maintained in the portal. See responses for more details.

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