GoodBed Reviews API
Syndicating GoodBed Product & Store Reviews

GoodBed's API allows manufacturers and retailers to receive an automatically updated feed of structured data containing reviews of specific products or stores that were collected through GoodBed's review platform. With GoodBed's approval, such reviews can be displayed on your website.

This article walks through some FAQ's about the GoodBed Reviews API.

 

UPDATE: Full API Documentation Here is a link to GoodBed's full API documentation, which contains the most comprehensive and up-to-date details on all requests, parameters, and responses: https://www.goodbed.com/api/docs/

 

1. Getting started

Here are the first few things you'll need to know to use this REST API.

API Key

Before you can access your reviews API feed, you'll need an API Key, provided by GoodBed. Keep this key somewhere secure. If you lose it, we'll need to generate a new key for you. When you make an API request, you'll put the key in the request header like this: GB-API-KEY: YOUR API KEY

JSON

The file format of the API results is JSON. For more info about working with JSON files check this: https://www.json.org/json-en.html

 

2. Description of fields in API results

The GoodBed Reviews API contains two types of fields.

Hypermedia fields (used to dynamically navigate the API):

• count: How many total reviews match this query
• next: Next page to access more reviews
• previous: Previous page to access more reviews
• results: Returns a list of all the reviews, each with their own data

Data fields (containing the available information for each review):

• link: URL of the API endpoint for this specific review
• adjusted_average_rating: Age-weighted average of all ratings for this product or store
• review_count: Total number of published reviews for this product or store (note: a "review" contain both a rating and written content)
• rating_count: Total number of published ratings for this product or store
• review_url: URL of the published web page that is dedicated to this specific review
• author: General information about the person that posted this review
  • profile: Displayed information about the person that posted this review
    • short_name: Display version of reviewer's name (eg, John D)
    • home_city: Location of the person that posted this review (City, ST)
• rating: Star rating (1-5)
• title: Review title
• text: Review text
• date_reviewed: Date this review was posted
• comment_count: Number of comments on this review
• comments: Displayed information about the comments on this review
  • comment: Text of the comment
  • user_name: Display version of commenter's name
  • submit_date: Date this comment was posted
  • is_official: Whether this comment was posted by an official representative of the company being reviewed

 

3. How to make an API request

For security purposes, GoodBed's REST API only intended to be consumed from the backend, rather than directly from the browser. This means that CORS (Cross Origin Resource Sharing) requests are not allowed, so this API can not be accessed using Javascript (eg, AJAX).

Below are the instructions for how to make an API request. Note that all URL's shown in this section should begin with our primary domain (https://www.goodbed.com). So, before using any of the URL's below, be sure to replace "{GoodBed Domain}" with "https://www.goodbed.com". In order to avert computer-generated spam, this article avoids writing these as complete URL's.

Read on for more specific instructions relating to requesting product reviews or store reviews.

 

3.1. General instructions

These instructions apply to requests for both product reviews and store reviews.

3.1.1. Here is the base URL for all API requests:

{GoodBed Domain}/api/v1/partners/

 

3.1.2. To confirm what kind of reviews (product, store, or both) are associated with your API Key, use your key to perform a GET request to this URL:

{GoodBed Domain}/api/v1/partners/

 

Sample response:

{
  "reviews": "{GoodBed Domain}/api/v1/partners/reviews/",
  "store_reviews": "{GoodBed Domain}/api/v1/partners/store-reviews/"
}

 

3.2. Requesting store information

These instructions apply to requests for information about either retailers or store locations.

3.2.1. To get a list of retailers associated with your API Key, use your key to perform a GET request to this URL:

{GoodBed Domain}/api/v1/partners/stores/retailer/

 

Response structure:

{
   "count": number,
   "next": string | null,
   "previous": string | null,
   "results": [
      {
        'shopper_rating': number | null,
        'adjusted_average_rating': number | null,
        'name': string,
        'slug': string,
        'review_count': number,
        'rating_count': number
       },
      {...}
   ]
}

 

3.2.2. To get general information about a specific retailer, use the appropriate URL for that retailer:

{GoodBed Domain}/api/v1/partners/stores/retailer/{retailer-slug}/

Sample:

{GoodBed Domain}/api/v1/partners/stores/retailer/sample-retailer/

 

Response structure:

{
  'shopper_rating': number | null,
  'adjusted_average_rating': number | null,
  'name': string,
  'slug': string,
  'review_count': number,
  'rating_count': number
}

 

3.2.3. To get a list of store locations associated with your API Key, use your key to perform a GET request to this URL:

{GoodBed Domain}/api/v1/partners/stores/store/

 

Response structure:

