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.
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. This includes expert reviews, user reviews, and customer reviews unless limited by your setup.
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 (a decimal number between 1.0–10.0) |
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 (a decimal number between 1.0–5.0) |
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 |
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 |
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
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
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,*
By default the review URLs return reviews sorted by relevance. This varies depending on the review type.
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
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
optionsdate:asc
,score
, andscore:asc
can only be used to sort customer reviews.Expert reviews and user reviews will be sorted according to the default (relevance).
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 (expert reviews and user reviews) is handled by the lang
parameter as described in Language Selection.
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).
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": "https://api.testfreaks.example/reviews/page/2"
}
Example response from your_review_url
:
{
"reviews": [
{
"type": "customer",
"source": "Your Site Name",
"domain": "yoursite.example",
"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": "https://api.testfreaks.example/reviews/page/2"
}
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. Intended for displaying alongside the review. |
domain | Review source domain. Indented for displaying alongside the review but not for linking. Sometimes the domain includes a path or subdomain - like example.com/en or us.example.com . |
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 (a decimal number between 1.0–10.0 for expert reviews and user reviews, or an integer between 1–5 for customer reviews) |
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 (\r and \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
field contains the URL for the next page of reviews, if available.
Note: Treat this URL as an opaque string. Do not modify or parse it. The format may change without notice.
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 to the review. Typically the single response maintained in the portal. |
responses.response | Response text. The text never contains valid HTML, but may include newline characters (\r and \n ) if the response has multiple paragraphs. |
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 |
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 |
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. The text never contains valid HTML, but may include newline characters (\r and \n ) if the original review has multiple paragraphs. |
original.pros | Original “Pro” content |
original.cons | Original “Con” content |
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
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.
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": "https://api.testfreaks.example/questions/page/2"
}
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
field contains the URL for the next page of questions, if available.
Note: Treat this URL as an opaque string. Do not modify or parse it. The format may change without notice.