Provided for information only. Not to be used without a licence granted by Good On You.

Contents

 

Introduction

This documentation is for v3.0 of Good On You's Ratings REST API. The URLs listed in this documentation are relative to https://api.brandlist.goodonyou.eco/.

Other relevant resources before you get started:

This guide outlines usage of the API v3.0 - the latest and recommended version. Guides for previous versions can be found below:

 

Authentication

Your application must have authorisation credentials to be able to use the Brand Listing API. Your API key identifies your project and provides API access. If you do not already have an API key it can be provided by your Good On You account manager.

 

Brand Listing

Returns data for all subscribed Good On You brand rating records. Partners can subscribe to one or more rating verticals (e.g. fashion, beauty). Rating records will be returned for only the verticals the account is subscribed to.


GET {API_SERVER}/v3/brands-listing
API_SERVER: https://api.brandlist.goodonyou.eco/

REQUEST

Headers:
  • Content-Type: application/json
  • X-API-KEY: (As provided)
Query parameters:
  • limit: The maximum number of brands to return per page. Example: 10, Default: 100
  • skip: The offset of the brand at which to begin the response. Example: 100, Default: 0

Filters:

  • vertical: Return all records within one vertical. vertical=fashion is applied by default. vertical=beauty available only for subscribed accounts.
    Example: https://b2b-staging-2079.nodechef.com/v3/brands-listing?vertical=beauty
  • lastRated: Return all rating records that were rated within a defined time period. Uses lte (less than or equal to) and gte (greater than or equal to) parameters. Users can use either one or both.
    https://b2b-staging-2079.nodechef.com/v3/brands-listing?lastUpdatedDate[gte]=2023-01-01&lastUpdatedDate[lte]=2024-04-01
Example:
curl --request GET 'https://api.brandlist.goodonyou.eco/v3/brands-listing?limit=100&skip=500' \
--header 'X-API-Key: <INSERT API KEY>'
--header 'Content-Type: application/json'

 

RESPONSE

total: The total number of listed brands

limit: The limit that was used for these entries. This will be the same as the limit query parameter unless that value exceeds the maximum value allowed. The maximum value is 100.

skip: The 0-based offset of the first entry in this set. This will be the same as the skip query parameter.

