Data needs

There are two broad approaches to ingesting Good On You ratings data via the Good On You ratings API, each serving a different need.

A. Fetching rating data in bulk

This is the most common way to ingest Good On You ratings data into a database that powers a consumer product or internal tool.

  1. Fetch the data for all brand ratings from the Good On You ratings API (brand listing endpoint)
  2. Import the data to internal systems
  3. Match Good On You ratings to the brand entities in your system (see ‘Brand Name Matching’ below)
  4. Either filter and sort the extracted data in your own systems to update data for select ratings as needed, or refresh the entire rating catalogue in your system on a regular basis (e.g. weekly).
B. Fetching individual ratings

This approach might be preferred if your team has a workflow that first manually identifies brands that you want to get data for. Alternatively it can support a process to check if a rating exists for a brand in your system. We do not recommend fetching rating data in real time responding to client requests.

  1. Fetch data for a single brand by inputting the brand name in the Good On You rating SPI brand search endpoint.
  2. Verify brand entity match (see ‘Brand Name Matching’ below)
  3. Import the rating data for that brand into your internal systems.

*Filtering functionality will soon be added to the brand listing endpoint. Speak to your Good On You account manager to discuss your specific needs.

 

Update frequency

Good On You updates ratings in batches of brands - roughly one batch per month. Each batch will typically contain 100-500 ratings that may be new ratings or “re-rates” of existing ratings.

In that sense, the ratings data is not changing in real time and does not need to be requested in response to real time client requests. 

If you are displaying ratings data for a frequent internal use case or directly showing to users we recommend pulling new data no more than every 24 hrs and no less than every 7 days. Whatever frequency you choose will be the maximum amount of time that the data may be outdated, depending on the timing of a batch update.

If you are using ratings data for a specific regular task (such as updating an internal dashboard for monthly reporting), then we recommend pulling new data at the same regularity as part of that workflow.

 

Brand name matching

Good On You uses the consumer-facing name for a brand. There are cases where a brand uses multiple consumer-facing names and the entity’s name in Good On You data may not match the name in your systems.

You will want to match the right brand rating in Good On You data with the right brand entity in your systems, and ensure that you get rating data for all rated brands in your portfolio, avoiding false positive and false negative matches.

  • False positives - A brand in Good On You’s system has the same or very similar name to a brand in your system and is matched, even though it’s actually a different brand/company. For example, Good On You has two brands rated both named “Mori” (1, 2). If you used the rating for #1, even though the brand in your portfolio is actually #2 that would be a false positive.
  • False negatives - Good On You may have a rating for a brand in your system under a different name. For example, the brand rated in Good On You as “BAPE”, could be in your system under alternate names “Bathing Ape” or “The Bathing Ape”.

The recommended approach is to store the Good On You brand name in your brand records. This way you can get the rating data for that brand name whichever way you pull data from the Good On You API and dashboard. There are three ways you can do that matching:

  1. Provide your Good On You account manager with your list of brand names (and domain URLs if available) and we can match your records to the brand names in Good On You data. We can run this manual process once per quarter.
  2. Run your brand names through the brand search endpoint. You will get the best match brand rating record returned for the brand name in your system. This scenario would require a manual check for false positive matches (to ensure the matched rating is in fact the same brand in your system). You could manage that process internally as frequently as needed with just the new brands that need to be matched to a Good On You brand name (for example only new brands in your portfolio).
  3. On a regular cadence, you can identify new ratings through the history feature of the ratings dashboard or by the lastUpdatedDate field returned with all brand rating records in the API. Your team can then manually match those ratings to any records in your system and add the Good On You brand name to your system’s record.

*A unique ID will soon be added to the API data to account for situations where the brand name changes. Speak to your Good On You account manager to discuss your specific needs.