{
   "count": number,
   "next": string | null,
   "previous": string | null,
   "results": [
      {
        'shopper_rating': number | null,
        'adjusted_average_rating': number | null,
        'store_location': string,
        'slug': string,
        'review_count': number,
        'rating_count': number
       },
      {...}
   ]
}

 

3.2.4. To get general information about a specific store location, use the appropriate URL for that store location:

{GoodBed Domain}/api/v1/partners/stores/store/{location-slug}/

Sample:

{GoodBed Domain}/api/v1/partners/stores/store/sample-retailer-portland-or-96502/

 

Response structure:

{
  'shopper_rating': number | null,
  'adjusted_average_rating': number | null,
  'store_location': string,
  'slug': string,
  'review_count': number,
  'rating_count': number
}

 

3.3. Requesting product reviews

Your key may contain access to multiple Product Review Feeds. Each Product Review Feed shows reviews for a particular manufacturer, line, collection, or model. To get a list of reviews for a specific product, follow the URL specified for that particular Product Review Feed (more on this in Section 3.3.2 below).

3.3.1. To get a list of the Product Review Feed URL's that are associated with your key, use your key to make a GET request to this URL:

{GoodBed Domain}/api/v1/partners/reviews/products/

 

Sample response:

{
   "count": 2,
   "next": null,
   "previous": null,
   "results": [
{
   "Acme Original": "{GoodBed Domain}/api/v1/partners/reviews/products/model/the-acme-bed/"
       }
   },
   "Acme Hybrid": "{GoodBed Domain}/api/v1/partners/reviews/products/line/acme-hybrid/"
}
  ]
}

 

3.3.2. To display all the product reviews for a given product, use the appropriate Product Review Feed URL.

Product Review Feeds can be requested at any level of the GoodBed product hierarchy: manufacturer > line > collection > model.

• To request all product reviews for an entire manufacturer, use the 'manufacturer' directory followed by the unique slug for that manufacturer.
• For all product reviews associated with a given product line, use the 'line' directory followed by the unique slug for that product line.
• For all product reviews associated with a given collection, use the 'collection' directory followed by the unique slug for that collection.
• For all product reviews associated with a specific model, use the 'model' directory followed by the unique slug for that model.

Note that you will see a max of 25 reviews per page.

Sample:

This request would show all product reviews associated with the product line whose unique slug is 'acme-hybrid':

{GoodBed Domain}/api/v1/partners/reviews/products/line/acme-hybrid/

 

Sample response:

{
    "count": 355,
    "next": "{GoodBed Domain}/api/v1/partners/reviews/?page=2",
    "previous": null,
    "results": [
{
   "link": "{GoodBed Domain}/api/v1/partners/reviews/436518/",
   "product_url": "{GoodBed Domain}/mattress-model/acme-hybrid-yorkshire-firm-euro-top/",
   "author": {
       "profile": {
           "short_name": "Rick C",
           "home_city": "Parson, MS"}
       }
   },
   "brand_name": "Acme",
   "mattress_name": "Acme Hybrid Yorkshire Firm Euro Top",
   "rating": 5,
   "title": "It's awesome",
   "text": "It's better than I could imagine. My wife and I have loved this mattress from the very start.",
   "pros": "Really comfortable and supportive",
   "cons": "I have a hard time getting out of it",
   "date_reviewed": "2020-02-29T18:28:22.311572",
   "comment_count": 0
}
  ]
}

 

3.3.3. To display a specific product review, use this URL structure, inserting the ID of the review you want to display:

{GoodBed Domain}/api/v1/partners/reviews/{reviewid}/

Sample:

{GoodBed Domain}/api/v1/partners/reviews/436518/

 

Sample response:

{
   "link": "{GoodBed Domain}/api/v1/partners/reviews/436518/",
   "product_url": "{GoodBed Domain}/mattress-model/acme-hybrid-yorkshire-firm-euro-top/",
   "author": {
       "profile": {
           "short_name": "Rick C",
           "home_city": "Parson, MS"}
       }
   },
   "brand_name": "Acme",
   "mattress_name": "Acme Hybrid Yorkshire Firm Euro Top",
   "rating": 5,
   "title": "It's awesome",
   "text": "It's better than I could imagine. My wife and I have loved this mattress from the very start.",
   "pros": "Really comfortable and supportive",
   "cons": "I have a hard time getting out of it",
   "date_reviewed": "2020-02-29T18:28:22.311572",
   "comment_count": 0
}

 

3.4. Requesting store reviews

Your key may contain access to multiple Store Review Feeds. Each Store Review Feed shows reviews that are associated with a particular retailer or store location. To get a list of reviews for a specific retailer or location, use the URL specified for that particular Store Review Feed (more on this in Section 3.4.2 below).