data: An array of brands data, sorted by brands’ names

  • name: Brand’s name. 
    Example: “Denham”
  • website: Brand’s website.
    Example: “https://www.denhamthejeanmaker.com/en/home/”
  • size: Brand’s size considering turnover, number of employees, digital signals, being a parent/subsidiary company, etc. Value is either “small” or “large”.
  • headquarters: Name of the country where the brand's headquarters is located. ISO3166 country names are used.
    Example: “Netherlands”
  • vertical: Indicates the vertical methodology that the rating is produced within.
    Example: ["fashion"] or ["beauty"].
  • categories: An array of strings with a maximum size of 3 denoting the most significant product categories the brand sells within the rating vertical. Possible values are:
    • Fashion: “Accessories”, “Activewear”, “Bags”, “Basics & Intimates”, “Bottoms”, “Denim”, “Dresses & Playsuits”, “Jewellery & Watches”, “Maternity”, “Outerwear”, “Shoes”, “Sleepwear”, “Sweaters & Knitwears”, “Swimwears”, “Tops”
    • Beauty: "Face", "Eyes", "Lips", "Nails",  "Skincare", "Haircare", "Suncare", "Bath & Body", "Fragrance", "Dental"
      Example: [ "Bottoms", "Denim", "Tops" ]
  • subcategories: An array of strings indicating subcategories that the brand sells within the rating vertical. Subcategories are child to categories. Response is limited to 7 values. Possible values are:
    • Fashion: "T-Shirts", "Tops & Blouses", "Polos", "Shirts", "Jumpsuits & Playsuits", "Dresses", "Sneakers", "Slippers & Comfort", "Sneakers", "Flats", "Boots", "Sandals", "Heels", "Casual", "Dressy", "Underwear", "Stockings & Tights", "Socks", "Bodysuits", "Lingerie", "Skirts", "Shorts", "Pants", "Denim", "Outdoorwear", "Activewear", "Sportswear", "Swimwear", "Satchels & Totes", "Backpacks", "Handbags", "Wallets & Purses", "Luggage", "Handbag", "Satchels & Totes", "Wallets & Purses", "Ties", "Belts", "Gloves", "Jewellery", "Hair Accessories", "Scarves", "Watches", "Eyewear", "Hats", "Knitwear", "Sweaters", "Hoodies & Sweatshirts", "Hoodies", "Jumpers", "Coats", "Jackets", "Sports Coats & Blazers", "Jackets & Blazers", "Sports Coats & Blazers", "Sleepwear", "Suits", "Uniforms", "Maternity".
    • Beauty: "Foundation", "Powder", "Concealer", "Contour & highlight", "Face primer", "Blush & bronzer", "Setting", "BB,CC,DD cream", "Tinted moisturiser", "Mascara", "Eyeshadow", "Eyeliner", "Eyebrow Gel, Pomade & Wax", "Lash & brow treatments", "Lipstick", "Lip gloss", "Lip liner", "Lip Treatments", "Nail polish", "Nail polish remover", "Nail treatments", "Moisturisers", "Face Washes & Cleansers", "Face Scrubs & Exfoliants", "Masks", "Toners & Mists", "Makeup Remover", "Face Serums & Oils", "Face Wipes", "Acne & Blemish", "Face Treatments", "Shampoo & conditioner", "Hair styling", "Hair colouring", "Hair treatments", "Face Sunscreen", "Body Sunscreen", "Tanning", "Aftersun", "Soap & body wash", "Body Scrubs & Exfoliants", "Bath Soaks & Bubble Bath", "Body Lotions & Body Oils", "Hair removal", "Deodorant", "Hand sanitiser", "Intimate care", "Perfume", "Cologne", "Toothpaste", "Mouthwash"
      Example: [ "Backpacks", "Jumpers", "Polos" ]
  • plusSize: Boolean, indicates if the brand offers plus size fashion clothing.
    Example: [ "true"]
  • segment: The type of apparel the brand sells. Possible values for fashion brands are: “Children”, “Men”, “Women”. Only "Children" is valid for beauty brands. 
    Example: [“Men”, “Women”]
  • price: Brand’s price range indicator denoted by an integer between 1 to 4. 
    Example: 2
  • contact: An object containing the brand’s contact details including name and email, if known.
    Example: { "name": null, "email": "csr@denham.com" }
  • sentence: Brand’s lead sentence as shown in the Good On You mobile App and web Directory.
    Example: “Since 2008, DENHAM has been creating quality garments with low impact.”
  • summary: Brand’s summary explaining their rating, returned in html format. 
    Example: “<p>DENHAM's environment rating is 'it's a start'. It uses some eco-friendly materials including Global Organic Textile Standard (GOTS) cotton. It uses low impact non-toxic dyes in some of its products. It recycles clothing to minimise textile waste. It uses renewable energy in its direct operations but not its supply chain. </p><p> Its labour rating is 'it's a start'. It has a Code of Conduct that covers all of the ILO Four Fundamental Freedoms principles. It sources its final stage of production from countries with medium risk of labour abuse. There is no evidence it ensures payment of a living wage in its supply chain. It traces most of its supply chain. It audits most of the final stage of production. </p><p> Its animal rating is 'not good enough'. It uses leather and wool. It uses down accredited by the Responsible Down Standard. It does not use fur, exotic animal skin, exotic animal hair or angora. </p><p> DENHAM is rated 'It's a start' overall.</p>”
  • parentCompany: The name of the brand’s parent company if the brand is a subsidiary. A null value indicates the brand does not have a parent company.
    Example: null
    Example 2: “Kering”
  • values: An array of strings indicating the “Values” held by a brand. Possible values are: “Eco-Friendly Materials”, “Fairtrade”, “Give back”, “Organic”, “Recycled / Upcycled Materials”, “Vegan”.
    Example: [“Organic”, “Eco-Friendly Materials”]
  • certifications: An array of strings indicating the Certifications held by a brand. Possible values are: “bluesign certified”, “Certified B Corporation”, “Fair Wear Foundation”, “Fairtrade certified”, “Global Organic Textile Standard”, “Global Recycled Standard”, “OEKO-TEX Standard 1000”, “PETA-Approved Vegan”.
    Example: [“Global Recycled Standard”, “Global Organic Textile Standard”, “OEKO-TEX Standard 1000”]
  • overallRating: Brand’s overall rating
    • score: an integer between 1 to 5. Each number corresponds to a label
    • score_out_of_100: a decimal between 0 and 100 indicating the detailed score of the brand
    • label: possible values for the label are: “We avoid”, “Not good enough”, “It’s a start”, “Good”, “Great”
      Example: { "score": 3, “score_out_of_100”: 61.5, "label": "It's a start" }
  • environment: Brand’s environment rating
    • score: an integer between 1 to 5. Each number corresponds to a label
    • score_out_of_100: a decimal between 0 and 100 indicating the detailed score of the brand
    • label: possible values for the label are: “Very poor”, “Not good enough”, “It’s a start”, “Good”, “Great”
      Example: { "score": 2, “score_out_of_100”: 41, "label": "Not good enough" }
  • labour: Brand’s labour rating
    • score: an integer between 1 to 5. Each number corresponds to a label
    • score_out_of_100: a decimal between 0 and 100 indicating the detailed score of the brand
    • label: possible values for the label are: “Very poor”, “Not good enough”, “It’s a start”, “Good”, “Great”
      Example: { "score": 5, “score_out_of_100”: 94.2, "label": "Great" }
  • animal: Brand’s animal rating
    • score: an integer between 0 to 5. Each number corresponds to a label. Score 0 is given when the animal rating is “Not applicable” or “Not assessed”
    • score_out_of_100: a decimal between 0 and 100 indicating the detailed score of the brand
    • label: possible values for the label are: “Not applicable”, “Not assessed”, “Very poor”, “Not good enough”, “It’s a start”, “Good”, “Great”
      Example 1: { "score": 0, “score_out_of_100”: 0, "label": "Not applicable" }
      Example 2: { "score": 3, “score_out_of_100”: 62.4, "label": "It’s a start" }
  • lastUpdatedDate: Latest date that the brand’s ratings are updated/reviewed expressed according to ISO 8601.
    Example: “2021-06-02T00:00:00.000Z”
  • lastRated: Identical to "lastUpdatedDate", renamed to better indicate it represents the date of the most recent rating.
  • lastModified: The date of the last modification to any data in the rating record.
  • directoryUrl: The url of the brand’s page in the Good On You web Directory.
    Example: https://directory.goodonyou.eco/brand/denham

 

Returns a single brand rating record for the best match for the brand name input.
GET {API_SERVER}/v3/brands-listing/{Brand Name}
API_SERVER: https://api.brandlist.goodonyou.eco/

REQUEST

Headers:
  • Content-Type: application/json
  • X-API-KEY: (As provided)
Parameters:

  • The brand name to search which must be URL encoded.

Example:
curl --request GET 'https://api.brandlist.goodonyou.eco/v3/brands-listing/adias' \
--header 'X-API-Key: <INSERT API KEY>'
--header 'Content-Type: application/json'

 

RESPONSE

A single brand record is returned with the exact fields returned for brands in the listing API.

  • name: Brand’s name. 
  • website: Brand’s website.
  • size: Brand’s size considering turnover, number of employees, digital signals, being a parent/subsidiary company, etc. Value is either “small” or “large”.
  • headquarters: Name of the country where the brand's headquarters is located. ISO3166 country names are used.
  • vertical: Indicates the vertical methodology that the rating is produced within.
  • categories: An array of strings with a maximum size of 3 denoting the most significant product categories the brand sells within the rating vertical. Possible values are:
    • Fashion: “Accessories”, “Activewear”, “Bags”, “Basics & Intimates”, “Bottoms”, “Denim”, “Dresses & Playsuits”, “Jewellery & Watches”, “Maternity”, “Outerwear”, “Shoes”, “Sleepwear”, “Sweaters & Knitwears”, “Swimwears”, “Tops”
    • Beauty: "Face", "Eyes", "Lips", "Nails",  "Skincare", "Haircare", "Suncare", "Bath & Body", "Fragrance", "Dental"
  • subcategories: An array of strings indicating subcategories that the brand sells within the rating vertical. Subcategories are child to categories. Response is limited to 7 values. Possible values are:
    • Fashion: "T-Shirts", "Tops & Blouses", "Polos", "Shirts", "Jumpsuits & Playsuits", "Dresses", "Sneakers", "Slippers & Comfort", "Sneakers", "Flats", "Boots", "Sandals", "Heels", "Casual", "Dressy", "Underwear", "Stockings & Tights", "Socks", "Bodysuits", "Lingerie", "Skirts", "Shorts", "Pants", "Denim", "Outdoorwear", "Activewear", "Sportswear", "Swimwear", "Satchels & Totes", "Backpacks", "Handbags", "Wallets & Purses", "Luggage", "Handbag", "Satchels & Totes", "Wallets & Purses", "Ties", "Belts", "Gloves", "Jewellery", "Hair Accessories", "Scarves", "Watches", "Eyewear", "Hats", "Knitwear", "Sweaters", "Hoodies & Sweatshirts", "Hoodies", "Jumpers", "Coats", "Jackets", "Sports Coats & Blazers", "Jackets & Blazers", "Sports Coats & Blazers", "Sleepwear", "Suits", "Uniforms", "Maternity".
    • Beauty: "Foundation", "Powder", "Concealer", "Contour & highlight", "Face primer", "Blush & bronzer", "Setting", "BB,CC,DD cream", "Tinted moisturiser", "Mascara", "Eyeshadow", "Eyeliner", "Eyebrow Gel, Pomade & Wax", "Lash & brow treatments", "Lipstick", "Lip gloss", "Lip liner", "Lip Treatments", "Nail polish", "Nail polish remover", "Nail treatments", "Moisturisers", "Face Washes & Cleansers", "Face Scrubs & Exfoliants", "Masks", "Toners & Mists", "Makeup Remover", "Face Serums & Oils", "Face Wipes", "Acne & Blemish", "Face Treatments", "Shampoo & conditioner", "Hair styling", "Hair colouring", "Hair treatments", "Face Sunscreen", "Body Sunscreen", "Tanning", "Aftersun", "Soap & body wash", "Body Scrubs & Exfoliants", "Bath Soaks & Bubble Bath", "Body Lotions & Body Oils", "Hair removal", "Deodorant", "Hand sanitiser", "Intimate care", "Perfume", "Cologne", "Toothpaste", "Mouthwash"
  • plusSize: Boolean, indicates if the brand offers plus size fashion clothing.
    Example: [ "true"]
  • segment: The type of apparel the brand sells. Possible values for fashion brands are: “Children”, “Men”, “Women”. Only "Children" is valid for beauty brands.
  • segment: The type of apparel the brand sells. Possible values are: “Children”, “Men”, “Women”.
  • price: Brand’s price range indicator denoted by an integer between 1 to 4. 
  • contact: An object containing the brand’s contact details including name and email, if known.
  • sentence: Brand’s lead sentence as shown in the Good On You mobile App and web Directory.
  • summary: Brand’s summary explaining their rating, returned in html format. 
    Example: “<p>DENHAM's environment rating is 'it's a start'. It uses some eco-friendly materials including Global Organic Textile Standard (GOTS) cotton. It uses low impact non-toxic dyes in some of its products. It recycles clothing to minimise textile waste. It uses renewable energy in its direct operations but not its supply chain. </p><p> Its labour rating is 'it's a start'. It has a Code of Conduct that covers all of the ILO Four Fundamental Freedoms principles. It sources its final stage of production from countries with medium risk of labour abuse. There is no evidence it ensures payment of a living wage in its supply chain. It traces most of its supply chain. It audits most of the final stage of production. </p><p> Its animal rating is 'not good enough'. It uses leather and wool. It uses down accredited by the Responsible Down Standard. It does not use fur, exotic animal skin, exotic animal hair or angora. </p><p> DENHAM is rated 'It's a start' overall.</p>”
  • parentCompany: The name of the brand’s parent company if the brand is a subsidiary. A null value indicates the brand does not have a parent company.
  • values: An array of strings indicating the “Values” held by a brand. Possible values are: “Eco-Friendly Materials”, “Fairtrade”, “Give back”, “Organic”, “Recycled / Upcycled Materials”, “Vegan”.
  • certifications: An array of strings indicating the Certifications held by a brand. Possible values are: “bluesign certified”, “Certified B Corporation”, “Fair Wear Foundation”, “Fairtrade certified”, “Global Organic Textile Standard”, “Global Recycled Standard”, “OEKO-TEX Standard 1000”, “PETA-Approved Vegan”.
  • overallRating: Brand’s overall rating
    • score: an integer between 1 to 5. Each number corresponds to a label
    • score_out_of_100: a decimal between 0 and 100 indicating the detailed score of the brand
    • label: possible values for the label are: “We avoid”, “Not good enough”, “It’s a start”, “Good”, “Great”
      Example: { "score": 3, “score_out_of_100”: 61.5, "label": "It's a start" }
  • environment: Brand’s environment rating
    • score: an integer between 1 to 5. Each number corresponds to a label
    • score_out_of_100: a decimal between 0 and 100 indicating the detailed score of the brand
    • label: possible values for the label are: “Very poor”, “Not good enough”, “It’s a start”, “Good”, “Great”
      Example: { "score": 2, “score_out_of_100”: 41, "label": "Not good enough" }
  • labour: Brand’s labour rating
    • score: an integer between 1 to 5. Each number corresponds to a label
    • score_out_of_100: a decimal between 0 and 100 indicating the detailed score of the brand
    • label: possible values for the label are: “Very poor”, “Not good enough”, “It’s a start”, “Good”, “Great”
      Example: { "score": 5, “score_out_of_100”: 94.2, "label": "Great" }
  • animal: Brand’s animal rating
    • score: an integer between 0 to 5. Each number corresponds to a label. Score 0 is given when the animal rating is “Not applicable” or “Not assessed”
    • score_out_of_100: a decimal between 0 and 100 indicating the detailed score of the brand
    • label: possible values for the label are: “Not applicable”, “Not assessed”, “Very poor”, “Not good enough”, “It’s a start”, “Good”, “Great”
      Example 1: { "score": 0, “score_out_of_100”: 0, "label": "Not applicable" }
      Example 2: { "score": 3, “score_out_of_100”: 62.4, "label": "It’s a start" }
  • lastUpdatedDate: Latest date that the brand’s ratings are updated/reviewed expressed according to ISO 8601.
  • lastRated: Identical to "lastUpdatedDate", renamed to better indicate it represents the date of the most recent rating.
  • lastModified: The date of the last modification to any data in the rating record.
  • directoryUrl: The url of the brand’s page in the Good On You web Directory.

 

Response codes

  • 200 - Returns a collection of brands
  • 401 - Returned when the API Key provided in the X-API-KEY header is not recognised or not provided
  • 429 - Returned when the client exceeds the number of API calls in one minute. Rate Limit is 60 API calls per minute. You can check the API rate in the response header via X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
  • 500 - An unexpected error in the server. Please contact Good On You.