3.4.1. To get a list of the Store Review Feed URL's that are associated with your key, use your key to make a GET request to this URL:

{GoodBed Domain}/api/v1/partners/store-reviews/stores/

 

Sample response:

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "Sample Retailer": "{GoodBed Domain}/api/v1/partners/store-reviews/stores/retailer/sample-retailer/"
}
  ]
}

 

3.4.2. To display all the store reviews for a given retailer or store location, use the appropriate Store Review Feed URL.

Store Review Feeds can be requested at any level of the GoodBed store hierarchy: retailer > store.

• To request all store reviews for an entire retailer, use the 'retailer' directory followed by the unique slug for that retailer.
• For all store reviews associated with a specific store location, use the 'store' directory followed by the unique slug for that store location.

Note that you will see a max of 25 reviews per page.

Sample:

This request would show all store reviews associated with the retailer whose unique slug is 'sample-retailer':

{GoodBed Domain}/api/v1/partners/store-reviews/stores/retailer/sample-retailer/

 

Sample response:

{
  "count": 253,
  "next": "{GoodBed Domain}/api/v1/partners/store-reviews/?page=2",
  "previous": null,
  "results": [
    {
      "link": "{GoodBed Domain}/api/v1/partners/store-reviews/7234/",
      "shopper_rating": 82,
      "store_url": "{GoodBed Domain}/mattress-store/sample-retailer-portland-or-96502/",
      "review_url": "{GoodBed Domain}/mattress-store-review/sample-retailer-portland-or-96502/7234/",
      "store_location": "1370 Plaza Blvd, Portland, OR 96502",
      "retailer_name": "Sample Retailer",
      "author": {
          "profile": {
              "short_name": "Randy",
              "home_city": "Montague, OR"}
          }
      },
      "rating": 4,
      "title": "Great quick friendly service",
      "text": "I went looking for a mattress for our master bedroom. Jeff properly introduced himself, asked what I needed, and was able to quickly help me find a great mattress. He was very friendly, courteous, and had a neat personality. It was an excellent experience.",
      "date_reviewed": "2020-07-15T22:00:17.703945",
      "comment_count": 1,
      "comments": [
          {
              "is_official": true,
              "comment": "Thanks for the great feedback, Randy!",
              "user_name": "Brett",
              "submit_date": "2020-07-16T08:10:11.132919",
           }
       ]
   },
   {
      "link": "{GoodBed Domain}/api/v1/partners/store-reviews/7571/",
      "shopper_rating": 82,
      "store_url": "{GoodBed Domain}/mattress-store/sample-retailer-anytown-ca-94804/",
      "review_url": "{GoodBed Domain}/mattress-store-review/sample-retailer-anytown-ca-94804/7571/",
      "store_location": "2820 Joseph Boulevard, Anytown, CA 94804",
      "retailer_name": "Sample Retailer",
      "author": {
          "profile": {
              "short_name": "Dan",
              "home_city": "Springfield, CA"}
          }
      },
      "rating": 4,
      "title": "Good Experience",
      "text": "Salesperson had a good knowledge of the product. Very patient in assisting us with options and final selection.",
      "date_reviewed": "2020-07-08T11:23:01.070384",
      "comment_count": 0
}
  ]
}

 

3.4.3. To display a specific store review, use this URL structure, inserting the ID of the review you want to display:

{GoodBed Domain}/api/v1/partners/store-reviews/{reviewid}/

Sample:

{GoodBed Domain}/api/v1/partners/store-reviews/7234/

 

Sample response:

{
   "link": "{GoodBed Domain}/api/v1/partners/store-reviews/7234/",
   "shopper_rating": 82,
   "store_url": "{GoodBed Domain}/mattress-store/sample-retailer-portland-or-96502/",
   "review_url": "{GoodBed Domain}/mattress-store-review/sample-retailer-portland-or-96502/7234/",
   "store_location": "1370 Plaza Blvd, Portland, OR 96502",
   "retailer_name": "Sample Retailer",
   "author": {
       "profile": {
           "short_name": "Randy",
           "home_city": "Montague, OR"}
      }
   },
   "rating": 4,
   "title": "Great quick friendly service",
   "text": "I went looking for a mattress for our master bedroom. Jeff properly introduced himself, asked what I needed, and was able to quickly help me find a great mattress. He was very friendly, courteous, and had a neat personality. It was an excellent experience.",
   "date_reviewed": "2020-07-15T22:00:17.703945",
   "comment_count": 1,
   "comments": [
       {
           "is_official": true,
           "comment": "Thanks for the great feedback, Randy!",
           "user_name": "Brett",
           "submit_date": "2020-07-16T08:10:11.132919",
        }
    ]
}